This quick start guide describes how to use the SignServer Administration CLI (AdminCLI) to set up a crypto token and a set of workers/signers for testing and demonstration purposes.

Setup a Sample Crypto Token

To set up a sample crypto token, do the following:

  1. Set up a crypto token called CryptoTokenP12 which uses a keystore-based token:

    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
  2. Activate the configuration using the assigned worker ID that was printed (for example, 1):

    $ bin/signserver reload 1

Setup Sample Workers

Workers can then be set up using the setproperties followed by the reload command.

  1. Sample configurations are available in doc/sample-configs which by default uses the sample crypto token:

    $ bin/signserver setproperties doc/sample-configs/CONFIGURATION.properties
  2. Activate the configuration using the assigned worker ID that was printed (for example, 2):

    $ bin/signserver reload 2

For examples for specific workers, see the following sections.


Setup a Sample Time-stamp Signer

Follow the steps below to set up a demo Time Stamp service (TSA according to RFC3161) and get an understanding of the structure of SignServer works:

  1. Set up the keystore crypto token (if not already done) and activate it with its ID:

    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
  2. Update the crypto token's KEYSTOREPATH property to point to a PKCS#12 keystore containing keys and certificate suitable for timestamp signing (the sample keystore in res/test/dss10/dss10_keystore.p12 can be used).
    Update the keystore password and set the crypto token's default key:

    $ bin/signserver setproperty 1 KEYSTOREPATH $SIGNSERVER_HOME/res/test/dss10/dss10_keystore.p12
    $ bin/signserver setproperty 1 KEYSTOREPASSWORD foo123
    $ bin/signserver setproperty 1 DEFAULTKEY "ts00003"
    $ bin/signserver reload 1
  3. Load the Timestamp demo configuration and notice the generated worker ID (in this example 2):

    $ bin/signserver setproperties doc/sample-configs/timestamp.properties
  4. Activate the configuration:

    $ bin/signserver reload 2
  5. Check the status and configuration:

    $ bin/signserver getstatus complete all
  6. Run the test client to confirm that the setup is successful:

    $ bin/signclient timestamp http://localhost:8080/signserver/process?workerName=TimeStampSigner

The message "TimeStampRequest validated" should appear once a second. Also, check that successful messages appear in JBOSS_HOME/standalone/log/server.log or GLASSFISH_HOME/domains/domain1/logs/server.log.

Setup a Sample PDF Signer

To install the PDF signer, issue the following commands (either instead of the Time Stamp service (TSA) or in addition to the TSA):

  1. Make sure the pdfsigner module is built in by setting module.pdfsigner.enabled=true and module.pdfsigner.include=true in signserver_deploy.properties before building and deploying SignServer. Alternatively, set includemodulesinbuild=true to have all modules built in.

  2. Setup the keystore crypto token (if not already done) and activate it with its ID:

    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
  3. Update the crypto token's KEYSTOREPATH property to point to a PKCS#12 keystore containing keys and certificate suitable for document signing (the sample keystore in res/test/dss10/dss10_keystore.p12 can be used).
    Update the keystore password and set the crypto token's default key.

    $ bin/signserver setproperty 1 KEYSTOREPATH $SIGNSERVER_HOME/res/test/dss10/dss10_keystore.p12
    $ bin/signserver setproperty 1 KEYSTOREPASSWORD foo123
    $ bin/signserver setproperty 1 DEFAULTKEY "signer00003"
    $ bin/signserver reload 1
  4. Load the PDF signer demo configuration and notice the generated worker ID (in this example 3):

    $ bin/signserver setproperties doc/sample-configs/pdfsigner.properties
  5. Activate the configuration:

    bin/signserver reload 3
  6. Check the status and configuration:

    $ bin/signserver getstatus complete all

You can now access the URL http://localhost:8080/signserver/clientweb/pdfsign.jsp with your web browser to get PDF documents signed.


Setup a Sample XML validator

An XML validator validates the signature of an XML document. The XML validator uses a certificate validation service worker for validating the certificate and thus that worker needs to be configured first.

To install two sample certificate validation service workers with IDs 15 and 16, issue the following commands:

  1. Load the configuration and notice the worker IDs (in this case, 15 and 16):

    $ bin/signserver setproperties doc/sample-configs/validator.properties
  2. Activate the configuration:

    $ bin/signserver reload 15
    $ bin/signserver reload 16
  3. The status of the workers can now be viewed with:

    $ bin/signserver getstatus complete CRLValidator
    $ bin/signserver getstatus complete OCSPValidator

