Services

The EJBCA framework for timer services handles procedures that run on a timely basis, performing various background tasks.

Service Types

The following services types are available:

Service Name	Description
Certificate and CRL Reader Service	Populates a VA with certificates and CRLs sent from a CA using the SCP Publisher.
Certificate Expiration Check Service	Checks if a CA has certificates about to expire and sends an email notification to the end user and/or the administrator.
CRL Download and CRL Update Service	Periodically downloads a CRL from the provided URL and imports it into EJBCA, also updating any revocation information for the certificates.
CRL Updater Service	Checks if any of the configured CAs need a new CRL and generates it if necessary
Database Maintenance Service	Performs a database cleanup by removing expired certificates and CRLs.
HSM Keepalive Service	The PKCS#11 protocol is fragile in terms of timeouts, so this service will periodically test all available crypto tokens by performing a test signing in order to avoid session timeouts to the HSM.
Microsoft Intune Certificate Revocation	Allows EJBCA to revoke certificates via Intune. Given an Intune tenant, the service worker pulls revocation requests from Microsoft Intune and performs certificate revocation internally.
OAuth Key Update Worker	Periodically downloads public keys for the configured OAuth providers and updates the internal configuration accordingly.
OCSP Response Pre-Signer	Generates, persists and updates OCSP Responses for the configured CAs.
Publisher Queue Process Service	Maintains a queue of publishing operations, periodically retrying any that have failed.
Remote Internal Key Binding Updater	Automatically renews expiring OCSP signing certificates and keys at a connected VA.
Renew CA Service	Checks if CA certificates are about to expire and automatically renews them.
Rollover Service	Periodically checks if any CAs are waiting to be rolled over if a rollover certificate has been installed.
User Password Expire Service	Checks if a user has not enrolled for a new certificate within a specified amount of time after the user was last edited. If the user has not enrolled within this time, the user's status is set to Generated and the user will not be able to enroll.

EJBCA also allows you to write plug-ins for customized services. For more information, see Writing Customized Services.

Service Configuration

A service consists of the following components: a worker doing the actual work, an interval determining the time to the next time the service should run, and an optional action of what should be performed if a certain condition occurs.

Workers

The worker is the class that will be executed when the service runs. Each worker can have a different worker-specific configuration.

Intervals

Periodical Interval

Defines in days/hours/minutes/seconds of how often the worker will be run.

A worker should never be configured to run more often than the time a single invocation takes.

Actions

Mail Action

Action that sends an email notification when the service is executed and has the following settings:

Sender Address: The from-address used in the email.
Receiver Address: The to-address of the email of not specified by the worker.

Pin to Specific Node(s)

Allows choosing on which nodes the service is allowed to execute. By not choosing any nodes in the list, the service can be executed on any of the nodes.

On EJBCA startup, each node adds its hostname to the list of nodes. The list can also be manually edited on the System Configuration page.

Run on all Nodes

By default, services execute on only one node in a cluster or one of the pinned nodes. However, certain services like the HSM Keepalive service should be run on all nodes.

Selecting Run on all nodes disables checking if a service has been running on another node and executes the service on all nodes.

The Run on all nodes option should normally only be enabled for the HSM Keepalive service. Do not select the option for any other service unless you are absolutely sure you know what you are doing.

Multiple Services and Clustering

A service worker, except the HSM Keepalive service, should never run simultaneously on two nodes (or more than one instance of a worker running at a time on one node for that matter). To avoid running more than one instance on a single node there is a semaphore that inhibits more than one instance of the worker to run in a single JVM. If a worker starts and another worker is already running the worker is rescheduled to run on the next planned interval, and immediately terminated. To avoid running any two services on two nodes simultaneously, the service has a time stamp that is set when it runs and schedules the next run before the actual work is started. This time stamp makes it possible for another node to determine if the service is already running on another node and if so, does not start running.

In practice what this leads to is that a service will always run on a single node, the same node every time, but the running node may switch at times.

For most cases, you do not have to pin a service to a specific node. Some reasons to pin nodes are:

HSM Keepalive services: This service should have one service running on each node, since it should keep the local PKCS#11 session alive.
External RA service: If having multiple RAs and running very often there may be a race condition with services competing to run. Pinning services to run on different cluster nodes towards different External RAs can increase performance and enhance simplicity.

Writing Customized Services

It is possible to write customized component plug-ins that can be used with other standards (or customized plug-ins) and this section explains the steps necessary.

Common for all the components is that it is required to create a class implementing the components interface. Then you have to create a special jar containing the necessary plug-in classes and meta-data (described below) and deploy it to the application server so it is included in the class-path. The next step is to create a service using the custom class and optionally the custom properties used by the component. The properties field has the same syntax as a regular Java property file.

The Jar must contain meta-data that describes which classes implement which interfaces. This is necessary since EJBCA enumerates all implementations using the ServiceLoader facility of Java. For each implemented interface the Jar must contain a file named META-INF/services/name.of.interface, for example META-INF/services/org.ejbca.core.model.services.IWorker. Each such file should contain a list of implementing classes, one per line. For example:

# Example file. Should be named META-INF/services/org.ejbca.core.model.services.IWorker
com.example.ejbca.MyWorker
com.example.ejbca.MyOtherWorker

XML

It is not possible to hot-deploy EJBCA when customized services are used.

CustomWorker

A Custom worker must implement the org.ejbca.core.model.services.IWorker interface. But a simpler way is to inherit the BaseWorker class. Then you have to implement one method 'void work()' doing the actual work every time the service framework decides it is time. The work method can make a call to the action (optional) component by 'getAction().performAction(someActionInfo);' The action info can vary depending on the action component, but it must implement the ActionInfo interface.CustomWorker

If something goes wrong during the work should a ServiceExecutionFailedException be thrown with a good error message.

See org.ejbca.core.model.services.workers.DummyWorker for an example implementation.

CustomInterval

A Custom Interval must implement the org.ejbca.core.model.services.IInterval interface. But a simpler way is to inherit the BaseInterval class. You then have to implement one method 'public long getTimeToExecution();' which should return the time in seconds until the next time the service is run. Or it should return DONT_EXECUTE if the service should stop running.

See org.ejbca.core.model.services.intervals.DummyInterval for an example implementation.

CustomAction

A Custom Action must implement the org.ejbca.core.model.services.IAction interface.

A simpler way is to inherit the BaseAction class. Then only the method 'performAction(ActionInfo actionInfo)' needs to be implemented. The methods should perform the action according to the defined properties and the ActionInfo (all optional). If something goes wrong during the processing of the action should a ActionException be thrown.

See org.ejbca.core.model.services.actions.DummyAction for an example implementation.