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 (with TouchID support 🎉)
• Windows Credential Manager
• Windows Hello-gated encrypted Credential Manager backend
• Secret Service (Gnome Keyring, KWallet)
• KWallet
• Pass
• Passage
• Encrypted file (JWT)
• KeyCtl
• 1Password Connect
• 1Password Service Accounts
• 1Password Desktop Application Integration

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)

To configure TouchId biometrics:

keyring.Config.UseBiometrics = true
keyring.Config.TouchIDAccount = "cc.byteness.aws-vault.biometrics"
keyring.Config.TouchIDService = "aws-vault"

The winhello backend stores encrypted envelopes in Windows Credential Manager. This may sound similar to the wincred backend, but the difference is encryption. Here, we don't store plaintext item data in Credential Manager. It is encrypted with AES-256-GCM, and the content encryption key is wrapped by a Windows Hello / Passport KSP key and unwrapped through an interactive private-key operation.

Upon the first use, a new Passport KSP key is created and stored in the user's protected key store. This operation requires user interaction and Windows Hello authentication. Later, whenever an item is accessed, the content encryption key is unwrapped by the Passport KSP key, which requires Windows Hello authentication again. This means that every access to the stored secrets requires user presence and authentication through Windows Hello (using PIN, fingerprint, face ID, etc.).

This protects against silent reads of the stored Credential Manager blob. It does not protect against malware that can read process memory after a successful unlock, inject into an approved process, or steal credentials after they are handed to a caller.

To use the Windows Hello backend on Windows:

ring, err := keyring.Open(keyring.Config{
  ServiceName: "example",
  AllowedBackends: []keyring.BackendType{
    keyring.WinHelloBackend,
  },
})
if err != nil {
  return err
}

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
./bin/go-test

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 part of ByteNess 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!