Using Keyrings

The Signum Agent stores sensitive configuration data, including credentials and the server address, either in an encrypted file or in a keyring. A keyring is a secure, OS-managed encrypted database for protecting passwords, keys, and certificates. On macOS, this is the system Keychain. On Linux, it is gnome-keyring accessed via the D-Bus secret service.

On macOS, adding signing certificates to the Keychain is also required to use them with native tools like codesign and productsign. See macOS Agent | Add Signing Certificates to the Keychain.

Supported Platforms

Install gnome-keyring (Linux)

Before using a keyring on Linux, install libsecret and gnome-keyring.

Debian and Ubuntu:

sudo apt-get install libsecret-1-0 gnome-keyring

Alma and RHEL:

sudo dnf install libsecret gnome-keyring

No additional installation is required on macOS.

Set the Configuration Storage Type

The configuration storage type is set automatically based on the operating system. By default, macOS uses keyring, and Linux uses encrypted file. To change the configuration storage type, adjust the --configuration_storage_type flag, or -s, during setup.

Example setup using a keyring:

signum-util setup -h 123.123.0.1 -u user@local -p secret -s keyring

In the situation that the keyring setup breaks completely, it is also possible to modify the storage type in the ~/.keyfactor/config with configuration_storage_type=File or configuration_storage_type=Keyring.

Configuration Storage Location

The Signum configuration is stored in the following location(s), depending on the Agent. This location determines where the Signum Agent reads and writes the configuration from.

Troubleshooting (Linux)

The following checks help diagnose keyring setup failures on Linux. These steps are intended to help identify the root cause of configuration failures. If any step does not produce the expected result, the setup is not correctly configured and will not function as intended.

For macOS, see macOS Agent | Troubleshooting.

systemd must be PID 1

The keyring requires a full systemd user session. Verify:

ps -p 1 -o comm=

Expected output:

systemd

If systemd is not PID 1, the most likely cause is that the agent is running inside a container without a systemd-enabled user session. In that case, switch to storing credentials in an encrypted file (configuration_storage_type=File) rather than trying to use the keyring in that environment.

D-Bus must be installed and available

The keyring operates within the user D-Bus session and requires dbus-daemon. Verify it is installed:

dbus-daemon --version

Expected output begins with:

D-Bus Message Bus Daemon 1.14.10
...

A user session must be running

Verify that a user session is running in the shell:

echo $XDG_RUNTIME_DIR
ls -l $XDG_RUNTIME_DIR/bus

Expected output:

/run/user/1000
srw-rw-rw- 1 username ubuntu 0 Jan 26 16:22 /run/user/1000/bus

If $XDG_RUNTIME_DIR is empty, set it manually:

export DBUS_SESSION_BUS_ADDRESS="unix:path=$XDG_RUNTIME_DIR/bus"

The secrets service must be registered

The secrets.service file tells the D-Bus session which program handles keyring access. If it is missing, you may see “The name is not able to be activated”.

Verify that the secrets.service file exists:

ls /usr/share/dbus-1/services/org.freedesktop.secrets.service

Expected output:

/usr/share/dbus-1/services/org.freedesktop.secrets.service

gnome-keyring must be running

Verify the gnome-keyring service is started:

gnome-keyring-daemon --start --foreground --components=secrets

If the daemon was not running, re-run the DBUS_SESSION_BUS_ADDRESS export and retry the keyring operation.