RenewalWorker

Fully-qualified class name: org.signserver.module.renewal.worker.RenewalWorker.

Overview

The RenewalWorker can be used for generating a new key-pair and renewing a worker's certificate from EJBCA using web services (WS). The RenewalWorker should be configured with its own CryptoToken and an SSL client authentication certificate with permissions set up in EJBCA to issue certificates. Some properties are configured for the RenewalWorker, such as the EJBCA WS endpoint URL and truststore details. Other properties should be set on the worker to be renewed (the renewee) and some arguments are provided when the worker is invoked.

Note that, since the keys and certificates used by the TLS connection for the web service is setup globally, it might not be possible to have multiple renewal workers using different crypto tokens.

Requesting the Worker

After setting up a RenewalWorker and installing its certificate, signers (and other workers) can easily be renewed using the SignServer AdminWeb. See the Workers Renewal Page in Administration Web.

As the RenewalWorker is a worker, it can also be invoked using the normal client APIs.

Using the Client Web

Go to the Client Web, click Direct Input and specify the Worker name: MyRenewalWorker.

Data:

CODE

WORKER=MySigner
AUTHCODE=foo123

Using the Client CLI:

CODE

bin/signclient signdocument -workername MyRenewalWorker -data "WORKER=MySigner
AUTHCODE=foo123"

Note that the command is on two lines.

Using the Admin CLI to initiate the renewal:

CODE

bin/signserver renewsigner MySigner -renewalworker MyRenewalWorker -authcode foo123

RenewalWorker Operations

The RenewalWorker starts by generating a new key-pair, unless a NEXTCERTSIGNKEY is already set for the renewee, or if the request property FORDEFAULTKEY=true is set in the request. The HSM/keystore password needs to be submitted as part of the request (AUTHCODE request property) to generate a new key-pair.

When the key-pair has been generated and tested successfully, the key alias is set as the NEXTCERTSIGNKEY property. A certificate signing request is created for the key, and the worker sends the request to EJBCA to issue a certificate for the configured end entity. After receiving the certificate and certificate chain, they are installed for the worker. The DEFAULTKEY property is updated with the value from the NEXTCERTSIGNKEY property, and this property is then removed.

Worker Properties

Property	Description
DEFAULTKEY	Specifies the key alias to use from the crypto token. Required.
EJBCAWSURL	Specifies the URL to the EJBCA. Example: `https://ca.example.com:8443/ejbca`
KEYSTOREPASSWORD	Specifies the password that locks the key-store. Required for JKS.
TRUSTSTOREPATH	Specifies the path to the keystore containing the CA's SSL server certificate as a trusted entry. Use instead of `TRUSTSTOREVALUE`. If this property is not specified, `TRUSTSTOREVALUE` must be set.
TRUSTSTOREVALUE	Keystore containing the CA's SSL server certificate as a trusted entry. If `TRUSTSTORETYPE` is not PEM, the keystore is stored in the property in base64 encoding. Use instead of `TRUSTSTOREPATH`. If this property is not specified, `TRUSTSTOREPATH` must be set.
TRUSTSTORETYPE	Specifies the type of keystore. JKS and PEM is supported. Required.
TRUSTSTOREPASSWORD	Specifies the password protecting the truststore keystore. This property must be set if `TRUSTSTORETYPE` is not PEM.

Renewee Properties

Property	Description
DEFAULTKEY	Key alias for the current existing key. The worker will update this property.
EXPLICITECC	True if explicit domain parameters should be used instead of NamedCurves. Default: False.
KEYALG	Specifies the algorithm for the key generation. Examples: `RSA`, `ECDSA`.
KEYSPEC	Specifies the key length (for RSA) or curve name (for ECDSA). Examples: `2048`, `4096`, `secp256r1`.
NEXTCERTSIGNKEY	Specifies the key alias for the next existing key. If this property exists, a new key-pair will not be generated. The worker will update/remove this property.
RENEWENDENTITY	Specifies the name of the existing end entity in EJBCA.
RENEWWORKER	Specifies the name of the default RenewalWorker to use. Use this property to have the current RenewalWorker already selected in the AdminWeb when renewing signers. The property is only required when using a RenewalTimedService.
REQUESTDN	Specifies the subject DN to set in the certificate signing request (PKCS#10).
SIGNATUREALGORITHM	Specifies the signature algorithm to use when signing the certificate signing request (PKCS#10).

Request Properties

Property

Description

AUTHCODE

Specifies the HSM/keystore password for activation.

FORDEFAULTKEY

(Optional) Specifies if the current key should be used instead of the next key or a new key.

Default: False.

WORKER

Specifies the name of the worker that should be renewed.

Response Properties

Property	Description
MESSAGE	Returns an error message, if any.
RESULT	Returns OK if the renewal succeeded. Otherwise, returns FAILURE.

Renewal Modes

Renewee DEFAULTKEY NEXTCERTSIGNKEY		Request FORDEFAULTKEY DEFAULTKEY		Result NEXTCERTSIGNKEY
-	-	-	New key and alias	Removed
present	-	-	New key and alias	Removed
-	present	-	Alias from nextcertsignkey	Removed
present	present	-	Alias from nextcertsignkey	Removed
present	-		Same alias	Same alias
present	present		Same alias	Same alias