Breadcrumbs

Linux Agent


The Signum Linux Agent provides an authenticated user access to signing certificates from the Signum Server and a connected HSM for use with signing tools that support PKCS#11.

The Linux agent supports the Local Users Domain and Certificate User Domain. See Domains.

The Linux Agent also supports working with SignServer 7.4 and later. For more information about configuring this Agent with SignServer, see Signum Agents in the SignServer documentation.

For a guide to configure OpenSSL through a PKCS#11 module with the Linux Agent, see Using Signum with OpenSSL.

Prerequisites

  • Outbound access to port 443 on the Signum server instance.

    • A firewall rule permitting this outbound connection (if applicable).

Dependencies

The Signum Linux Agent is available as either a .deb or as an .rpm package. All packages have a Standalone version that bundles the necessary .NET runtime.

  • Standard: Relies on the .NET 10 runtime installed on the host. The dotnet-runtime-10.0 and aspnetcore-runtime-10.0 packages are pulled in as dependencies, so the Microsoft / .NET repository must be enabled before installing the Agent.

  • Standalone (self-contained): Bundles the .NET 10 runtime alongside the Agent binaries. No .NET repository or runtime package is needed on the host.

The following provides the .NET repository setup and the runtime dependencies for the Standard package based on distribution. When using the Standalone package, skip the .NET repository step and omit dotnet-runtime-10.0 / aspnetcore-runtime-10.0 from the install command. For the latest information about configuring the repositories for your distribution, see Microsoft’s official page: Install .NET on Linux distributions.

Debian 12 
# Standard package only: enable the Microsoft .NET repository
wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo apt install -y libcurl4 libssl3 libsqlite3-0 dotnet-runtime-10.0 aspnetcore-runtime-10.0
Debian 13 
# Standard package only: enable the Microsoft .NET repository
wget https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo apt install -y libcurl4 libssl3 libsqlite3-0 dotnet-runtime-10.0 aspnetcore-runtime-10.0
Alma 9 
# Standard package only: enable EPEL (provides some of the runtime libraries)
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo dnf install -y libcurl sqlite-libs libstdc++ libicu openssl-libs dotnet-runtime-10.0 aspnetcore-runtime-10.0
RHEL 8 
# Standard package only: enable Microsoft's .NET repo IF dotnet-runtime-10.0 is not yet
# available in your RHEL 8 AppStream.
sudo rpm -Uvh https://packages.microsoft.com/config/rhel/8/packages-microsoft-prod.rpm

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo dnf install -y libcurl sqlite-libs libstdc++ libicu openssl-libs dotnet-runtime-10.0 aspnetcore-runtime-10.0
RHEL 9 
# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo dnf install -y libcurl sqlite-libs libstdc++ libicu openssl-libs dotnet-runtime-10.0 aspnetcore-runtime-10.0
Ubuntu 22 
# Standard package only: enable the .NET backports PPA
sudo add-apt-repository ppa:dotnet/backports
sudo apt update

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo apt install -y libcurl4 libssl3 libsqlite3-0 dotnet-runtime-10.0 aspnetcore-runtime-10.0
Ubuntu 24 
sudo apt update

# Runtime dependencies (omit dotnet-runtime-10.0 and aspnetcore-runtime-10.0 if using the Standalone package)
sudo apt install -y libcurl4 libssl3 libsqlite3-0 dotnet-runtime-10.0 aspnetcore-runtime-10.0

Keyring Credentials Storage

To use the Keyring as credential storage, you need to additionally install the libsecret package. For more information, see Using Keyrings.

Debian / Ubuntu:

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

RHEL / Alma:

sudo dnf install -y libsecret gnome-keyring

Agent Installation & Upgrade

Agent binaries are available from the Signum SaaS Portal. For upgrades, you can either upgrade in-place or uninstall and reinstall your Agent, depending on the Agent version. See Signum Agents | Agent Updates.

When uninstalling the Agent, the existing configuration is purged. You need to run signum-util setup again after the new installation. However, the uninstall process does not remove any configuration stored on the keychain. If you want to ensure the configuration is deleted, run signum-util logout before uninstalling.

Debian & Ubuntu

Modify to match the agent .deb being installed:

sudo apt install  ./amd64_ubuntu22.04_keyfactor-agent-4.60.2-5435da7-Trust.deb

Check the Agent version:

dpkg --list keyfactor-agent

Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name            Version      Architecture Description
+++-===============-============-============-=================================
ii  keyfactor-agent 4.60.2       amd64        Keyfactor Agent

For a fresh installation:

sudo dpkg -i keyfactor-agent.deb

To fix any missing dependency:

sudo apt install -f

