ENTERPRISE This is a SignServer Enterprise feature.

Fully qualified class name: org.signserver.module.renewal.service.RenewalTimedService

Overview

The RenewalTimedService is a timed service that can be used to periodically check the signing validity of workers and invoking the renewal worker if needed.

Setup

A typical setup with automatic renewal contains at least the following workers.

Crypto Worker

The worker holding the crypto token. Configured as usual, but needs to be separated from the worker that will be renewed, in order not to be deactivated when the worker's configuration changes during the renewal.

Renewee(s)

One or more workers that should be automatically renewed.

Each renewee requires the RENEWWORKER property, and can have additional properties:

Required property RENEWWORKER: Points out which Renewal worker to use.
Optional property RENEW_FORDEFAULTKEY: If set to true, the certificate request is sent for the current DEFAULTKEY and no key generation is performed. Default: false.
Optional property RENEW_MINREMAININGSIGNINGVALIDITY: The minimum signing validity that must remain for the worker without it to be up for renewal. This value is expressed as number of days, hours, minutes, and milliseconds in the format "*d *h *m *s *ms". Default: "0d".

Renewal worker

The worker performing the renewal. For configuration information, see RenewalWorker.

The Renewal Timed service

The worker that runs periodically and checks if a worker needs renewal. Requires a property listing each worker to check and renew if needed.

Available Properties

Property	Description
WORKERS	Comma-separated list of workers to check the validity time for, and request renewal for, if needed.

Execution

Like all timed services, the Renewal Timed Service is executed periodically. The service checks the configurations and certificates for all the configured workers and creates a list with renewal statuses for each worker. Each worker in the list configured correctly and up for renewal is then renewed by sending a request for it to the Renewal worker.

For crypto token activation, note that the workers that should be renewed must have their crypto tokens previously activated. Since only activated workers configured with a certificate will be scheduled for renewal, the worker needs to be renewed manually the first time to get its initial key and certificate. For the renewal service to work automatically, the worker that is going to be renewed must use a separate worker (i.e. a CryptoWorker) for its crypto token. If the worker has its own crypto token configuration, the token will be deactivated during the renewal process.

Troubleshooting

The complete status information of the services list renewal statuses. For example:

$ bin/signserver getstatus complete RenewalTimedService1
...
Workers Renewal Prognose:
 - TimeStampSigner (102): Renewal after: 2016-03-02 16:14:07,000, with key generation, using renewal worker "RenewalWorker1".
 - CMSSigner (3): Renewal after: 2016-02-22 16:01:00,000 (on next run), without key generation, using renewal worker "RenewalWorker1".

The example shows that:

The service is configured to manage two workers, and their names and worker ID are displayed.
Both workers have certificates configured and was active so the service will be able to determine after which date they need to be renewed.
For the CMSSigner, the renewal date has already passed and this is indicated by the text "on next run" showing that the renewal will take place as soon as the service runs.
We can assume that the CMSSigner is configured with the worker property "RENEW_FORDEFAULTKEY=true" as the status says "without key generation".
Both workers are configured with "RENEWWORKER=RenewalWorker1".

Installing a service

To install a service, use the same commands as for installing a worker:

$ bin/signserver setproperties configuration.properties

Example:

$ bin/signserver setproperties doc/sample-configs/signerstatusreport.properties
===========================================
 Executing Command on host : localhost
===========================================
Configuring properties as defined in the file : doc/sample-configs/signerstatusreport.properties
Setting the property ACTIVE to TRUE for worker 2
Setting the property INTERVAL to 10 for worker 2
Setting the global property WORKER2.CLASSPATH to org.signserver.server.timedservices.SignerStatusReportTimedService with scope GLOB.
Setting the property WORKERS to PDFSigner1 for worker 2
Setting the property NAME to SignerStatusReporter for worker 2
Setting the property OUTPUTFILE to /tmp/statusreport for worker 2
$ bin/signserver reload 2
===========================================
Executing Command on host : localhost
===========================================
SignServer reloaded successfully
Current configuration is now activated