ENTERPRISE  This is a SignServer Enterprise feature.

Fully qualified class name: org.signserver.module.onetime.cryptoworker.OneTimeCryptoWorker

Overview

This is a specific Crypto Worker used for one-time keys and certificates allowing 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. For more information on setting up one-time keys using the OneTimeCryptoWorker, see Setting up One-time Keys.

The OneTimeCryptoWorker generates a new key-pair for each signing request, creates a certificate signing request (CSR), and uses a CA Connector to obtain a certificate issued for the CSR. One-time keys are not stored once the signature has been created and the key is deleted from the CryptoToken (i.e. the HSM) after signing.

The OneTimeCryptoWorker internally requires a PKCS11CryptoToken referenced by the CRYPTOTOKEN property to use as the source crypto token.

When using the OneTimeCryptoWorker, enable the CESeCore keystore caching by setting cryptotoken.keystorecache=true in conf/cesecore.properties (by default disabled).

The following displays an overview of the OneTimeCryptoWorker operations:

  • The Source Crypto Worker contains a Crypto Token in order to communicate with the HSM and perform key operations. The TLS key is created in the HSM using the Source Crypto Token.

  • The One Time Crypto Worker generates a new key-pair for each signing request, creates a certificate signing request (CSR), and uses a CA Connector to obtain a certificate issued for the CSR. One-time keys are not stored once the signature has been created and the key is deleted from the CryptoToken (i.e. the HSM) after signing.

  • The One Time Crypto Worker references the Source Crypto Worker to get hold of the TLS key/certificate in order to connect to EJBCA CA and also to perform one time key creation/deletion operations in HSM before/after signing respectively.

  • The XAdeSSigner references the One Time Crypto Worker in order to perform a signing operation. The signer is configured with a Username Authorizer to provide the user data used by the CA for certificate issuance.

Worker Properties

Common Properties

Property

Description

CRYPTOTOKEN

Name of (crypto) worker holding (for instance) the PKCS11CryptoToken to use as the source crypto token.

(warning) When using the PKCS11CryptoToken, ensure to set CACHE_PRIVATEKEY=false as each request should use a new key pair.

KEYALG

Key algorithm to be used for key generation. Required.
Example: RSA, ECDSA

KEYSPEC

Key specification to be used for key generation. Required.
Example: 2048, prime256v1

KEYALIAS_PREFIXKey alias prefix. Default: onetime-
CACONNECTOR_IMPLEMENTATION

CA connector implementation class. Required.
Example:

org.signserver.module.onetime.caconnector.EjbcaPeersCAConnector
org.signserver.module.onetime.caconnector.EjbcaWSCAConnector
org.signserver.module.onetime.caconnector.SelfSignedCAConnector

CA Connector Properties

EJBCA Peers CA Connector

The EJBCA Peers CA Connector uses EJBCA Peer Systems for issuing certificates. See Peer Systems for information on setting up a peer connection, additionally enabling the Process incoming requests option for the Peer Connector in EJBCA (EJBCA Admin Web>Peer Systems).

This EJBCA Peers CA Connector uses EJBCA Peers in a mode where SignServer acts as the RA and posts certificate signing requests to the CA over the peer connection. The CA Connector also maps the SignServer User Credentials (username) to the user data required by EJBCA to issue the certificate. The mapping can use data forwarded via JWT Bearer token using JWT Authorizer. All claim values of a token accesible via pattern <JWT.Claim_Name1> in the corresponding Subject alternative name, Subject DN and User name patterns.

PropertyDescription
CANAMECA name. Required.
CERTIFICATESTARTTIMECertificate start time. Optional.
CERTIFICATEENDTIMECertificate end time. Optional.
CERTIFICATEPROFILECertificate profile. Required.
EJBCAWSURLEJBCA Web Service URL. Required.
ENDENTITYPROFILEEnd entity profile. Required.
CERTSIGNATUREALGORITHMSignature algorithm used to sign the certificate signing request (CSR). Required.
SUBJECTALTNAME_PATTERN

Subject alternative name pattern used to derive the Subject Alternative Names attribute of the certificate to be issued. Examples: dNSName=signservertest. Optional.

Example subject alternative names:
rfc822Name=<email>
dNSName=<host name>
uri=<http://host.com/>
ipaddress=<address>
upn=<MS UPN>
guid=<MS globally unique id>
directoryName=<LDAP escaped DN>
krb5principal=<Krb5 principal name>

SUBJECTDN_PATTERN

Subject DN pattern used to derive the SUBJECT DN (Distinguished Name) of the certificate to be issued. Required.
Example: CN=User ${username},UID=${transactionId},O=SignServer Testing,C=SE
(warning) The username is the name of the SignServer logged-in user, and the transactionId is a SignServer internal random alphanumeric number unique for each signing request.

JWT Example: CN=${JWT.firstName} ${JWT.lastName},UID=${transactionId},O=SignServer Testing,C=SE
The firstName and lastName are corresponding claims of JWT token.

USERNAME_PATTERN

User name pattern used to derive the user name for the end entity which is registered before the certificate issuance. Required.
Example: onetime-${transactionId}
(warning) The transactionId is a SignServer internal random alpha numeric number unique for each signing request.

JWT Example: onetime-${transactionId}-${JWT.iat}
The iat is issued at time of JWT token.

EJBCA WS CA Connector

The EJBCA WS CA Connector connects to EJBCA using Web Services in the same way as the RenewalWorker.

The CA Connector maps the SignServer User Credentials (username) to the user data required by EJBCA to issue the certificate.

PropertyDescription
CANAMECA name. Required.
CERTIFICATESTARTTIMECertificate start time. Optional.
CERTIFICATEENDTIMECertificate end time. Optional.
CERTIFICATEPROFILECertificate profile. Required.
EJBCAWSURLEJBCA Web Service URL. Required.
ENDENTITYPROFILEEnd entity profile. Required.
CERTSIGNATUREALGORITHMSignature algorithm used to sign the certificate signing request (CSR). Required.
SUBJECTALTNAME_PATTERNSubject alternative name pattern used to derive the Subject Alternative Names attribute of the certificate to be issued. Example: dNSName=signservertest. Optional.

Example subject alternative names:
rfc822Name=<email>
dNSName=<host name>
uri=<http://host.com/>
ipaddress=<address>
upn=<MS UPN>
guid=<MS globally unique id>
directoryName=<LDAP escaped DN>
krb5principal=<Krb5 principal name>
SUBJECTDN_PATTERN

Subject DN pattern used to derive the SUBJECT DN (Distinguished Name) of the certificate to be issued. Required.
Example: CN=User ${username},UID=${transactionId},O=SignServer Testing,C=SE
(warning) The username is the name of the SignServer logged-in user, and the transactionId is a SignServer internal random alpha numeric number unique for each signing request.

TLSCLIENTKEYTLS client key. Required.
TRUSTSTOREPASSWORDTrust store password.
TRUSTSTOREPATHTrust store path. Either TRUSTSTOREPATH or TRUSTSTOREVALUE is required.
TRUSTSTOREVALUETrust store value. Either TRUSTSTOREPATH or TRUSTSTOREVALUE is required.
TRUSTSTORETYPE

Trust store type. Required.
Example: PEM, JKS

USERNAME_PATTERNUser name pattern used to derive the user name for the end entity which is registered before the certificate issuance. Required.
Example: onetime-${transactionId}
(warning) The transactionId is a SignServer internal random alpha numericnumber unique for each signing request.

Self-Signed CA Connector

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

PropertyDescription
CERTSIGNATUREALGORITHMSignature algorithm used for self-signing the certificate and for signing the certificate signing request (CSR). Required.