enterprise

The Signum Linux Agent uses native code signing tools to access certificates stored in SignServer.

The current version of Signum-util 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 Linux Agent documentation.

Prerequisites

SignServer Enterprise 7.4.0 or later is required for the Linux Agent.

Step 1 - Install Linux 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 Linux Agent installation.

After completing the installation, three new tools are available:

  • SignumUtil

  • SignumService

  • SignumAgent App

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

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

Worker Configuration

The Linux Agent needs a Plain Signer configured in SignServer to process the request made through SignumUtil.

The Linux 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

To use the Linux Agent, the SignumUtil needs to be configured to connect to your SignServer deployment. For more information, see Signum Linux Agent documentation.

Change Default 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.

SignumUtil 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.

The setup can be checked by running the show command:

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

Or 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 SignServer 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

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.

Using 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" test.txt > signature.bin
Engine "pkcs11" set.

To verify the signature, run the following command:

Verify

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

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.