Linux Keyring
Store and Retrieve Secrets from the Linux Keyring
Overview
Keyring is a Linux security feature that stores sensitive information, such as passwords and secrets, and allows applications to securely access it.
Keeper provides a utility, the Linux Keyring Utility, that interacts with the native Linux APIs to store and retrieve secrets from the Keyring using the Secret Service API. This utility can be used by any integration, plugin, or code base to store and retrieve credentials, secrets, and passwords in any Linux Keyring simply and natively.
The code base for the Linux Keyring Utility can be found here:
The binary needed to use the above utility can be found here:
To use the Linux Keyring Utility, you can either
deploy the pre-built binary from the releases page
or import it into your code base.
Both use cases are covered below.
Linux Keyring Utility
The Linux Keyring Utility gets and sets secrets in a Linux Keyring using the D-Bus Secret Service.
It has been tested with GNOME Keyring and KDE Wallet Manager. It should work with any implementation of the D-Bus Secrets Service.
Interface
There are two packages, dbus_secrets
and secret_collection
. The secret_collection
object uses the functions in dbus_secrets
. It unifies the D-Bus Connection, Session and Collection Service objects to offer a simple get/set/delete interface that the CLI uses.
Usage - Importing it into your codebase
The Go Language API has offers Get()
, Set()
and Delete()
methods. The first two accept and return string
data.
Example (get)
The .DefaultCollection()
returns whatever collection the default alias refers to. It will generate an error if the default alias is not set. It usually points to the login keyring. Most Linux Keyring interfaces allow the user to set it.
The .NamedCollection(string)
method provides access to collections by name.
Example (set)
Set takes the data as a parameter and only returns an error or nil
on success. It does not restrict the content or length of the secret data.
Usage - Binary Interface (CLI)
The Linux binary supports three subcommands:
get
set
del
Get
and del
require one parameter; name, which is the secret Label in D-Bus API terms.
Del
accepts one or more secret labels and deletes all of them. If it generates an error it will stop.
Set also requires the data as a single string in the second parameter. For example, set foo bar baz
will generate an error but set foo 'bar baz'
will work. If the string is -
then the string is read from standard input.
Base64 encoding
Get
and set
take a -b
or --base64
flag that handles base64 automatically. If used, Set
will encode the input before storing it and/or get will decode it before printing.
Note that calling get -b
on a secret that is not base64 encoded secret will generate an error.
Examples
Errors
Error output goes to stderr
so adding 2>/dev/null
to the end of a command will suppress it.
No keyring
The login collection does not exist because the keyring does not exist. KDE may create kdewallet instead of login like GNOME.
No matching secret
A secret may not be returned even though a secret with the same label exists. If the secret was not created with lkru, it may not have the same attributes. Namely 'Agent', 'Application', and 'Id'.
No D-Bus Session
There may not be a D-Bus Session to host the Secret Service. This happens when the user is not logged into the GUI.
No D-Bus
The system may not host D-Bus. Several lightweight linux distributions ship without it by default.
Last updated