Setup a Sample Crypto Token

To setup 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

See the following section for examples for specific workers.

Setup a Sample Time-stamp Signer

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

1. Setup 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 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. It uses a certificate validation service worker for validating the certificate so that worker has to be configured first.

To install a certificate validation service worker, issue the following commands:

1. Load the configuration and notice the worker ID (in this example, 6):

   $ bin/signserver setproperties doc/sample-configs/validator_dummy.properties

2. Activate the configuration:

   $ bin/signserver reload 6

3. The status of the Worker can now be viewed with:

   $ bin/signserver getstatus complete CertValidationWorker

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 7):

   $ bin/signserver setproperties doc/sample-configs/xmlvalidator.properties

3. Verify the configuration: Note that VALIDATIONSERVICEWORKER is set to "CertValidationWorker".

   $ bin/signserver getconfig 7

4. Activate the configuration with:

   $ bin/signserver reload 7

5. The status of the Validator can now be viewed with:

   $ bin/signserver getstatus complete DemoXMLValidator

Now the SignServer APIs can be used to request XML documents to be validated by the DemoXMLValidator worker. For more information, see

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 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:

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:

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

For more information, refer to the EJBCA documentation section EJBCA Client Toolbox.