Renewal Worker | Keyfactor Docs

The Renewal Worker can be used for generating a new key-pair and renewing a Worker's certificate from EJBCA using web services (WS).

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

Overview

The Renewal Worker should be configured with its own Crypto Token and an SSL client authentication certificate with permissions set up in EJBCA to issue certificates. Some properties are configured for the Renewal Worker, 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.

Since the keys and certificates used by the TLS connection for the web service are set up globally, it might not be possible to have multiple renewal Workers using different Crypto Tokens.

To download a sample configuration file for this Worker, see Sample Worker Configurations.

For information on the interfaces this Worker can be called through, see Supported Interfaces by Worker.

Renewal Worker Operations

The Renewal Worker 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 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 keystore. 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. From SignServer 7.6, ensure that the directory where the `TRUSTSTOREPATH` is read from is on the allowlist. See Deploy-time Configuration.
`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 Renewal Worker to use. Use this property to have the current Renewal Worker 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.

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 Example

Renewee		Request	Result
`DEFAULTKEY`	`NEXTCERTSIGNKEY`	`DEFAULTKEY`	`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

Requesting the Worker

By using a Renewal Worker and installing its certificate, Signers and other Workers can easily be renewed using the Admin Web. See the Workers Renewal Page.

As the Renewal Worker is a Worker, it can also be invoked using the normal client APIs.

Option 1: Using Client Web

Go to the Client Web.
Click Direct Input.
Specify the Worker name: MyRenewalWorker, and provide the following values:
- WORKER=MySigner
- AUTHCODE=foo123

Option 2: Using SignClient

Use the signdocument command to set the properties:

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

Note that the command is on two lines.

Initiate Renewal with Admin CLI

Use the Admin CLI to renew the Renewal Worker:

bin/signserver renewsigner MySigner -renewalworker MyRenewalWorker -authcode foo123