To uninstall:

sudo dpkg -r keyfactor-agent

To upgrade (the already installed version has to be 4.30.0 or higher):

sudo dpkg -i keyfactor-agent.deb

RHEL & Alma

Modify to match the agent .rpm being installed. Use the standalone Agent versions if .Net 10 is not yet available in the App stream.

Install RHEL 8 
sudo dnf install ./amd64_rhel8_keyfactor-agent-4.60.2-5435da7-Trust.rpm
Install RHEL 9 
sudo dnf install ./amd64_rhel9_keyfactor-agent-4.60.2-5435da7-Trust.rpm

Check the Agent version:

rpm -qa keyfactor-agent

keyfactor-agent-4.60.2

After installing, you can verify the agent service is running:

systemctl status SignumService.service

● SignumService.service - Long running SignumService service/daemon created by Keyfactor.
     Loaded: loaded (/etc/systemd/system/SignumService.service; enabled; preset: disabled)
     Active: active (running) since Tue 2025-11-04 11:22:24 EST; 2min 52s ago

For a fresh installation:

sudo rpm -i keyfactor-agent.rpm

To uninstall:

sudo rpm -e keyfactor-agent

To upgrade (the already installed version has to be 4.80.0 or higher):

sudo rpm -Uvh keyfactor-agent.rpm

Agent Configuration & Authentication

With the Agent installed, use the signum-util tool to configure the Agent Daemon with the connection information and credentials to authenticate a user.

Run the following command to return information about the tool:

signum-util help

The command returns the following:

signum-util 4.60.3+c1d230508a5da192ecc28dc9e82147902e3c7a2d
Copyright (C) 2025 signum-util

  show, w                 Shows stored info.

  test, t                 Tests the connection to the configured instance.

  logout, l               Closes the session for the current user and deletes stored credentials.

  listcertificates, lc    List certificates from the server.

  setup, s                Setup Signum

  signserversetup, dss    Configures the Signum Agent for use with SignServer.

  service, ser            Signum Service related operations, requires running with elevated permissions.

  help                    Display more information on a specific command.

  version                 Display version information.

Example to setup new config:
        signum-util setup -h [HOSTNAME] -u [USERNAME] -x [PROXY]
        signum-util setup -h [HOSTNAME] -c [CERTIFICATE PATH]
        signum-util signserversetup -h [SIGNSERVER URL] -c [CERTIFICATE PATH]

As of Signum 4.60.2, the ClientID parameter is no longer required.

The following table describes the returned values:

Command

Usage

show

Returns the current setup information if present including the server being used.

test

Tests the connection to the configured instance.

logout

Closes the session for the current user and deletes stored credentials.

listcertificates

Returns a list of certificates that the configured user has access to based on a policy configured in Signum or Worker property in SignServer.

setup

Use this command to configure the connection to your Signum server and authenticate your user:

signum-util setup

signum-util 4.60.3+c1d230508a5da192ecc28dc9e82147902e3c7a2d
Copyright (C) 2025 signum-util

  -h, --hostname        Required. Set agent server address

  -u, --username        Required. Set username to connect

  -x, --https_proxy     Setup an http proxy to be used by signum, this configuration overrides the system configuration (usually /etc/systemd/system.conf) if not
                        specified, blank or unable to connect to the signum instance through it, the agent will fall back to the system configuration  (usually
                        /etc/systemd/system.conf).

  -p, --password        Set the password for the user or certificate to connect. If not provided, you will be prompted to input it interactively.

  -l, --loglevel        (Default: NONE) Set log level. [NONE, LOW, MEDIUM or HIGH]

  -o, --outputFormat    (Default: Text) Output formats [Text, JSON, JSONFormatted]

  --help                Display this help screen.

  --version             Display version information.

Example to setup new config:
        signum-util setup -h [HOSTNAME] -u [USERNAME] -x [PROXY]
        signum-util signserversetup -h [SIGNSERVER URL] -c [CERTIFICATE PATH]

signserversetup

Use this command to configure the connection to SignServer. For more information about using the signum-util with SignServer, see Signum Agents in the SignServer documentation.

service

Use for configuring the Signum Service.

The backend value can be edited later if needed to change between working with Signum or SignServer.

The service command options require elevated permissions to write to the service configuration file and to restart the service.


  -p, --port            Set the listening port for the service, default 51599
  -t, --logtype         Set the log type, accepted values [STDOUT, FILE]
  -l, --loglevel        Set log level. [NONE, LOW, MEDIUM or HIGH]
  -b, --backend         Set the backend to SIGNSERVER or SIGNUM.
  -r, --restart         Restarts the service to apply configuration changes,
                        this will remove all elements from cache.
  -o, --outputFormat    (Default: Text) Output formats [Text, JSON,
                        JSONFormatted]

