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, and other properties should be set on the worker to be renewed (the renewee) and some arguments are provided when the worker is invoked.
Note the known limitation that it might not be possible to have multiple renewal workers using different crypto tokens, since the keys and certificates used by the TLS connection for the web service is setup globally.
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 Renew signer dialog 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:
WORKER=MySigner
AUTHCODE=foo123Using the Client CLI
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:
bin/signserver renewsigner MySigner -renewalworker MyRenewalWorker -authcode foo123RenewalWorker Operations
The RenewalWorker starts by generating a new key-pair. That is, 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 and the DEFAULTKEY property is updated with the value from the NEXTCERTSIGNKEY property, and this property is then removed.
Worker Properties
| Property | Description |
|---|---|
| EJBCAWSURL | URL to the EJBCA. Must be specified. Example: https://ca.example.com:8443/ejbca |
| TRUSTSTOREPATH | Path to the keystore containing the CA's SSL server certificate as a trusted entry. Used 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. Used instead of TRUSTSTOREPATH. If this property is not specified, TRUSTSTOREPATH must be set. If TRUSTSTORETYPE is not PEM, the keystore is stored in the property in base64 encoding. |
| TRUSTSTORETYPE | Type of keystore. JKS and PEM is supported. This property must be set. |
| TRUSTSTOREPASSWORD | Password protecting the truststore keystore. This property must be set if TRUSTSTORETYPE is not PEM. |
| KEYSTOREPASSWORD | The password that locks the key-store. Required for JKS. |
| DEFAULTKEY | Key alias to use from the crypto token. This property must be set. |
Properties of renewee
| Property | Description |
|---|---|
| RENEWENDENTITY | Name of the existing end entity in EJBCA. |
| REQUESTDN | Subject DN to set in the certificate signing request (PKCS#10). |
| SIGNATUREALGORITHM | Signature algorithm to use when signing the certificate signing request (PKCS#10). |
| KEYALG | Algorithm for the key generation. Examples: RSA, DSA or ECDSA. |
| KEYSPEC | Key length (for RSA or DSA) or curve name (for ECDSA). Examples: 2048, 4096, secp256r1. |
| EXPLICITECC | True if explicit domain parameters should be used instead of NamedCurves. Default: false. |
| RENEWWORKER | Name of the default RenewalWorker to use (Required when using a RenewalTimedService otherwise optional). Specify this to have the current RenewalWorker already selected in the AdminWeb when renewing signers. |
| DEFAULTKEY | Key alias for the current existing key. The worker will update this property. |
| NEXTCERTSIGNKEY | 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. |
Request Properties
| Property | Description |
|---|---|
| WORKER | Name of the worker that should be renewed. |
| AUTHCODE | HSM/keystore password for activation. |
| FORDEFAULTKEY | If the current key should be used instead of the next key or a new key. (Optional, default: false) |
Response Properties
| Property | Description |
|---|---|
| RESULT | OK if the renewal succeeded otherwise FAILURE. |
| MESSAGE | Error message if any. |
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 | |