keyring

README

Keyring

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

• macOS Keychain
• Windows Credential Manager
• Secret Service (Gnome Keyring, KWallet)
• KWallet
• Pass
• Encrypted file (JWT)
• KeyCtl

Usage

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

Testing

Vagrant is used to create linux and windows test environments.

# Start vagrant
vagrant up

# Run go tests on all platforms
./bin/go-test

Contributing

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

Documentation

Overview

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

Index

• Constants
• Variables
• func ExpandTilde(dir string) (string, error)
• func GetKeyringIDForScope(scope string) (int32, error)
• func GetPermissions(process, user, group, others uint32) uint32
• func TerminalPrompt(prompt string) (string, error)
• type ArrayKeyring
  • func NewArrayKeyring(initial []Item) *ArrayKeyring
  • func (k *ArrayKeyring) Get(key string) (Item, error)
  • func (k *ArrayKeyring) GetMetadata(_ string) (Metadata, error)
  • func (k *ArrayKeyring) Keys() ([]string, error)
  • func (k *ArrayKeyring) Remove(key string) error
  • func (k *ArrayKeyring) Set(i Item) error
• type BackendType
  • func AvailableBackends() []BackendType
• type Config
• type Item
• type Keyring
  • func Open(cfg Config) (Keyring, error)
• type Metadata
• type PromptFunc
  • func FixedStringPrompt(value string) PromptFunc

Examples

• Open

Constants

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)

	KEYCTL_PERM_OTHERS  = 0
	KEYCTL_PERM_GROUP   = 8
	KEYCTL_PERM_USER    = 16
	KEYCTL_PERM_PROCESS = 24
)

Variables

var (
	// Debug specifies whether to print debugging output.
	Debug bool
)

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.

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.

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

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

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

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

Functions

func ExpandTilde

func ExpandTilde(dir string) (string, error)

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

func GetKeyringIDForScope

func GetKeyringIDForScope(scope string) (int32, error)

GetKeyringIDForScope get the keyring ID for a given scope.

func GetPermissions

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

GetPermissions constructs the permission mask from the elements.

func TerminalPrompt

func TerminalPrompt(prompt string) (string, error)

Types

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

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.

Example

package main

import (
	"log"

	"github.com/99designs/keyring"
)

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

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

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

type Metadata

type Metadata struct {
	*Item
	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

func FixedStringPrompt(value string) PromptFunc