help

Display more information on a specific command.

version

Display version information.

Authenticate with User & Password

To authenticate the Agent, you need the Signum Server URL which can be found in the Signum Links at Keyfactor Customer Portal.

  1. Enter your username in the format of username@domain. For example, if your username is testuser and your Local User Domain Alias is testdomain, enter “testuser@testdomain”.

    signum-util --hostname a_signum_url --username "testuser@testdomain"

  2. Enter the users credentials when prompted. The credentials can also be passed in with “--password” argument. Remember to clear shell histories of sensitive credentials or use the interactive prompts.

    password:
*****************

  3. A connection status message is returned. Running signum-util test tests the connection using the current configuration and returns a similar connection status message:

    Instance [URL] successfuly reached .
Login successfull into the instance [URL] with user [USER].
User [USER] successfuly logged in [URL].
New configuration saved successfully, some changes to system settings might require restarting SignumService.
Please run [signum-util service --restart], [systemctl restart SignumService] or equivalent with appropiate permissions.

  4. To restart the service, run:

    sudo signum-util service --restart
SignumService restarted successfully.

Authenticate with Certificate

To authenticate with a certificate, you need the Signum Server URL which can be found in the Signum Links at Keyfactor Customer Portal. You also need a p12 file of the certificate used for login, located in a folder accessible with permissions from the terminal, such as /tmp.

  1. Run the following command:

    signum-util setup -h a_signum_url -c /a_certificate.p12

  2. Enter the certificate password when prompted.

    password:
*****************

  3. A connection status message is returned. Running signum-util test tests the connection using the current configuration and returns a similar connection status message:

    Instance [URL] successfuly reached .
Login successfull into the instance [URL] with user [USER].
User [USER] successfuly logged in [URL].
New configuration saved successfully, some changes to system settings might require restarting SignumService.
Please run [signum-util service --restart], [systemctl restart SignumService] or equivalent with appropiate permissions.

  4. To restart the service, run:

    sudo signum-util service --restart
SignumService restarted successfully.

For more information about logging in with certificates, see Use Certificate-based Authentication.

List Certificates

With a user logged into the Agent and with a membership to a policy that allows access, running signum-util lc returns the certificates that the user has access to:

signum-util lc

Subject CN     : Signum-RSA-3072
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 170570A1D56FBB5A4CC780B69ACAEF94010D5DAA
Subject CN     : Signum-RSA-4096
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD
Subject CN     : Signum-RSA-2048
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2030-02-05
    Valid From     : 2025-02-06
    Thumbprint     : F78AE7871FEF1D0CF3EFFB58E9CC85F261438D2B

For a detailed view, run:

signum-util lc -v Detailed

Subject CN     : Signum-RSA-3072
    Issuer CN      : BenDemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 170570A1D56FBB5A4CC780B69ACAEF94010D5DAA
    Serial Number  : 6FBEC1D43B272A64763488491D7191335564D92C
    Key Algorithm  : RSA
    Key Size       : 3072 bits
    Signature Algo : sha256RSA
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)
Subject CN     : Signum-ECDSA-521
    Issuer CN      : ManagementCA
    Valid Until    : 2027-04-07
    Valid From     : 2026-04-07
    Thumbprint     : 36D0CB3C5765FF5D978BBA93228BE1945E77F3F5
    Serial Number  : 460CA3F6C4C90D0A9B9834CFDA6F80969F1025BA
    Key Algorithm  : ECC
    Key Size       : 521 bits
    Signature Algo : sha256RSA
    Capability     : Code Signing (1.3.6.1.5.5.7.3.3)
    SAN Email      : mail@test.com

Log Out

Calling signum-util logout removes the users credentials and configured setup information:

signum-util logout

Logout process started.
A total of 1 sessions have been closed for the provided user.
Successfully removed stored credentials.

Logging

Logs for the agent can be found in /tmp/:

ls /tmp/*[Ss]ignum* `#Log files for the SignumService and signum-util` 
ls /tmp/keyfactor_* `#Log files for applications loading the signum pkcs11 library`

Additional Information

The Agent connection can be tested with:

signum-util test

By default, the Agent Service uses port 51599. To change the port, edit the config file stored at /etc/keyfactor/config and restart the service.

The Agent PKCS#11 module, which is needed for configuring different signing tools, can be found at /usr/lib/libsignumpkcs11.so.

Troubleshooting

If any errors are returned during setup of signum-util or during signing, check the logs for more information about the root cause of the error.

The output logs for signum-util can be found under /tmp.