enterprise

The Signum Agents use native code signing tools to access certificates stored in SignServer.

The current version of the Signum Agents supports only configuring one backend at a time. You can set up either SignServer or Signum as the backend, but not both simultaneously. For more information, see Signum Agents.

Prerequisites

  • SignServer Enterprise 7.4.0 or later

Step 1 - Install Agent (ServiceUtilAgent)

For access to the Agent download, contact Keyfactor.

  1. Download the .pkg package.

  2. Click on the package to install.

  3. Follow the installer guide to complete the Agent installation.

After completing the installation, three new tools are available:

  • SignumUtil

  • SignumService

  • SignumAgent App

The Signum 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.

Follow the next steps to set up your SignServer workers for this new integration and to set up SignumUtil to use your SignServer as the backend for signing.

Step 2 - Set up SignServer Worker

To use your SignServer instance with the Agent, you need to have already set up a Crypto Worker. For more information, see Crypto Tokens: HSMs & Keystores.

Worker Configuration

Plain Signer configured in SignServer to process the request made through SignumUtil.

The Agent supports signing operations only with a Plain Signer configured in SignServer. Use of any other worker type is not supported in this workflow.

For the configuration to work with the SignumUtil:

  1. Set CLIENT_VISIBLE=true to let the Agent access only the workers set up for use with SignumUtil.

  2. Set CLIENTSIDEHASHING=true to sign with the Agent.

In the example, the CryptoWorker is configured from our PlainSigner template using a P12 CryptoToken and NOAUTH:

WORKERGENID1.CLIENT_VISIBLE=true
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP12
WORKERGENID1.ACCEPTED_HASH_DIGEST_ALGORITHMS=SHA-256,SHA-384,SHA-512
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.DISABLEKEYUSAGECOUNTER=true
WORKERGENID1.AUTHTYPE=NOAUTH
WORKERGENID1.CLIENTSIDEHASHING=true
WORKERGENID1.DEFAULTKEY=code00001
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.cmssigner.PlainSigner
WORKERGENID1.NAME=PlainSigner

The preferred configuration for authentication for production environments is to use ClientCert as AuthType in your worker. See Configure Client Certificate Authentication and Authorization.

Multiple PlainSigners can be configured for signing with different certificates or keys. However, setting up several PlainSigners with different configurations but pointing to same certificate can result in unexpected behavior and is not recommended.

Step 3 - Set up Signum Agent

To use the Agent, the SignumUtil needs to be configured to connect to your SignServer deployment.

macOS Agent Configuration

The setup for SignServer configuration is done with the following command:

signum-util signserversetup --certificate /home/path/to/my/cert --hostname localhost:443

SignumUtil needs to have permissions to the path where your certificate is stored.

Example of a successful setup:

% signum-util signserversetup -c /tmp/dss10_client1.p12 -h localhost:443
SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].
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.

Check the setup by running the show command:

% signum-util show
Signum SignServer stored configuration.
certificate=/tmp/dss10_client1.p12
hostname=localhost:443
loglevel=NONE

You can also retest the configuration:

% signum-util test
SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].

Linux Agent Configuration

By default, the Signum Linux Agent expects a setup with Signum as the backend. Therefore, if you try to set the Agent to connect to SignServer, you get the following error:

User configuration saved as SignServer but SignumService configured to use Signum
Please run [signum-util service --backend SIGNSERVER -r] with appropriate permissions.

To set up SignServer as the backend, run:

sudo signum-util service --backend SIGNSERVER -r
Service Settings saved successfully.
Service Settings reloaded successfully.
Configuration updated and SignumService restarted successfully.

The setup for SignServer configuration is done with the following command:

signum-util signserversetup --certificate /home/path/to/my/cert --hostname localhost:443

Make sure the SignumUtil has permissions to the path where your certificate is stored.

Example of a successful setup:

% signum-util signserversetup -c /tmp/dss10_client1.p12 -h localhost:443
SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].
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.

Check the setup by running the show command:

% signum-util show
Signum SignServer stored configuration.
certificate=/tmp/dss10_client1.p12
hostname=localhost:443
loglevel=NONE

You can also retest the configuration:

% signum-util test
SignServer Test completed, able to connect to instance [localhost:443] with certificate [/tmp/dss10_client1.p12].

Step 4 - Using Signum

The listcertificates command returns the certificates that the user is authorized to access and that are configured in SignServer for use with the Signum Agent. For more information, see the CLIENT_VISIBLE setting in the Worker Configuration.

signum-util listcertificates
Subject CN : code00001
Issuer CN : DSS Root CA 10
Valid Until : 2036-02-27
Valid From : 2016-03-03
Thumbprint : 0A9861B55542C065E68DBA15AA106C6C02095A2B

In the example, the response includes only one certificate, reflecting the SignServer configuration above that grants the user access to a single signing certificate with SignumUtil:

% signum-util keychain --add
Existing Signum certificates where successfully removed from the KeyChain
Certificate with alias [code00001] and ID [1] was added successfully to the KeyChain

After running the --add command, check that the certificate was added successfully by running the following:

% sc_auth identities
SmartCard: com.keyfactor.signum.token:1
Unpaired identities:
9DB1491F4933493C083F3CFE5E25AC3D10C0EB1E code00001

Linux Example: Sign Using OpenSSL

The following steps show how to sign a file using OpenSSL.

