README
¶
Keyring
Securely store secrets.
This package provides a cross platform keyring using system APIs (macOS/keychain, Windows/wincred, Linux/SecretService) or filesystem, protected by a password derived key.
For more details visit keys.pub.
Example
// Initialize Keyring.
// You can use keyring.System, keyring.SystemOrFS, keyring.FS, keyring.Mem, git.NewRepository.
kr, err := keyring.New(keyring.System("AppName"))
if err != nil {
log.Fatal(err)
}
// Setup keyring auth.
if err := kr.UnlockWithPassword("mypassword", true); err != nil {
log.Fatal(err)
}
// Create item.
// Item IDs are NOT encrypted.
item := keyring.NewItem("id1", []byte("mysecret"), "", time.Now())
if err := kr.Create(item); err != nil {
log.Fatal(err)
}
// Get item.
out, err := kr.Get("id1")
if err != nil {
log.Fatal(err)
}
fmt.Printf("secret: %s\n", string(out.Data))
// List items.
items, err := kr.List()
if err != nil {
log.Fatal(err)
}
for _, item := range items {
fmt.Printf("%s: %v\n", item.ID, string(item.Data))
}
macOS
The Keychain API via the github.com/keybase/go-keychain package.
Windows
The Windows Credential Manager API via the github.com/danieljoos/wincred package.
Linux
The SecretService dbus interface via the github.com/zalando/go-keyring package. The SecretService dbus interface, which is provided by GNOME Keyring.
We are still exploring whether to use kwallet or libsecret directly for linux environments that support that instead. In the meantime, you can fall back to the FS based keyring.
FS
There is a filesystem based keyring for OS' that have no system keyring.
Mem
The is an in memory keyring for ephemeral keys or for testing.
Git
A git backed keyring allowing for backup/sync, see github.com/keys-pub/keysd/git.
Documentation
¶
Overview ¶
Package keyring provides a cross-platform secure keyring.
Index ¶
- Constants
- Variables
- func Backup(path string, st Store, now time.Time) error
- func Copy(from Store, to Store, opt ...CopyOption) ([]string, error)
- func Restore(path string, st Store) error
- func SetLogger(l Logger)
- type AuthType
- type CopyOption
- type CopyOptions
- type CreateEvent
- type Event
- type IDsOption
- type IDsOptions
- type Item
- type Keyring
- func (k *Keyring) Create(item *Item) error
- func (k *Keyring) Delete(id string) (bool, error)
- func (k *Keyring) Deprovision(id string) (bool, error)
- func (k *Keyring) Exists(id string) (bool, error)
- func (k *Keyring) Get(id string) (*Item, error)
- func (k *Keyring) IDs(opts ...IDsOption) ([]string, error)
- func (k *Keyring) List(opts ...ListOption) ([]*Item, error)
- func (k *Keyring) Lock() error
- func (k *Keyring) MasterKey() SecretKey
- func (k *Keyring) Provision(key SecretKey, provision *Provision) error
- func (k *Keyring) Provisions() ([]*Provision, error)
- func (k *Keyring) Reset() error
- func (k *Keyring) Salt() ([]byte, error)
- func (k *Keyring) SaveProvision(provision *Provision) error
- func (k *Keyring) SetMasterKey(mk SecretKey)
- func (k *Keyring) Setup(key SecretKey, provision *Provision) error
- func (k *Keyring) Status() (Status, error)
- func (k *Keyring) Store() Store
- func (k *Keyring) Subscribe(topic string) chan Event
- func (k *Keyring) Unlock(key SecretKey) (*Provision, error)
- func (k *Keyring) UnlockWithPassword(password string, setup bool) error
- func (k *Keyring) Unsubscribe(topic string)
- func (k *Keyring) Update(id string, b []byte) error
- type ListOption
- type ListOptions
- type LockEvent
- type LogLevel
- type Logger
- type Option
- type Options
- type Provision
- type SecretKey
- type Status
- type Store
- type UnlockEvent
- type UpdateEvent
Examples ¶
Constants ¶
const HiddenPrefix = "."
HiddenPrefix are hidden items.
const ReservedPrefix = "#"
ReservedPrefix are reserved items.
Variables ¶
var ErrAlreadySetup = errors.New("keyring is already setup")
ErrAlreadySetup if already setup.
var ErrInvalidAuth = errors.New("invalid keyring auth")
ErrInvalidAuth if auth is invalid.
var ErrItemAlreadyExists = errors.New("keyring item already exists")
ErrItemAlreadyExists if item already exists trying to create.
var ErrItemNotFound = errors.New("keyring item not found")
ErrItemNotFound if item not found when trying to update.
var ErrItemValueTooLarge = errors.New("keyring item value is too large")
ErrItemValueTooLarge is item value is too large. Item.ID is max of 254 bytes. Item.Type is max of 32 bytes. Item.Data is max of 2048 bytes.
var ErrLocked = errors.New("keyring is locked")
ErrLocked if no keyring key is set.
Functions ¶
func Copy ¶
func Copy(from Store, to Store, opt ...CopyOption) ([]string, error)
Copy data from a keyring.Store to another keyring.Store. It copies raw data, it doesn't need to be unlocked. Doesn't overwrite existing data.
Types ¶
type CopyOption ¶
type CopyOption func(*CopyOptions)
CopyOption ...
func SkipExisting ¶
func SkipExisting() CopyOption
SkipExisting to skip existing entries, otherwise error.
type IDsOptions ¶
IDsOptions ...
type Item ¶ added in v0.1.18
type Item struct {
// ID for item. IDs are NOT encrypted.
ID string `msgpack:"id"`
// Type for item data.
Type string `msgpack:"typ"`
// Data for item.
Data []byte `msgpack:"dat"`
// CreatedAt when item was created.
CreatedAt time.Time `msgpack:"cts"`
}
Item is a keyring entry.
func DecryptItem ¶
DecryptItem returns Item from bytes.
func List ¶
func List(st Store, key SecretKey, opts ...ListOption) ([]*Item, error)
List items from Store.
type Keyring ¶
type Keyring struct {
// contains filtered or unexported fields
}
Keyring stores encrypted keyring items.
func New ¶
New creates a new Keyring with backing Store.
Use keyring.System for the default system Store. On macOS this is the Keychain, on Windows wincred and linux SecretService.
Use keyring.SystemOrFS for the default system Store or fallback to FS. Use keyring.Mem for testing or ephemeral keys. Use keyring.FS for filesystem based keyring.
Example ¶
package main
import (
"fmt"
"log"
"time"
"github.com/keys-pub/keys/keyring"
)
func main() {
// Initialize Keyring.
// You can use keyring.System(service), keyring.SystemOrFS(service), keyring.FS(service, dir), or keyring.Mem().
kr, err := keyring.New(keyring.SystemOrFS("AppName"))
if err != nil {
log.Fatal(err)
}
// Remove this Reset() if you want to keep the Keyring.
defer func() { _ = kr.Reset() }()
// Setup keyring auth.
if err := kr.UnlockWithPassword("mypassword", true); err != nil {
log.Fatal(err)
}
// Create item.
// Item IDs are NOT encrypted.
item := keyring.NewItem("id1", []byte("mysecret"), "", time.Now())
if err := kr.Create(item); err != nil {
log.Fatal(err)
}
// Get item.
out, err := kr.Get("id1")
if err != nil {
log.Fatal(err)
}
fmt.Printf("secret: %s\n", string(out.Data))
// List items.
items, err := kr.List()
if err != nil {
log.Fatal(err)
}
for _, item := range items {
fmt.Printf("%s: %v\n", item.ID, string(item.Data))
}
}
Output: secret: mysecret id1: mysecret
func NewMem ¶
NewMem returns an in memory Keyring useful for testing or ephemeral keys. The Keyring is unlocked (setup with a random key). If setup is true, the mem Keyring will be setup with a random key.
func (*Keyring) Deprovision ¶
Deprovision auth. Doesn't require Unlock().
func (*Keyring) List ¶
func (k *Keyring) List(opts ...ListOption) ([]*Item, error)
List items. Requires Unlock(). Items with ids that start with "." or "#" are not returned by List. If you need to list IDs only, see Keyring.IDs.
func (*Keyring) MasterKey ¶
MasterKey returns master key, if unlocked. It's not recommended to use this key for anything other than possibly deriving new keys.
func (*Keyring) Provisions ¶
Provisions are currently provisioned auth. Doesn't require Unlock().
func (*Keyring) Salt ¶
Salt is default salt value, generated on first access and persisted until Reset(). This salt value is not encrypted in the keyring. Doesn't require Unlock().
func (*Keyring) SaveProvision ¶
SaveProvision for auth methods that need to store registration data before key is available (for example, FIDO2 hmac-secret).
func (*Keyring) SetMasterKey ¶
SetMasterKey directly sets the master key. If the key is wrong this could leave the keyring in a weird state and should only be used in special circumstances. You probably want to use Setup or Unlock instead.
func (*Keyring) Setup ¶
Setup auth, if no auth exists. Returns ErrAlreadySetup if already setup. Doesn't require Unlock().
func (*Keyring) UnlockWithPassword ¶
UnlockWithPassword unlocks keyring with a password. If setup is true, we are setting up the keyring auth for the first time. This is a convenience method, calling Setup or Unlock with KeyForPassword using the keyring#Salt.
type Logger ¶
type Logger interface {
Debugf(format string, args ...interface{})
Infof(format string, args ...interface{})
Warningf(format string, args ...interface{})
Errorf(format string, args ...interface{})
Fatalf(format string, args ...interface{})
}
Logger interface used in this package.
type Provision ¶
type Provision struct {
ID string `msgpack:"id"`
Type AuthType `msgpack:"type"`
CreatedAt time.Time `msgpack:"cts"`
AAGUID string `msgpack:"aaguid"`
Salt []byte `msgpack:"salt"`
NoPin bool `msgpack:"nopin"`
}
Provision is unencrypted provision and parameters used by client auth.
func NewProvision ¶
NewProvision creates a new provision.
type Store ¶
type Store interface {
// Name of the Store implementation (keychain, wincred, secret-service, mem, fs, git).
Name() string
// Get bytes.
Get(id string) ([]byte, error)
// Set bytes.
Set(id string, data []byte) error
// Delete bytes.
Delete(id string) (bool, error)
// List IDs.
IDs(opts ...IDsOption) ([]string, error)
// Exists returns true if exists.
Exists(id string) (bool, error)
// Reset removes all items.
Reset() error
}
Store is the interface that a Keyring uses to save data.
func NewSystemOrFS ¶
NewSystemOrFS returns system keyring store or FS if unavailable. On linux, if dbus is not available, uses the filesystem at ~/.keyring.
type UnlockEvent ¶
type UnlockEvent struct {
Provision *Provision
}
UnlockEvent when keyring is unlocked.
Source Files
Directories