keyring

README

Keyring

Keyring provides utility functions for and 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/OSX Keychain
• Windows credential store
• Pass
• Secret Service
• KDE Wallet
• Encrypted File

Installing

go get github.com/99designs/keyring

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

Development & 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

See project homepage at https://github.com/99designs/keyring for more background

Index

• Variables
• 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

Examples

• Open

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 ErrNoAvailImpl = errors.New("Specified keyring backend not available")

ErrNoAvailImpl is returned by Open when a backend cannot be found

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

A BackendType is an identifier for a credential storage service

const (
	InvalidBackend       BackendType = ""
	SecretServiceBackend BackendType = "secret-service"
	KeychainBackend      BackendType = "keychain"
	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 home dir
	FileDir string

	// 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
	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",
	})

	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