Then, to install the XML validator, issue the following commands:

  1. Make sure the xmlvalidator module is built in by setting module.xmlvalidator.enabled=true and module.xmlvalidator.include=true in signserver_deploy.properties before building and deploying SignServer. Alternatively, set includemodulesinbuild=true to have all modules built in.
  2. Load the XML validator demo configuration and note the generated worker ID (in this example 17):

    $ bin/signserver setproperties doc/sample-configs/xmlvalidator.properties
  3. Verify the configuration and note that VALIDATIONSERVICEWORKER is set to "CertValidationWorker" but needs to be changed to either CRLValidator or OCSPValidator.

    $ bin/signserver setproperty 17 VALIDATIONSERVICEWORKER OCSPValidator
  4. Activate the configuration with:

    $ bin/signserver reload 17
  5. The status of the validator can now be viewed with:

    $ bin/signserver getstatus complete DemoXMLValidator

The SignServer APIs can now be used to request XML documents to be validated by the DemoXMLValidator worker.


Setup a Sample MRTD SOD Signer

The MRTD SOD signer takes data group hashes as input and creates a signed SO(d), allowing SignServer to function as a Document Signer for ePassports.

To install the MRTD SOD signer, issue the following commands:

  1. Make sure the mrtdsodsigner module is built in by setting module.mrtdsodsigner.enabled=true and module.mrtdsodsigner.include=true in signserver_deploy.properties before building and deploying SignServer. Alternatively, set includemodulesinbuild=true to have all modules built in.
  2. Setup the soft crypto token (if not already done) and activate it with its ID:

    $ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
    $ bin/signserver reload 1
  3. Load the MRTD SOD signer demo configuration and notice the generated worker ID (in this example 8):

    $ bin/signserver setproperties doc/sample-configs/mrtdsodsigner.properties
  4. Activate the configuration:

    $ bin/signserver reload 8
  5. The status of the signer can now be viewed with:

    $ bin/signserver getstatus complete mrtdsodsigner

The SignServer APIs can now be used to send MRTD SOD sign requests to the MRTDSODSigner. Additionally, you can use the HTML page http://localhost:8080/signserver/demo/mrtdsodsign.jsp to enter requests and get the SOd back. This HTML form also functions as a sample to show how you can make HTTP requests from the personalization system to the Document Signer.


Setup a Production Configuration with HSM

To install a production signer using an HSM instead of the CryptoTokenP12, make a copy of doc/sample-configs/pkcs11-crypto.properties and configure the necessary properties for the HSM and apply that file using setproperties and reload with its worker ID. Note that you need to reload the file using setproperties after changing properties in the file.

Before starting with an HSM installation, review the PKCS11CryptoToken page.

When configuring a worker, make sure to have the worker property CRYPTOTOKEN=CryptoTokenP11:

bin/signserver setproperties doc/sample-configs/pkcs11-crypto.properties
bin/signserver reload 9
bin/signserver setproperties doc/sample-configs/mrtdsodsigner.properties
bin/signserver setproperty 10 CRYPTOTOKEN CryptoTokenP11
bin/signserver reload 10
bin/signserver activatecryptotoken 9 tokenpin
bin/signserver generatecertreq 9 "C=SE,CN=MRTD SOD Signer" SHA256WithRSA mrtdsodsigner.req

where 9 is the workerId that you got when running the setproperties command for the pkcs11 crypto token.
where tokenpin is the password for the HSM slot configured in the properties file.

This will create a certificate request that you can get signed by your CA. When you have received the response, you can import it and the CA certificate. If you have the returned signer certificate as cert.pem and the CA certificate as cacert.pem, then:

cat cert.pem cacert.pem > certchain.pem
bin/signserver uploadsignercertificate 10 glob cert.pem
bin/signserver uploadsignercertificatechain 10 glob certchain.pem
bin/signserver reload 9

Note that you can use the EJBCA tool Client Toolbox to create keys on a PKCS#11 HSM:

ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so 2048 DSSignKey 5

For more information, refer to the EJBCA documentation section https://keyfactor.atlassian.net/wiki/spaces/EJBCADS/pages/238900607.