Skip to main content
Skip table of contents

Linux Agent

The Signum Linux Agent provides an authenticated user access to signing certificates stored on the Signum server and HSM for use with signing tools that can utilize a PKCS11 token interface (Jarsigner, Cosign, OpenSSL, etc.). Currently the only supported Domain with the Linux Agent is LocalUsers. Future versions of this agent will support additional authentication methods.

Installation Requirements

The Signum Linux Agent is available as either a .deb or .rpm package.

Package dependences are below.

Linux .NET installation instructions:


  • Libcurl

  • dotnet-runtime-6.0

  • aspnetcore-runtime-6.0

  • sqlite-libs

  • libstdc++

  • openssl-libs


  • libcurl4

  • dotnet-runtime-6.0

  • aspnetcore-runtime-6.0

  • libssl3 or libss1.1 - Depends on Linux Distro, Debian uses 1.1 , Ubuntu uses version 3

  • libsqlite3-0


After installing the package and required dependencies make note of the items and default locations below.

  • By default, the Keyfactor service uses port 51599 this can be changed by editing the config file.

  • The README file can be found in /etc/keyfactor.

  • The Config file can be found at /etc/keyfactor/config.

  • The pkcs11 lib is in /usr/lib/ and named

  • The KeyfactorService is executed as a root process by default.

  • After installation, enter “keyfactor-setup” in terminal to bring up the Agent Parameters.

  • Logs are stored in the /tmp folder unless set to stdout.

Linux Agent Readme

demo@ubuntu:/etc/keyfactor$ cat README
Instructions to install the Keyfactor agent in Linux v3.53.1

Tested on:
- Ubuntu 22.04 LTS 64 bits
- Debian 11.3
- RHEL 9.0

	Install the .NET runtime 6.0 following the steps from

	This agent uses a local Web API that is executed as background service. By default, the local service runs as a 
	root process and uses the default port 51599.

	URL: https://localhost:51599

	This configuration can be changed by editing the files /etc/keyfactor/config and /etc/systemd/system/KeyfactorService.service.

Service commands:
    sudo systemctl stop KeyfactorService
    sudo systemctl start KeyfactorService
    sudo systemctl status KeyfactorService
    sudo systemctl enable KeyfactorService
    sudo journalctl -u KeyfactorService

Test the agent with the following command:

pkcs11-tool --module /usr/lib/ -t

Install tool: 
	# sudo apt install opensc
	# sudo yum install opensc

Linux Agent Service & Config

Example of the Signum Linux Agent Config file where the port, log type and level settings can be configured. Note that the logtype can also be set to STDOUT.

demo@ubuntu:/etc/keyfactor$ cat config 

Example of the settings for the Keyfactor Service.

demo@ubuntu:/etc/systemd/system$ cat KeyfactorService.service 
Description=Long running KeyfactorService service/daemon created by Keyfactor.

# will set the Current Working Directory (CWD). KeyfactorService service will have issues without this setting.
# systemd will run this executable to start the service.
# to query logs using journalctl, set a logical name here.

# Use your username to keep things simple.
# If you pick a different user, make sure dotnet and all permissions are set correctly to run the app.
# To update permissions, use 'chown yourusername -R /srv/Worker' to take ownership of the folder and files.
#       Use 'chmod +x /srv/Worker/Worker' to allow execution of the executable file.

# Ensure the service restarts after crashing.
# Amount of time to wait before restarting the service.                  

# This environment variable is necessary when dotnet isn't loaded for the specified user.
# To figure out this value, run 'env | grep DOTNET_ROOT' when dotnet has been loaded into your shell.


Linux Agent Setup

Below is the command line argument to pass using “keyfactor-setup” to configure the Agent to communicate to the Signum server.

demo@ubuntu:/etc/keyfactor$ keyfactor-setup
Keyfactor Agent configuration tool.

   hostname= Set agent server address
   clientid= Set service ClientId
   username= Set user username to connect
   loglevel= [NONE|LOW|HIGH] Set log level (optional)
   logtype= [FILE|STDOUT] (optional, default FILE) 

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

   show : Shows stored info
   help : Shows this message

Login Example

Note the password parameter can be provided via the flag or passed through STDIN.

Demo@Ubuntu:~$ keyfactor-setup clientid=12345 loglevel=LOW username=test@domain

Logout Example

bendew@benUbuntu:~$ keyfactor-setup logout
Logout ini.
No session was closed for the provided user and clientId
Successfully logged out from server.
Successfully removed stored credentials.

Linux Agent Test

One way to verify that the Linux Agent is connected is to use the pkcs11-tool to query for certificate objects that are available to the user. For this test to return values, the Agent user needs a policy configured allowing the use of one or more certificates.

demo@Ubuntu:~$ pkcs11-tool --module /usr/lib/ -O
Certificate Object; type = X.509 cert
  label:      CC5B8075AFE198D8BD2EA2577FC99B33A8F34C90 - Certificate
  subject:    DN: CN=Test 2
  ID:         cc5b8075afe198d8bd2ea2577fc99b33a8f34c90
Public Key Object; RSA 2048 bits
  label:      CC5B8075AFE198D8BD2EA2577FC99B33A8F34C90 - Public key
  ID:         cc5b8075afe198d8bd2ea2577fc99b33a8f34c90
  Usage:      encrypt, verify, wrap
  Access:     none
Private Key Object; RSA
  label:      CC5B8075AFE198D8BD2EA2577FC99B33A8F34C90 - Private key
  ID:         cc5b8075afe198d8bd2ea2577fc99b33a8f34c90
  Usage:      decrypt, sign, unwrap
  Access:     sensitive, extractable
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.