SignClient

The SignServer Client CLI SignClient is used for sending requests to the workers.

Prerequisites

Install Java OpenJDK 17.

CODE

sudo yum install -y java-17-openjdk

SignClient Setup

Run SignClient from SIGNSERVER_HOME or SIGNSERVER_HOME\bin or specify the home directory using one of the following parameters to allow running SignClient from any directory:

SIGNCLIENT_HOME: SignClient specific environment variable for specifying the home directory. Takes precedence over the SIGNSERVER_HOME variable.
SIGNSERVER_HOME: General SignServer environment variable also valid for SignClient if the SIGNCLIENT_HOME variable is not set.

CODE

$ bin/signclient
usage: signclient <signdocument | validatedocument | timestamp | validatecertificate | signdatagroups>

Configure Certificate Authentication

Mutual TLS (mTLS) authentication is a security protocol that requires both the client and server to verify each other's digital certificates before establishing an encrypted connection. To configure mTLS authentication through SignClient, you can use:

Server-Side Setup

Before configuring SignClient, you need to set up the worker to require client certificate authentication:

On the Admin Web Workers page, and select your worker.
In the Configuration tab, set AUTHTYPE = CLIENTCERT.
Click Submit.
In the Authorization tab, add a rule matching the client certificate. You can do this by loading fields from your current administrator certificate, importing fields from a local PEM file, or manually specifying the Subject (such as CN=Client One) and Issuer DN (such as CN=DSS Root CA 10,OU=Testing,O=SignServer,C=SE).

Once saved, requests will be refused unless the client authenticates via TLS and the certificate matches an authorization rule.

For more information, see Configure Client Certificate Authentication and Authorization.

Additional Configuration for Appliance Deployments

For the SignServer Hardware and Software Appliance deployments, you need to also configure a truststore with CAs classified as trustworthy.

Option 1: JKS (Java KeyStore) / PKCS#12

This is the standard software keystore approach.

If your certificate was issued by a CA (such as EJBCA), it typically comes in PKCS#12 (.p12) or PEM format. From EJBCA, you can also generate keystores directly in JKS format. See EJBCA: Create Server Certificates.

Adding Certificate to SignClient

In SignClient, use the -keystore option to provide a keystore containing your private key and certificate for client certificate authentication. Use -keystorepwd to provide the password. If -keystorepwd is omitted, SignClient will prompt for the password interactively.

The following shows a sample signdocument command using -keystore flags:

CODE

bin/signclient signdocument \
  -workername XMLSigner \
  -data "<root/>" \
  -port 8443 \
  -truststore truststore.jks \
  -truststorepwd changeit \
  -keystore client.jks \
  -keystorepwd <password> \
  -keystoretype JKS

The -truststore should contain the CA certificate that issued the server TLS certificate.

Trusting the Certificate

The truststore.jks should contain only the CA certificate. The truststore needs to be configured with the CA that issued the client authentication certificate that SignClient is trying to use.

Use the keytool command from Java to add the certificate file to the truststore.jks:

CODE

keytool -importcert -keystore dss10_admin1.jks -file example-org.pem

Provide the password and select yes to trusting the certificate.

Option 2: PKCS#11 Token

In addition to using a keystore for client certificate authentication, it is also possible to use a PKCS#11 device like a smartcard or a token.

Use the following SignClient parameters to configure authentication:

Parameter	Use Case
`-keystoretype PKCS11`	With this keystore type, the `-keystore` option should point to the PKCS#11 (cryptoki) shared library file.
`-keystoretype PKCS11_CONFIG`	With this keystore type, the `-keystore` options should point to a SunPKCS#11 configuration file.
`-keyaliasprompt`	Instead of providing the key alias with `-keyalias`, this option can be used to have SignClient prompt for which of the matching key alias to use.
`-keystorepwd`	Smartcard PIN can either be provided on the command line or if this option is not provided instead SignClient will prompt for the PIN.

The following shows an example configuration using the signdocument command:

CODE

bin/signclient signdocument \
  -workername PlainSigner \
  -data "test data" \
  -host signserver.example.com \
  -port 8443 \
  -truststore truststore.jks \
  -truststorepwd changeit \
  -keystoretype PKCS11_CONFIG \
  -keystore smartcard.cfg \
  -keyaliasprompt

Set up the file for the -keystore value based on your smartcard or token documentation:

CODE

# smartcard.cfg
name = ExampleKey
library = /usr/lib/libykcs11.so
slot = 0

SignClient Commands & Usage

The following sections cover options and sample usages of the following SignClient commands:

signdocument

timestamp

validatedocument

Client-side Hashing

validatecertificate

signdatagroups

SignWrapper-GPG

For information on logging, see Client Logging.