keyring provides cross-platform keychain access

July 3, 2026 ยท View on GitHub

https://pkg.go.dev/github.com/tmc/keyring

Keyring provides a common interface to keyring/keychain tools.

License: ISC

Requires Go 1.25 or later.

Currently implemented:

  • OSX
  • SecretService
  • gnome-keychain (via "gnome_keyring" build flag)
  • Windows

Contributions welcome!

Usage example:

  err := keyring.Set("libraryFoo", "jack", "sacrifice")
  password, err := keyring.Get("libraryFoo", "jack")
  fmt.Println(password) //Output: sacrifice
  err = keyring.Delete("libraryFoo", "jack")

Linux

Linux requirements:

SecretService provider

  • dbus

The default SecretService provider is pure Go and preferred. The gnome_keyring build tag selects the opt-in cgo/libsecret provider for environments that specifically require libsecret.

gnome-keychain provider

  • gnome-keychain headers
  • Ubuntu/Debian: libsecret-dev
  • Fedora: libsecret-devel
  • Archlinux: libsecret

Tests on Linux:

 $ go test github.com/tmc/keyring
 $ # for gnome-keyring provider
 $ go test -tags gnome_keyring github.com/tmc/keyring

Security considerations

  • macOS: the secret is written to /usr/bin/security over stdin (base64-encoded so any byte value survives), so it is not exposed in the process argument list.
  • Linux SecretService: sessions are opened with "plain" negotiation, so secrets traverse the user's D-Bus session bus unencrypted. A local process able to snoop that bus could read them. A future implementation should use dh-ietf-1024-sha256 session encryption.
  • File provider: security depends on passphrase strength. KEYRING_PASSPHRASE can leak to child processes and process listings; prefer FileOptions.Passphrase when using NewFileProvider.