keys: Index | Examples | Files

package keyring

import ""



Package Files

auth.go fs.go item.go keyring.go keyring_linux.go log.go mem.go secretbox.go


var ErrInvalidAuth = errors.New("invalid keyring auth")

ErrInvalidAuth if auth is invalid.

var ErrLocked = errors.New("keyring is locked")

ErrLocked if no keyring key is set.

var ErrNotAnItem = errors.New("not an encoded keyring item")

ErrNotAnItem if value in keyring is not an encoded keyring item. TODO: Add test.

func SetLogger Uses

func SetLogger(l Logger)

SetLogger sets package log

func UnlockWithPassword Uses

func UnlockWithPassword(kr Keyring, password string) error

UnlockWithPassword unlocks a Keyring with a password.

type Auth Uses

type Auth interface {
    Key() SecretKey

Auth ...

func NewKeyAuth Uses

func NewKeyAuth(key SecretKey) Auth

NewKeyAuth returns auth with a key.

func NewPasswordAuth Uses

func NewPasswordAuth(password string, salt []byte) (Auth, error)

NewPasswordAuth generates key from password, salt and secret key.

type Item Uses

type Item struct {
    ID   string
    Type string
    // contains filtered or unexported fields

Item is a keyring entry.

func DecodeItem Uses

func DecodeItem(b []byte, secretKey SecretKey) (*Item, error)

DecodeItem returns Item from bytes. If encrypted and secret key is specified, it will have the decrypted data and will return (*Item, true, nil).

func NewItem Uses

func NewItem(id string, secret Secret, typ string) *Item

NewItem creates an Item with a secret.

func (*Item) Marshal Uses

func (i *Item) Marshal(secretKey SecretKey) ([]byte, error)

Marshal to bytes. If secretKey is specified we store the data encrypted.

func (*Item) Secret Uses

func (i *Item) Secret() *Secret

Secret ...

func (*Item) SecretData Uses

func (i *Item) SecretData() []byte

SecretData ...

func (*Item) SecretDataFor Uses

func (i *Item) SecretDataFor(name string) []byte

SecretDataFor ...

func (*Item) SecretFor Uses

func (i *Item) SecretFor(name string) *Secret

SecretFor returns a named secret.

func (*Item) SetSecret Uses

func (i *Item) SetSecret(val Secret)

SetSecret sets the secret.

func (*Item) SetSecretFor Uses

func (i *Item) SetSecretFor(name string, val Secret)

SetSecretFor sets a named secret.

type Keyring Uses

type Keyring interface {
    // Get item.
    // Requires Unlock().
    Get(id string) (*Item, error)

    // Set item.
    // Requires Unlock().
    Set(i *Item) error

    // Delete item.
    // Doesn't require Unlock().
    Delete(id string) (bool, error)

    // List items.
    // Requires Unlock().
    // Items with ids that start with "." are not returned by List.
    List(opts *ListOpts) ([]*Item, error)

    // IDs.
    // Doesn't require Unlock().
    // Items with ids that start with "." are not returned by IDs.
    IDs(prefix string) ([]string, error)

    // Exists returns true it has the id.
    // Doesn't require Unlock().
    Exists(id string) (bool, error)

    // Unlock with auth.
    Unlock(auth Auth) error

    // Lock.
    Lock() error

    // Salt is default salt value, generated on first access and persisted
    // until ResetAuth() or Reset().
    // This salt value is not encrypted in the keyring.
    // Doesn't require Unlock().
    Salt() ([]byte, error)

    // Authed returns true if Keyring has ever been unlocked.
    // Doesn't require Unlock().
    Authed() (bool, error)

    // Reset keyring.
    // Doesn't require Unlock().
    Reset() error

Keyring defines an interface for accessing keyring items.

func NewFS Uses

func NewFS(service string, dir string) (Keyring, error)

NewFS creates a Keyring using the local filesystem. This is an alternate Keyring implementation that is platform agnostic.

func NewKeyring Uses

func NewKeyring(service string, st Store) (Keyring, error)

NewKeyring 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.

On other environments, you can use a filesystem backed Store by specifying keyring.FS(dir).


kr, err := keyring.NewKeyring("AppName", keyring.SystemOrFS())
if err != nil {
// Remove this Reset() if you want to keep the Keyring
defer func() { _ = kr.Reset() }()
// Unlock keyring (on first unlock, sets the password)
if err := keyring.UnlockWithPassword(kr, "mypassword"); err != nil {

// Save secret
secret := keyring.NewSecret([]byte("mysecret"))
item := keyring.NewItem("id1", secret, "")

if err := kr.Set(item); err != nil {

// Get secret
out, err := kr.Get("id1")
if err != nil {
fmt.Printf("secret: %s\n", string(out.SecretData()))

// List secrets
items, err := kr.List(nil)
if err != nil {
for _, item := range items {
    fmt.Printf("%s: %v\n", item.ID, string(item.SecretData()))


secret: mysecret
id1: mysecret

func NewMem Uses

func NewMem() Keyring

NewMem returns an in memory Keyring useful for testing or ephemeral keys. The Keyring is unlocked (setup with a random key).

type ListOpts Uses

type ListOpts struct {
    Types []string

ListOpts ...

type Logger Uses

type Logger interface {
    Debugf(format string, args ...interface{})
    Infof(format string, args ...interface{})
    Warningf(format string, args ...interface{})
    Errorf(format string, args ...interface{})

Logger interface used in this package

type Secret Uses

type Secret struct {
    Data []byte `json:"data"`

Secret for item.

func NewSecret Uses

func NewSecret(b []byte) Secret

NewSecret returns a new secret with data.

func NewStringSecret Uses

func NewStringSecret(s string) Secret

NewStringSecret returns a new secret for a string.

func (*Secret) String Uses

func (s *Secret) String() string

String returns secret data as a string.

type SecretKey Uses

type SecretKey *[32]byte

SecretKey for encrypting items.

type Store Uses

type Store interface {
    Get(service string, id string) ([]byte, error)
    Set(service string, id string, data []byte, typ string) error
    Delete(service string, id string) (bool, error)

    IDs(service string, prefix string, showHidden bool, showReserved bool) ([]string, error)
    List(service string, key SecretKey, opts *ListOpts) ([]*Item, error)
    Exists(service string, id string) (bool, error)
    Reset(service string) error

Store is the cross platform keyring interface that a Keyring uses.

func FS Uses

func FS(dir string) (Store, error)

FS returns keyring.Store backed by the filesystem.

func NewMemStore Uses

func NewMemStore() Store

NewMemStore returns in memory keyring.Store.

func System Uses

func System() Store

System returns system keyring store.

func SystemOrFS Uses

func SystemOrFS() Store

System returns system keyring store or FS if unavailable. On linux, if dbus is not available, uses the filesystem at ~/.keyring.

Package keyring imports 18 packages (graph) and is imported by 2 packages. Updated 2020-04-09. Refresh now. Tools for package owners.