Cross-platform system keychain access library for Go.
This package is largely based on the node-keytar package, though the GNOME Keyring implementation has been modified to work on older GNOME versions that don't provide the simple password storage API.
This package is designed to add, get, replace, and delete passwords in the user's default keychain. On OS X, passwords are managed by the Keychain. On Linux, passwords are managed by GNOME Keyring. On Windows, passwords are managed by Credential Vault.
The module is currently tested1 on the following platforms:
Windows | OS X/Linux |
---|---|
On each platform, you'll need a Go installation that supports cgo compilation. On Windows, this means that you'll need MinGW-w64, because MinGW doesn't support the Windows Credential Vault API and, even if it did, it doesn't support 64-bit compilation. On other platforms, Go should just use the system compiler for cgo compilation.
All library dependencies are met by the system on Windows and OS X.
On Linux, you need to ensure that the GNOME Keyring development package is installed. On Ubuntu systems, do:
sudo apt-get install libgnome-keyring-dev
On Red Hat systems, do:
sudo yum install gnome-keyring-devel
For all other Linux distributions, consult your package manager.
The interface to the platform's default keychain is provided by the Keychain
interface. To get the appropriate Keychain
instance for the current platform,
do:
keychain, err := keytar.GetKeychain()
if err != nil {
// Handle error (most likely ErrUnsupported)
}
Then you can add a password:
// NOTE: AddPassword will not overwrite a password - use
// keytar.ReplacePassword for that
err = keychain.AddPassword("example.org", "George", "$eCr37")
if err != nil {
// Handle error
}
Query a password:
password, err := keychain.GetPassword("example.org", "George")
if err != nil {
// Handle error
}
// Use password
Replace a password:
// NOTE: This is a module-level function, not part of the keychain interface
err = keytar.ReplacePassword(
keychain,
"example.org",
"George",
"M0r3-$eCr37",
)
if err != nil {
// Handle error
}
Or delete a password:
err = keytar.DeletePassword("example.org", "George")
if err != nil {
// Handle error (you can probably ignore keytar.ErrNotFound)
}
That's it.
Note that all strings passed to the interface must be UTF-8 encoded without any
null bytes. The GetPassword
method may return a non-UTF-8 string if the entry
was created by another program not enforcing this constraint.
- Create GoDoc entry.
- Move Linux convenience C code out of the Go source file (it's a bit long), or, even better, switch to a more modern keychain system on Linux, like libsecret.
- Make APIs try to extract more concise error information from the underlying
platform APIs. At the moment, many failures are classified as
ErrUnknown
, but we could probably figure out the real error and expand our list of error codes. - Figure out if Go has a secure fallback that we could use somewhere in its crypto libraries.
- Jacob Howard (@havoc-io)
- Jeffrey Hulten (@jhulten)