Breadcrumbs

Signum Agents

Signum Agents are lightweight components that bridge native operating system signing capabilities with the Signum SaaS platform.

Agent Overview

The Signum Agents work by leveraging platform-native cryptographic interfaces, such as:

  • Windows: Key Storage Providers (KSP), Cryptographic Service Providers (CSP), and PKCS#11

  • macOS: PKCS#11 and Keychain using CryptoTokenKit

  • Linux: PKCS#11

For more information, see Interoperability.

Download the Agent packages for Windows (.msi), macOS (.pkg), and Linux (.deb, .rpm) from the Signum SaaS Portal.

The Signum Container Agent is a container-based version of the Linux Agent. For access to the Container Agent, contact Keyfactor support.

Once authenticated through an Agent, users or machines gain access to certificates governed by the roles and policies defined in Signum.

Outbound access to port 443 on the Signum server instance is required. Ensure your firewall permits this connection.

For guides on signing with these Agents, see Signing Guides.

Agent Upgrades

Agent binaries are available from the Signum SaaS Portal. For the supported Agents for your server version, see Supported Versions.

Depending on the platform and version, you can either upgrade in-place or uninstall and reinstall your Agent:

In-place Upgrade: In-place upgrades preserve the configuration. On some platforms, in-place updates are not supported and might leave the Agent in an inconsistent state.

Uninstall/Reinstall: 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.

Platform

Recommended Upgrade Procedure

Linux DEB (Ubuntu, Debian)

From version 4.30.4, perform an in-place upgrade with dpkg -i. See Linux Agent.

Linux RPM (RHEL, AlmaLinux, Rocky)

For versions 4.30.4 to 4.70.1, perform a complete uninstall and new installation. An in-place upgrade is not safe.

From version 4.80.1, use rpm -Uvh. See Linux Agent.

macOS

Double-click the new .pkg and follow the installer. See macOS Agent.

Windows

Uninstall the previous version, then install the new one. See Windows Agent.

Agent Tools

After installation, the following tools are available for the Agent:

Signum Util

Only available for macOS and Linux Agents. The Windows agent uses the rtsetup.exe tool for configuration.

The Agent is set up and configured using the Signum Util tool. The tool is added to /usr/local/bin/signum-util by the installer and added to the users path.

Signum Service

Only available for macOS and Linux Agents. The Windows agent uses the RTService tool.

The Signum Service is the background service that serves as bridge between the crypto libraries and the Signum server.

PKCS#11 Module

After installation, the Agent PKCS#11 module, which is needed for configuring different signing tools, can be found in the following locations:

OS

Location

Windows

/Windows/System32/libsignumpkcs11.dll

macOS

/Library/Keyfactor/Signum/lib/libsignumpkcs11.so

Linux

/usr/lib/libsignumpkcs11.so

Other OS-specific Tools

The following tools are also included, based on the OS of your Agent:

OS

Tool

Functionality

Windows

KSP/CSP

The KSP or CSP tools make HSM-backed certificates visible in the Windows certificate store.

macOS

KeyfactorAgentToken

This is the CryptoTokenKit, which makes Signum
HSM-backed keys appear as locally available identities to these tools.

SignumAgent App

This is a Basic UI that registers the KeyfactorAgentToken.appex extension.

In this section

Logging

Windows

Logs for the Windows Agents can be found in C:\Windows\Temp under redtrustclient.txt.

macOS and Linux

Logs for the macOS and Linux Agents can be found in /tmp/:

ls /tmp/*[Ss]ignum* `#Log files for the SignumService and signum-util`

UI and Token Logs

Logs for the UI and token driver-specific can be found in ~/Library/Group Containers/group.com.keyfactor.signum.shared.

  • The log for the UI interface: keyfactoragent.log

  • The log for the token being invoked by the applications using the keychain's certificates: keyfactoragenttoken.log

Agent Tool Logs

The PKCS#11 logs are stored in ~/.keyfactor/logs.

The Cryptotokenkit logs are stored in ~/Library/Group Containers/group.com.keyfactor.signum.shared.