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

The cross-platform backends compile into every build, whether or not you use them, along with their dependency trees. If you know at build time that you don't need a backend, an opt-out build tag excludes it (and its dependencies) from compilation:

go build -tags keyring_no1password ./...

The platform-specific backends (keychain, wincred, winhello, secret-service, kwallet, keyctl) are already gated by GOOS constraints and need no tags. Default builds (no tags) are unaffected. An excluded backend is simply absent from AvailableBackends(), and requesting it explicitly returns ErrNoAvailImpl — the same behavior as a backend that's unavailable on the current platform. The BackendType constants and Config fields are always present, so there is no API change under any tag.

Vagrant is used to create linux and windows test environments.

# Start vagrant
vagrant up

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

Report issues/questions/feature requests on in the issues section.

Full contributing guidelines are covered here.

• Marko Bevc
• Full contributors list