package module
v1.2.2 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Dec 19, 2022 License: MIT Imports: 18 Imported by: 403



Build Status Documentation

Keyring provides a common interface to a range of secure credential storage services. Originally developed as part of AWS Vault, a command line tool for securely managing AWS access from developer workstations.

Currently Keyring supports the following backends


The short version of how to use keyring is shown below.

ring, _ := keyring.Open(keyring.Config{
  ServiceName: "example",

_ = ring.Set(keyring.Item{
	Key: "foo",
	Data: []byte("secret-bar"),

i, _ := ring.Get("foo")

fmt.Printf("%s", i.Data)

For more detail on the API please check the keyring godocs


Vagrant is used to create linux and windows test environments.

# Start vagrant
vagrant up

# Run go tests on all platforms


Contributions to the keyring package are most welcome from engineers of all backgrounds and skill levels. In particular the addition of extra backends across popular operating systems would be appreciated.

This project will adhere to the Go Community Code of Conduct in the github provided discussion spaces, with the moderators being the 99designs engineering team.

To make a contribution:

  • Fork the repository
  • Make your changes on the fork
  • Submit a pull request back to this repo with a clear description of the problem you're solving
  • Ensure your PR passes all current (and new) tests
  • Ideally verify that aws-vault works with your changes (optional)

...and we'll do our best to get your work merged in



Package keyring provides a uniform API over a range of desktop credential storage engines.




View Source
const (
	KEYCTL_PERM_VIEW    = uint32(1 << 0)
	KEYCTL_PERM_READ    = uint32(1 << 1)
	KEYCTL_PERM_WRITE   = uint32(1 << 2)
	KEYCTL_PERM_SEARCH  = uint32(1 << 3)
	KEYCTL_PERM_LINK    = uint32(1 << 4)
	KEYCTL_PERM_SETATTR = uint32(1 << 5)
	KEYCTL_PERM_ALL     = uint32((1 << 6) - 1)



View Source
var (
	// Debug specifies whether to print debugging output.
	Debug bool
View Source
var ErrKeyNotFound = errors.New("The specified item could not be found in the keyring")

ErrKeyNotFound is returned by Keyring Get when the item is not on the keyring.

View Source
var ErrMetadataNeedsCredentials = errors.New("The keyring backend requires credentials for metadata access")

ErrMetadataNeedsCredentials is returned when Metadata is called against a backend which requires credentials even to see metadata.

View Source
var ErrMetadataNotSupported = errors.New("The keyring backend does not support metadata access")

ErrMetadataNotSupported is returned when Metadata is not available for the backend.

View Source
var ErrNoAvailImpl = errors.New("Specified keyring backend not available")

ErrNoAvailImpl is returned by Open when a backend cannot be found.


func ExpandTilde added in v1.2.1

func ExpandTilde(dir string) (string, error)

ExpandTilde will expand tilde (~/ or ~\ depending on OS) for the user home directory.

func GetKeyringIDForScope added in v1.2.0

func GetKeyringIDForScope(scope string) (int32, error)

GetKeyringIDForScope get the keyring ID for a given scope.

func GetPermissions added in v1.2.0

func GetPermissions(process, user, group, others uint32) uint32

GetPermissions constructs the permission mask from the elements.

func TerminalPrompt added in v1.2.0

func TerminalPrompt(prompt string) (string, error)


type ArrayKeyring

type ArrayKeyring struct {
	// contains filtered or unexported fields

ArrayKeyring is a mock/non-secure backend that meets the Keyring interface. It is intended to be used to aid unit testing of code that relies on the package. NOTE: Do not use in production code.

func NewArrayKeyring

func NewArrayKeyring(initial []Item) *ArrayKeyring

NewArrayKeyring returns an ArrayKeyring, optionally constructed with an initial slice of items.

func (*ArrayKeyring) Get

func (k *ArrayKeyring) Get(key string) (Item, error)

Get returns an Item matching Key.

func (*ArrayKeyring) GetMetadata added in v1.1.0

func (k *ArrayKeyring) GetMetadata(_ string) (Metadata, error)

func (*ArrayKeyring) Keys

func (k *ArrayKeyring) Keys() ([]string, error)

Keys provides a slice of all Item keys on the Keyring.

func (*ArrayKeyring) Remove

func (k *ArrayKeyring) Remove(key string) error

Remove will delete an Item from the Keyring.

func (*ArrayKeyring) Set

func (k *ArrayKeyring) Set(i Item) error

Set will store an item on the mock Keyring.

type BackendType

type BackendType string

BackendType is an identifier for a credential storage service.

const (
	InvalidBackend       BackendType = ""
	SecretServiceBackend BackendType = "secret-service"
	KeychainBackend      BackendType = "keychain"
	KeyCtlBackend        BackendType = "keyctl"
	KWalletBackend       BackendType = "kwallet"
	WinCredBackend       BackendType = "wincred"
	FileBackend          BackendType = "file"
	PassBackend          BackendType = "pass"

All currently supported secure storage backends.

func AvailableBackends

func AvailableBackends() []BackendType

AvailableBackends provides a slice of all available backend keys on the current OS.

type Config

type Config struct {
	// AllowedBackends is a whitelist of backend providers that can be used. Nil means all available.
	AllowedBackends []BackendType

	// ServiceName is a generic service name that is used by backends that support the concept
	ServiceName string

	// MacOSKeychainNameKeychainName is the name of the macOS keychain that is used
	KeychainName string

	// KeychainTrustApplication is whether the calling application should be trusted by default by items
	KeychainTrustApplication bool

	// KeychainSynchronizable is whether the item can be synchronized to iCloud
	KeychainSynchronizable bool

	// KeychainAccessibleWhenUnlocked is whether the item is accessible when the device is locked
	KeychainAccessibleWhenUnlocked bool

	// KeychainPasswordFunc is an optional function used to prompt the user for a password
	KeychainPasswordFunc PromptFunc

	// FilePasswordFunc is a required function used to prompt the user for a password
	FilePasswordFunc PromptFunc

	// FileDir is the directory that keyring files are stored in, ~/ is resolved to the users' home dir
	FileDir string

	// KeyCtlScope is the scope of the kernel keyring (either "user", "session", "process" or "thread")
	KeyCtlScope string

	// KeyCtlPerm is the permission mask to use for new keys
	KeyCtlPerm uint32

	// KWalletAppID is the application id for KWallet
	KWalletAppID string

	// KWalletFolder is the folder for KWallet
	KWalletFolder string

	// LibSecretCollectionName is the name collection in secret-service
	LibSecretCollectionName string

	// PassDir is the pass password-store directory, ~/ is resolved to the users' home dir
	PassDir string

	// PassCmd is the name of the pass executable
	PassCmd string

	// PassPrefix is a string prefix to prepend to the item path stored in pass
	PassPrefix string

	// WinCredPrefix is a string prefix to prepend to the key name
	WinCredPrefix string

Config contains configuration for keyring.

type Item

type Item struct {
	Key         string
	Data        []byte
	Label       string
	Description string

	// Backend specific config
	KeychainNotTrustApplication bool
	KeychainNotSynchronizable   bool

Item is a thing stored on the keyring.

type Keyring

type Keyring interface {
	// Returns an Item matching the key or ErrKeyNotFound
	Get(key string) (Item, error)
	// Returns the non-secret parts of an Item
	GetMetadata(key string) (Metadata, error)
	// Stores an Item on the keyring
	Set(item Item) error
	// Removes the item with matching key
	Remove(key string) error
	// Provides a slice of all keys stored on the keyring
	Keys() ([]string, error)

Keyring provides the uniform interface over the underlying backends.

func Open

func Open(cfg Config) (Keyring, error)

Open will open a specific keyring backend.

package main

import (


func main() {
	// Use the best keyring implementation for your operating system
	kr, err := keyring.Open(keyring.Config{
		ServiceName: "my-service",
	if err != nil {

	v, err := kr.Get("llamas")
	if err != nil {

	log.Printf("llamas was %v", v)

type Metadata added in v1.1.0

type Metadata struct {
	ModificationTime time.Time

Metadata is information about a thing stored on the keyring; retrieving metadata must not require authentication. The embedded Item should be filled in with an empty Data field. It's allowed for Item to be a nil pointer, indicating that all we have is the timestamps.

type PromptFunc

type PromptFunc func(string) (string, error)

PromptFunc is a function used to prompt the user for a password.

func FixedStringPrompt added in v1.2.0

func FixedStringPrompt(value string) PromptFunc


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL