Linux Agent

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)

In your download area on download.primekey.com, go to latest Signum agent folder.

Download the .pkg package.
Click on the package to install.
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 CryptoWorker. For more information, see CryptoTokens.

Worker Configuration

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

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

For the configuration to work with the SignumUtil:

Set CLIENT_VISIBLE=true to let the agent access only the workers set up for use with SignumUtil.
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:

CODE

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:

CODE

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:

CODE

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:

CODE

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

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

Example of a successful setup:

CODE

% signum-util signserversetup -c /tmp/dss10_client1.p12 -u 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:

CODE

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

Or you can also retest the configuration:

CODE

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

CODE

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

Install the OpenSSL PKCS11 module.

CODE

sudo apt-get install libengine-pkcs11-openssl

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

CODE

[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 PKCS11 interface to OpenSSL, allowing for crypto operations with key storing provided by Signum.

Using OpenSSL

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

CODE

pkcs11-tool --module /usr/lib/libkeyfactorpkcs11.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 Ke
y Object; RSA 
  label:      0A9861B55542C065E68DBA15AA106C6C02095A2B - Private key
  ID:         0a9861b55542c065e68dba15aa106c6c02095a2b
  Usage:      decrypt, sign, signRecover, unwrap
  Access:     sensitive, extractable
  Unique ID:

CODE

p11tool --list-tokens --provider /usr/lib/libkeyfactorpkcs11.so
Token 0:
	URL: pkcs11:model=Linux%00%20%20%20%20%20%20%20%20%20%00;manufacturer=Keyfactor%00%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%00;serial=1%00%20%20%20%20%20%20%20%20%20%20%20%20%20%00;token=Keyfactor%20for%20Linux%00%20%20%20%20%20%20%20%20%20%20%20%00
	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:

CODE

echo test > test.txt

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

CODE

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.

Verify

To verify the signature, run the following command:

CODE

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.