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  ./keyfactor-agent_4.10.0-c2914fc366a725b7d55ce349c17862897fa28270_ssl3-Trust_amd64.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.

CODE

sudo dnf install ./keyfactor-agent-4.10.0-c2914fc366a725b7d55ce349c17862897fa28270.x86_64

Checking 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 keyfactor-setup tool to configure the Agent Daemon with the connection information and credentials to authenticate a user.

CODE

keyfactor-setup

CODE

Keyfactor Agent configuration tool.

Parameters:
   hostname= Set agent server address
   clientid= Set service ClientId
   username= Set user username to connect
   loglevel= [NONE|LOW|HIGH] Set log level (optional)
   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).

Format to set new config:
   #Keyfactor-setup  hostname=[HOSTNAME] clientid=[CLIENT ID] username=[USERNAME] https_proxy=[PROXY] https_proxy=[PROXY URL]

Operations:
   show : Shows stored info.
   help : Shows this message.
   test : Tests the connection to the configured instance.
   logout : Closes the session for the current user and deletes stored credentials.

Authenticating

To authenticate the Agent you will need the Signum Server URL and ClientID which can be found in the Signum Links and Dashboard pages respectively 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 you would enter “testuser@testdomain”.

CODE

keyfactor-setup hostname=a_signum_url clientid="2qiBoMy5mt2bAZqHfGdOd/G4bY2hBKc0Oq0Llj+ME1U=" username="testuser@testdomain"

Enter the users credentials when prompted. The credentials can also be passed in with a “password” argument. Remember to clear shell histories of sensitive credentials.

CODE

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

A connection status message will be returned.

CODE

Instance [the_signum_url] successfuly reached.
New configuration saved successfully, some changes to system settings might require restarting KeyfactorService.
Please run [systemctl restart KeyfactorService] 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

Logging Out

Calling Keyfactor setup logout will remove the users credentials.

CODE

keyfactor-setup logout

CODE

Successfully logged out from server.
Successfully removed stored credentials.

Additional Information

The Agent connection can be tested with keyfactor-setup test

CODE

 Instance [a_signum_url] successfuly reached.

By default, the Agent Daemon uses port 51599 this can be changed by editing the config file stored at

CODE

/etc/keyfactor/config

The Agent PKCS11 module, which is needed for configuring different signing tools can be found at

CODE

/usr/lib/libkeyfactorpkcs11.so

Logs are stored in /tmp/ .

CODE

ls -la /tmp/*[Kk]eyfactor*