Skip to main content
Skip table of contents

Setting up One-time Keys

ENTERPRISE

One-time keys and certificates allow you to have a large number of individual signing keys and certificates, despite the often limited storage capabilities of HSMs. One-time keys are created on request and are deleted once the signature has been created.

One-time keys use a specific crypto worker called OneTimeCryptoWorker. The crypto worker references a regular crypto token used to generate the short-lived key-pair. Every time a signer requests a crypto instance from the OneTimeCryptoWorker, a new key-pair is generated and a certificate for the public key is obtained from a CA Connector component.

SignServer allows multiple implementations of the CA component. The following describes how to set up one-time keys either using the Self-Signed CA Connector for testing purposes or using the EJBCA Peers CA Connector or the EJBCA WS CA Connector to connect to the EJBCA.

Step 1: Set Up Crypto Worker with Source Crypto Token 

Make sure you have a CryptoWorker with a source PKCS11CryptoToken set up.

The following shows a source crypto worker CryptoTokenP11 sample configuration pkcs11-crypto.properties:

Sample source crypto worker configuration

CODE 
WORKERGENID1.TYPE=CRYPTO_WORKER
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.server.signers.CryptoWorker
WORKERGENID1.CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.server.cryptotokens.PKCS11CryptoToken

# Name for other workers to reference this worker:
WORKERGENID1.NAME=CryptoTokenP11

# Name of the PKCS#11 shared library to use: 
WORKERGENID1.SHAREDLIBRARYNAME=Utimaco

# HSM slot details
WORKERGENID1.SLOTLABELTYPE=SLOT_NUMBER
WORKERGENID1.SLOTLABELVALUE=1
WORKERGENID1.PIN=foo123

#One key to test activation with is required. If this key does not already exist generate it after the worker has been created.
WORKERGENID1.DEFAULTKEY=testkey0

Step 2: Set Up One-time Crypto Worker Referencing the Source Crypto Worker

Next, set up a OneTimeCryptoWorker referencing the source CryptoWorker. You can choose to test the OneTimeCryptoWorker without an actual CA by setting up the Self-signed CA Connector that generates its own self-signed certificate, using the EJBCA Peers CA Connector that uses EJBCA Peer Systems to request certificates from EJBCA, or EJBCA WS CA Connector that connects to EJBCA using Web Services.

Self-Signed CA Connector

The Self-Signed CA Connector generates its own self-signed certificate and is suitable for testing the OneTimeCryptoWorker without requiring a real CA.

To configure the Self-Signed CA Connector and set up a crypto worker referencing the source crypto worker, do the following:

  1. Add a new worker using the template onetime-crypto.properties. See OneTimeCryptoWorker properties for details.

    PropertyValue
    NAMEUpdate as appropriate, for example P11 or P12 and possibly slot.
    CACONNECTOR_IMPLEMENTATIONorg.signserver.module.onetime.caconnector.SelfSignedCAConnector
    CERTSIGNATUREALGORITHM
    SHA256WithRSA

    Example Configuration Sample
    The following shows a sample configuration onetime-crypto.properties for a crypto worker CryptoTokenP11OneTimeSelfSigned:

    Sample Configuration

    CODE 
    WORKERGENID1.TYPE=CRYPTO_WORKER
 
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.onetime.cryptoworker.OneTimeCryptoWorker
 
# Name for other workers to reference this worker:
WORKERGENID1.NAME=CryptoTokenP11OneTimeSelfSigned
 
# References a source CryptoToken
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11
 
# Key generation
WORKERGENID1.KEYALG=RSA
WORKERGENID1.KEYSPEC=2048
 
# CA Connector: Self-signed demo connector (not using a real CA)
WORKERGENID1.CACONNECTOR_IMPLEMENTATION=org.signserver.module.onetime.caconnector.SelfSignedCAConnector

# CSR & Certificate Signing
WORKERGENID1.CERTSIGNATUREALGORITHM=SHA256WithRSA

  2. Check that the status of the worker is ACTIVE, either on the SignServer Admin Web Worker Status page, or in the CLI using the command: ./bin/signserver getstatus brief.

EJBCA Peers CA Connector

The EJBCA Peers Connector uses EJBCA Peer Systems to request certificates from an EJBCA instance.

