.png){kind=logo}
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.
Private keys cannot be exported from the HSM.
On macOS, to use certificates with native tools like codesign and productsign, signing certificates must be added to the keychain. See macOS Agent | Add Signing Certificates to the Keychain.
Supported Platforms
|
Platform |
Keyring |
|---|---|
|
Windows 11 (64 bits or ARM) |
Windows Credentials Manager |
|
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 or Windows.
Unlock the Keychain
For macOS and Linux, calls to the keyring require the login keychain to be unlocked. Windows does not lock the vault separately and, as long as there is a user session, the credentials are accessible to Signum.
To unlock the keychain, run an unlock command in the terminal and introduce a password for the user:
security unlock-keychain ~/Library/Keychains/login.keychain-db
secret-tool store --label="4BCK5AYU94.com.keyfactor.signum.agentToken" service SignumService username myuser
If using Ubuntu Server, update the following files to automatically start the GNOME keyring after login:
/etc/pam.d/common-auth auth optional pam_gnome_keyring.so
etc/pam.d/common-session session optional pam_gnome_keyring.so auto_start
Unlock the keychain:
secret-tool store --label="4BCK5AYU94.com.keyfactor.signum.agentToken" service SignumService username myuser
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.
Set the Configuration Storage Type
The configuration storage type is set automatically based on the operating system. By default, macOS uses a keyring, and Windows and Linux use an 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. 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 |
Description |
|---|---|---|
|
Keychain/Keyring entry |
|
Enabled if the Agent is configured with Both |
|
Encrypted text file |
|
Enabled if the Agent is configured with Follows the file system permissions. |
|
Plain text file |
|
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.