Configure OpenSSL

  1. Install the OpenSSL PKCS#11 module:

    sudo apt-get install libengine-pkcs11-openssl opensc

  2. Edit your OpenSSL config file by default in: /usr/lib/ssl/openssl.cnf and add the following entries:

    [openssl_init]
    engines=engine_section
    [engine_section]
    pkcs11 = pkcs11_section
    [pkcs11_section]
    engine_id = pkcs11
    MODULE_PATH = /usr/lib/libkeyfactorpkcs11.so
    init = 0

The section [openssl_init] should already be in your openssl.cnf. Add the engines=engine_section there.

This configuration adds Signum as a PKCS#11 interface to OpenSSL, allowing for crypto operations with key storing provided by Signum.

Use OpenSSL

From OpenSSL 3.0.8, using a specific PKCS#11 URL is the required method for signing, rather than relying solely on a certificate thumbprint.

The pkcs11-tool can be used to view available key objects to the authenticated Signum user:

pkcs11-tool --module /usr/lib/libsignumpkcs11.so -O
Using slot 0 with a present token (0x11)
Certificate Object; type = X.509 cert
label: 0A9861B55542C065E68DBA15AA106C6C02095A2B - Certificate
subject: DN: CN=code00001, OU=Testing, O=SignServer, C=SE
ID: 0a9861b55542c065e68dba15aa106c6c02095a2b
Unique ID:
Public Key Object; RSA 2048 bits
label: 0A9861B55542C065E68DBA15AA106C6C02095A2B - Public key
ID: 0a9861b55542c065e68dba15aa106c6c02095a2b
Usage: encrypt, verify, wrap
Access: none
Unique ID:
Private Key Object; RSA
label: 0A9861B55542C065E68DBA15AA106C6C02095A2B - Private key
ID: 0a9861b55542c065e68dba15aa106c6c02095a2b
Usage: decrypt, sign, signRecover, unwrap
Access: sensitive, extractable
Unique ID:

Use the p11tool to find the PKCS#11 URL:

p11tool --list-tokens --provider /usr/lib/libsignumpkcs11.so
Token 0:
URL: pkcs11:model=Linux;manufacturer=Keyfactor;serial=1;token=Keyfactor for Linux
Label: Keyfactor for Linux
Type: Hardware token
Flags: uPIN uninitialized
Manufacturer: Keyfactor
Model: Linux
Serial: 1
Module:

Sign the File

To create a test .txt file to sign, run the following command:

echo test > test.txt

To sign the .txt file, run the following command:

openssl dgst -engine pkcs11 \
-keyform engine \
-sha256 \
-sign "pkcs11:model=Linux;manufacturer=Keyfactor;serial=1;token=Keyfactor for Linux" \
-out signature.bin \
test.txt

Expected result:

Engine "pkcs11" set.

Verify

To verify the signature, run the following command:

openssl dgst -engine pkcs11 -keyform engine -sha256 -verify "pkcs11:model=Linux;manufacturer=Keyfactor;serial=1;token=Keyfactor for Linux" -signature signature.bin < test.txt
Engine "pkcs11" set.
Verified OK

macOS Example: Sign using Codesign

This example shows how to sign a file using Codesign.

Create a sample file to sign:

echo "Something cool to sign" > file.sh

The created file is then provided to Codesign together with the Thumbprint returned by the listcertificates command above. The output should return file.sh: signed generic, as seen in the following output:

% codesign -s 0A9861B55542C065E68DBA15AA106C6C02095A2B -v file.sh
file.sh: signed generic [file]

If an error is returned, check the output logs from Codesign for more information about where the error occurred.

After signing the file, use the following command to check the signed file:

% codesign -dv --verbose file.sh
/file.sh
Identifier=file
Format=generic
CodeDirectory v=20100 size=149 flags=0x0(none) hashes=1+2 location=embedded
Signature size=3608
Authority=code00001
Authority=DSS Root CA 10
Signed Time=15 Oct 2025 at 08:04:00
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none
Internal requirements count=1 size=80

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.

Some examples of issues that could cause the errors:

  • Incorrect certificate url: The certificate provided needs to be in a location that signum-util has permissions for. If this is the cause of the error, the logs will state that signum-util does not have permission to the provided p12.

The url provided during configuration must be only the base url. Do not include the scheme or the SignServer path.

  • Incorrect certificate type: The chosen certificate for signing must be a signing certificate otherwise the signing fails. The command signum-util listcertificates -v Detailed shows the capabilities attribute:

    % signum-util listcertificates -v Detailed
    Subject CN : code00001
    Issuer CN : DSS Root CA 10
    Valid Until : 2036-02-27
    Valid From : 2016-03-03
    Thumbprint : 0A9861B55542C065E68DBA15AA106C6C02095A2B
    Serial Number : 0DE0C0DA115F264C
    Key Algorithm : RSA
    Key Size : 2048 bits
    Signature Algo : sha256RSA
    Capability : Client Authentication (1.3.6.1.5.5.7.3.2)
    Capability : Code Signing (1.3.6.1.5.5.7.3.3)
    Capability : Email Protection (1.3.6.1.5.5.7.3.4)

  • Worker changes not reflected in the keychain: Changes on the Workers in SignServer are not directly reflected in the keychain. For every server change, execute a listcertificates and a keychain --add in the signum-util.

  • TLS issues with private PKI: When running a private PKI with the macOS Agent and SignServer, TLS issues can occur, indicated by the following error:

    The SSL connection could not be established, see inner exception.
    The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot

    To resolve, run the following command to add the certificate to the system keychain and ensure SSL validation:

    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychsudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain PrivatePKIManagementCA.cacert.pem