To configure the EJBCA Peers CA Connector and set up a crypto worker referencing the source crypto worker, do the following:

  1. Add a new OneTimeCryptoWorker using the template onetime-crypto.properties and make the following changes. See OneTimeCryptoWorker properties for details.

    PropertyValue
    NAMEUpdate as appropriate, for example, P11 or P12, and possibly slot.
    CACONNECTOR_IMPLEMENTATIONEnable the following by removing the comments for the EjbcaWSCAConnector properties:
    • CACONNECTOR_IMPLEMENTATION=org.signserver.module.onetime.caconnector.EjbcaPeersCAConnector
    • CANAME
    • ENDENTITYPROFILE
    • CERTIFICATEPROFILE
    • USERNAME_PATTERN
    • SUBJECTDN_PATTERN
    • SUBJECTALTNAME_PATTERN
    • CERTIFICATESTARTTIME
    • CERTIFICATEENDTIME

    CERTSIGNATUREALGORITHM

    SHA256WithRSA

    Example Configuration

    The following shows a sample configuration onetime-crypto.properties for a crypto worker CryptoTokenP11OneTimeEjbcaPeers:

    CODE 
    WORKERGENID1.TYPE=CRYPTO_WORKER

WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.onetime.cryptoworker.OneTimeCryptoWorker

# Name for other workers to reference this worker:
WORKERGENID1.NAME=CryptoTokenP11OneTimeEjbcaPeers

# References a source CryptoToken
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11

# Key generation
WORKERGENID1.KEYALG=RSA
WORKERGENID1.KEYSPEC=2048

# CA Connector: EjbcaPeers (using EJBCA through Peer Connections)
WORKERGENID1.CACONNECTOR_IMPLEMENTATION=org.signserver.module.onetime.caconnector.EjbcaPeersCAConnector

WORKERGENID1.ENDENTITYPROFILE=EMPTY
WORKERGENID1.CERTIFICATEPROFILE=ENDUSER
WORKERGENID1.USERNAME_PATTERN=onetime-${transactionId}
WORKERGENID1.SUBJECTDN_PATTERN=CN=User ${username},UID=${transactionId},O=SignServer Testing,C=SE 

# CSR & Certificate Signing
WORKERGENID1.CERTSIGNATUREALGORITHM=SHA256WithRSA
  2. Setup an EJBCA Peer connection as described in Peer Systems and also ensure to enable the Process incoming requests option for the Peer Connector in EJBCA (EJBCA Admin Web>Peer Systems), see EJBCA documentation on Adding an Outgoing Peer Connection.
  3. Check that the status of the worker is ACTIVE, either on the SignServer Admin Web Worker Status page, or in the CLI using the command: ./bin/signserver getstatus brief.

EJBCA WS CA Connector

The EJBCA WS CA Connector connects to EJBCA using Web Services.

To configure the EJBCA WS CA Connector and set up a crypto worker referencing the source crypto worker, do the following:

  1. Add a new worker using the template onetime-crypto.properties and make the following changes. See OneTimeCryptoWorker properties for details.

    PropertyValue
    NAMEUpdate as appropriate, for example, P11 or P12, and possibly slot.
    CACONNECTOR_IMPLEMENTATIONEnable the following by removing the comments for the EjbcaWSCAConnector properties:
    • CACONNECTOR_IMPLEMENTATION=org.signserver.module.onetime.caconnector.EjbcaWSCAConnector
    • TRUSTSTORETYPE
    • TRUSTSTOREPATH or TRUSTSTOREVALUE (depending on TRUSTSTORETYPE)
    • TRUSTSTOREPASSWORD
    • TLSCLIENTKEY
    • EJBCAWSURL
    • CANAME
    • ENDENTITYPROFILE
    • CERTIFICATEPROFILE
    • USERNAME_PATTERN
    • SUBJECTDN_PATTERN
    • SUBJECTALTNAME_PATTERN
    • CERTIFICATESTARTTIME
    • CERTIFICATEENDTIME

    CERTSIGNATUREALGORITHM

    SHA256WithRSA

    Example Configuration Sample

    The following shows a sample configuration onetime-crypto.properties for a crypto worker CryptoTokenP11OneTimeEjbcaWS:

    Sample CryptoTokenP11OneTimeEjbcaWS Configuration

    CODE 
    WORKERGENID1.TYPE=CRYPTO_WORKER

WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.onetime.cryptoworker.OneTimeCryptoWorker

# Name for other workers to reference this worker:
WORKERGENID1.NAME=CryptoTokenP11OneTimeEjbcaWS

# References a source CryptoToken
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11

# Key generation
WORKERGENID1.KEYALG=RSA
WORKERGENID1.KEYSPEC=2048

# CA Connector: EjbcaWS (using EJBCA through Web Services)
WORKERGENID1.CACONNECTOR_IMPLEMENTATION=org.signserver.module.onetime.caconnector.EjbcaWSCAConnector
WORKERGENID1.TRUSTSTORETYPE=JKS

# To trust the TLS certificate of the CA the trust store properties must be configured and contain the issuer (i.e. CA) certificate that issued the TLS server certificate used when connecting to the CA
WORKERGENID1.TRUSTSTOREPATH=/opt/jboss-eap-6.4-ca/standalone/configuration/keystore/truststore.jks
WORKERGENID1.TRUSTSTOREPASSWORD=changeit

