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 ¶
Examples ¶
Constants ¶
This section is empty.
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
Functions ¶
This section is empty.
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 ¶
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)
}
Output:
type Metadata ¶
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 ¶
PromptFunc is a function used to prompt the user for a password
Source Files
Directories