Breadcrumbs

Set Up a Keyring

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 login keychain. On Linux, it is gnome-keyring accessed via the D-Bus secret service.

On macOS, to use certificates with native tools like codesign and productsign, signing certificates must be added to the keychain. See macOS Agent.

Private keys cannot be exported from the HSM.

Note for macOS: Calls to the keyring require the login keychain to be unlocked. This can be done on the terminal by running security unlock-keychain ~/Library/Keychains/login.keychain-db and introducing the password for the user. If programmatically unlocking the keychain is not advisable in your environment, set the option -s File when running the signum-util setup/signserver-setup command. See Set the Configuration Storage Type.

Supported Platforms

Platform

Keyring

macOS Sonoma 14.0 or later

macOS keychain

Debian 12, Debian 13

gnome-keyring via D-Bus

Ubuntu 22, Ubuntu 24

gnome-keyring via D-Bus

AlmaLinux 9

gnome-keyring via D-Bus

RHEL 8 (full enterprise), RHEL 9 (full enterprise)

gnome-keyring via D-Bus

Redhat UBI is not supported because it requires an entitlement server.

Linux: Install gnome-keyring

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 update the storage type in the ~/.keyfactor/config to configuration_storage_type=File or configuration_storage_type=Keyring using the signum-util tool and then reconfigure the Agent by re-running the signum-util setup/signserversetup command.

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.

Type

Location

Agent

Description

Keychain/Keyring entry

4BCK5AYU94.com.keyfactor.signum.agentToken

macOS

Linux

Enabled if the Agent is configured with -s keyring, used by Signum Util and Signum Service.

Both Signum Util and KeyfactorAgentToken are pre-authorized, and can be safely used on headless deployments.

Encrypted text file

~/.keyfactor/data

macOS

Linux

Enabled if the Agent is configured with -s file. Used by the PKCS#11 library and, in Linux, also by the signum-util.

Follows the file system permissions.

Plain text file

~/keyfactor/config

macOS

Linux

Always present, stores basic information for the agent.

Follows the file system permissions.

Troubleshooting

The following checks help diagnose keyring setup failures. 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.

Linux-specific Troubleshooting

The 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
The 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.

macOS-specific Troubleshooting

Worker changes not reflected in the keychain

Changes on the workers in SignServer are not directly reflected in the keychain. For every server change, execute a listcertificates and a keychain --add in the signum-util.

TLS issues with private PKI

When running a private PKI with the Mac Agent and SignServer, TLS issues can occur, indicated by the following error:

The SSL connection could not be established, see inner exception.
The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot

To resolve, run the following command to add the root CA certificate to the system keychain and ensure SSL validation:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychsudo security add-tr
SignumService not authorized to access the private key

If codesign or productsign fails with a key access error, the SignumService application may not be in the Access Control list for the private key in Keychain Access:

  1. Open Keychain Access.

  2. Locate the private key (expand the certificate entry to find it).

  3. Double-click the private key and go to Access Control.

  4. Add SignumService to the list of authorized applications.

  5. Click Save and enter your macOS admin credentials when prompted.

  6. Restart Keychain Access and confirm SignumService still appears in the list.