Quick Start Demo Setup using Administration CLI
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:
Set up a crypto token called CryptoTokenP12 which uses a keystore-based token:
$ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
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.
Sample configurations are available in doc/sample-configs which by default uses the sample crypto token:
$ bin/signserver setproperties doc/sample-configs/CONFIGURATION.properties
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:
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
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
Load the Timestamp demo configuration and notice the generated worker ID (in this example 2):
$ bin/signserver setproperties doc/sample-configs/timestamp.properties
Activate the configuration:
$ bin/signserver reload
2
Check the status and configuration:
$ bin/signserver getstatus complete all
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):
- Make sure the pdfsigner module is built in by setting
module.pdfsigner.enabled=true
andmodule.pdfsigner.include=true
in signserver_deploy.properties before building and deploying SignServer. Alternatively, setincludemodulesinbuild=true
to have all modules built in. Setup the keystore crypto token (if not already done) and activate it with its ID:
$ bin/signserver setproperties doc/sample-configs/keystore-crypto.properties
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
Load the PDF signer demo configuration and notice the generated worker ID (in this example 3):
$ bin/signserver setproperties doc/sample-configs/pdfsigner.properties
Activate the configuration:
bin/signserver reload
3
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:
Load the configuration and notice the worker IDs (in this case, 15 and 16):
$ bin/signserver setproperties doc/sample-configs/validator.properties
Activate the configuration:
$ bin/signserver reload
15
$ bin/signserver reload
16
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:
- Make sure the xmlvalidator module is built in by setting
module.xmlvalidator.enabled=true
andmodule.xmlvalidator.include=true
in signserver_deploy.properties before building and deploying SignServer. Alternatively, setincludemodulesinbuild=true
to have all modules built in. Load the XML validator demo configuration and note the generated worker ID (in this example 17):
$ bin/signserver setproperties doc/sample-configs/xmlvalidator.properties
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
Activate the configuration with:
$ bin/signserver reload
17
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:
- Make sure the mrtdsodsigner module is built in by setting
module.mrtdsodsigner.enabled=true
andmodule.mrtdsodsigner.include=true
in signserver_deploy.properties before building and deploying SignServer. Alternatively, set includemodulesinbuild=true
to have all modules built in. 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
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
Activate the configuration:
$ bin/signserver reload
8
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.