WORKERGENID1.TLSCLIENTKEY=tls_key
WORKERGENID1.EJBCAWSURL=https://localhost:9443/ejbca
WORKERGENID1.ENDENTITYPROFILE=EMPTY
WORKERGENID1.CERTIFICATEPROFILE=ENDUSER
WORKERGENID1.USERNAME_PATTERN=onetime-${transactionId}
WORKERGENID1.SUBJECTDN_PATTERN=CN=User ${username},UID=${transactionId},O=SignServer Testing,C=SE 

# CSR & Certificate Signing
WORKERGENID1.CERTSIGNATUREALGORITHM=SHA256WithRSA

  2. To trust the TLS certificate of the CA, the truststore properties must be configured and contain the issuer (i.e. CA) certificate that issued the TLS server certificate used when connecting to the CA. In some cases you can just point out the path to the truststore.jks from the application server where EJBCA is running.

  3. Create a TLS client key (tls_key).
  4. Generate a Certificate Signing Request (CSR) for the TLS key created in the step above, get the certificate for the CSR, and install the certificate for the key in the token.
  5. Provide Administrator access for the TLS Client certificate under the EJBCA CA Administration section, to enable the TLS client to access the CA resource (Web Service).

  6. Check that the status of the worker is ACTIVE, either on the SignServer Admin Web Worker Status page, or in the CLI using the command: ./bin/signserver getstatus brief.

Step 3: Set Up Signer with One-time Key

Configure a signer (for example the XAdESSigner) to use the following properties of your newly created CryptoWorker.

Since the user credentials are used in the certificate issuance, the signer needs to use a username or username/password authorizer, see OneTimeCryptoWorker.

PropertyChange

CRYPTOTOKEN

CryptoTokenP11OneTimeSelfSigned
or
CryptoTokenP11OneTimeEjbcaWS

AUTHTYPE

org.signserver.server.UsernameAuthorizer

ACCEPT_ALL_USERNAMES

true

ALIASSELECTORorg.signserver.server.aliasselectors.AuthorizedUsernameAliasSelector

Example Configuration Sample

The following shows a sample configuration xadessigner.properties for a CryptoTokenP11OneTimeEjbcaWS:

Sample XAdESSigner Configuration with One-time Key

CODE 
# General properties
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.xades.signer.XAdESSigner
WORKERGENID1.NAME=XAdESSigner
 
# Crypto token
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11OneTimeEjbcaWS
 
# Using one key-pair in the above crypto token
WORKERGENID1.DEFAULTKEY=tls_key

# Properties related to User Authentication & Alias selector as username will be part of Subject DN and Alias selector will be used to select key alias based on logged user name.
WORKERGENID1.AUTHTYPE=org.signserver.server.UsernameAuthorizer
WORKERGENID1.ACCEPT_ALL_USERNAMES=true
WORKERGENID1.ALIASSELECTOR=org.signserver.server.aliasselectors.AuthorizedUsernameAliasSelector
 
WORKERGENID1.SIGNATUREALGORITHM=SHA256withRSA

WORKERGENID1.XADESFORM = BES
WORKERGENID1.INCLUDE_CERTIFICATE_LEVELS=1
WORKERGENID1.COMMITMENT_TYPES = NONE

Step 4: Test and Verify Signing with One-time Keys

You can now test to sign using SignClient or test the performance using the stresstest tool.

Test Signing with SignClient

To test signing using the SignServer CLI SignClient, run the following:

CODE 
bin/signclient signdocument -workername XAdESSigner -data "<xml/>" -username user1 -password password

bin/signclient signdocument -workername CMSSigner -infile "input.txt" -username user1 -password password -outfile "output.p7s"

bin/signclient signdocument -workername JArchiveSigner -infile "HelloJar.jar" -username user1 -password password -outfile "HelloSignedJar.jar"

Note that a new certificate with a new key is used every time.

Signature Verification

  • To verify the CMS Signature through OpenSSL, run the following:

    CODE 
    openssl cms -verify -in output.p7s -inform DER -content input.txt -CAfile cacert.pem > /dev/null

  • To verify the code signature with jarsigner, run the following:

    CODE 
    jarsigner -verify -strict HelloJar_Signed.jar -certs

Performance Test using Stresstest Tool

To run a performance test using the stresstest tool, run the following:

CODE 
bin/stresstest -testsuite DocumentSigner1 -threads 20 -processurl http://localhost:8080/signserver/process -worker XAdESSigner -data "<root/>" -userprefix user -usersuffixmin 1 -usersuffixmax 500

To prevent memory leaks when generating a high number of keys, do not enable the crypto token caching (cryptotoken.keystorecache) in conf/cesecore.properties.

For more information on using the stresstest tool, see Stresstest CLI.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close