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 PKCS11. Currently the only supported Domain with the Linux Agent is LocalUsers. Future versions of this agent will support additional authentication methods.

Installation Requirements & Dependencies

The Signum Linux Agent is available as either a .deb package or as an .rpm package for both RHEL 8 and 9. Standalone versions of the agent packages are also included that come bundled with the dotnet runtimes should those be needed based on the OS version being used.

Installation instructions for the .NET Runtime from Microsoft: https://docs.microsoft.com/en-us/dotnet/core/install/linux

Dependencies

Debian

CODE

sudo apt update && sudo apt upgrade

Dotnet 6.0 - Agents before 4.10.0

CODE

sudo apt install sudo dotnet-runtime-6.0 aspnetcore-runtime-6.0 libssl3 libsqlite3-0 opensc -y

Dotnet 8.0 - Agents after 4.10.0

CODE

sudo apt install libcurl4 dotnet-runtime-8.0 aspnetcore-runtime-8.0 libssl3 libsqlite3-0 opensc -y

RHEL

CODE

sudo dnf update && sudo dnf upgrade

Dotnet 6.0 - Agents before 3.80.4

CODE

sudo dnf -y install libcurl dotnet-runtime-6.0 aspnetcore-runtime-6.0 sqlite-libs libstdc++ openssl-libs opensc

Dotnet 8.0 - Agents after 3.80.4

CODE

sudo dnf -y install libcurl dotnet-runtime-8.0 aspnetcore-runtime-8.0 sqlite-libs libstdc++ openssl-libs opensc

Agent Installation

Debian

Modify to match the agent .deb being installed:

CODE

sudo apt install  ./amd64_ubuntu22.04_keyfactor-agent-4.20.0-457bb50-Trust.deb

Checking the Agent version:

CODE

dpkg --list keyfactor-agent

CODE

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.10.0       amd64        Keyfactor Agent

RHEL

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

RHEL 8

CODE

sudo dnf install ./amd64_rhel8_keyfactor-agent-4.20.0-457bb50-Trust.rpm

RHEL 9

CODE

sudo dnf install ./amd64_rhel9_keyfactor-agent-4.20.0-457bb50-Trust.rpm

Check the Agent version:

CODE

rpm -qa keyfactor-agent

CODE

keyfactor-agent-4.10.0-c2914fc366a725b7d55ce349c17862897fa28270.x86_64

After installing, you can verify the Agent Daemon is running:

CODE

systemctl status KeyfactorService.service

CODE

● KeyfactorService.service - Long running KeyfactorService service/daemon created by Keyfactor.
     Loaded: loaded (/etc/systemd/system/KeyfactorService.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2024-01-30 16:22:33 UTC; 20min ago
   Main PID: 5472 (KeyfactorServic)
      Tasks: 15 (limit: 4668)
     Memory: 40.9M
        CPU: 960ms
     CGroup: /system.slice/KeyfactorService.service
             └─5472 /usr/local/keyfactor/service/KeyfactorService

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.

Commands

CODE

signum-util

CODE

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

  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]

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

CODE

signum-util setup

CODE

signum-util 4.60.2
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 de 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]

Setup

CODE

signum-util setup

CODE

signum-util 4.60.2
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 de 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]

To authenticate the Agent, you need the Signum Server URL which can be found in the Signum Links at https://portal.az.keyfactorsaas.com/. 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”.

CODE

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

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.

CODE

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

A connection status message is returned. Running signum-util test will test the connection using the current configuration and return similar connection status messaging.

CODE

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.

If the user that has been authenticated has access to a certificate in Signum via a policy, you can list the key objects using pkcs11-tool .

CODE

pkcs11-tool --module /usr/lib/libkeyfactorpkcs11.so --list-objects --type cert

CODE

Using slot 0 with a present token (0x0)
Certificate Object; type = X.509 cert
  label:      74495288CACC9CF4A15D269AB9C0C3DDABEDB3B0 - Certificate
  subject:    DN: CN=Demo
  ID:         74495288cacc9cf4a15d269ab9c0c3ddabedb3b0

Listing Certificates

With a user logged in to the Agent and having membership to a policy that allows access, running signum-util lc will return the certificates that the user has access to.

CODE

signum-util lc

CODE

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

CODE

signum-util lc -v Detailed

CODE

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)

Logging Out

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

CODE

signum-util logout

CODE

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

Additional Information

The Agent connection can be tested with signum-util test:

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

The Agent PKCS11 module, which is needed for configuring different signing tools, can be found at /usr/lib/libkeyfactorpkcs11.so

Logs are stored in /tmp/:

CODE

ls /tmp/*[Ss]ignum*