Customizing EJBCA

You can change any part of EJBCA to better suit your specific needs.

Handling Changes in a Separate Tree

You can keep your personal modifications of EJBCA in a separate tree (as of EJBCA 3.5). Set the location of your personal modifications in conf/custom.properties or use the default location '$EJBCA_HOME/../ejbca-custom'. Your modifications will automatically overwrite any existing file(s) found in the EJBCA_HOME-directory or its subdirectories before executing an 'ant'-command. A sample, conf/custom.properties.sample, is provided.

Example usage: You have a working set of configuration files and database from the latest stable release, and want to try the latest trunk snapshot.

  1. Backup your database

  2. Copy $EJBCA_HOME/conf/ to $EJBCA_HOME/../ejbca-custom/conf/

  3. Copy $EJBCA_HOME/p12/ to $EJBCA_HOME/../ejbca-custom/p12/

  4. Copy $EJBCA_HOME/src/java/.properties and modules/ejbca-common/src/.properties to $EJBCA_HOME/../ejbca-custom/src/java/ and ../ejbca-custom/modules/ejbca-common/src/

You can now remove the entire $EJBCA_HOME directory and replace it with the a fresh snapshot from the trunk. Restore the database and all the config and generated keys will be restored to $EJBCA_HOME next time you run ant deploy etc.

Note the following:

  • There is no way to recover overwritten files, so you have to manually restore files if needed.

  • Ant will not be able to detect if your changes are incompatible with newer versions of EJBCA. Always use 'diff' on the different versions to see if any file you override is affected.

  • Contributed new features or improvements that many would benefit from is greatly appreciated by the community and makes your maintenance easier.

Customizing Public Web Pages

The Public Web pages are written in JSP and can be found under modules/publicweb-gui/resources/. You can modify the pages (directly or by using a separate tree), rebuild and redeploy. The changes should show on http://ejbcahost:8080/ejbca.

Customizing Public Web Pages using ejba-custom

You can use the ejbca-custom feature to override the default files in EJBCA. To customize the Pubic Web pages, modify the style sheets and JSP pages located in modules/publicweb/resources.

Using the ejbca-custom feature, place your override files in an identical file structure in parallel, according to the following example:

ejbca
modules
publicweb
ejbca-custom
modules
publicweb

When you build using the ant build command, the files in your ejbca-custom directory will override those in the EJBCA distribution, thus making it easy to maintain the changes also when EJBCA is upgraded.

Plug-in Interfaces

There are several plug-in interfaces where you can extend functionality using your own classes:

  • Developing Custom Publishers: For more information, see Custom Publishers in Publishers.

  • Writing Customized Services: It is possible to write customized component plug-ins that can be used with other standards (or customized plug-ins). For more information, see Writing Customized Services in Services.

  • External User Data Sources: The User Data Sources framework allows importing user data from existing databases and enables importing user data from an LDAP and AD. For more information, see Framework for External User Data Sources.

  • Custom Certificate Extensions: Customized Extensions can be added and removed in the Custom Certificate Extensions tab in the System Configuration page. For more information, see Custom Certificate Extensions.

  • Custom email notification recipients: E-mail notification can be sent when a status changes for an end entity, for example when a new user is added. For more inforamtin, see E-mail Notifications.

Since it is open source, you can modify anything you like, or use any of the interfaces and create your own add-ons. See below for how to easily manage such add-ons and plug-ins.

EJBCA Plug-in Build System

In case you (for example) want to extend the RA functionality considerably, possibly including additional database tables as well, you may consider using the EJBCA plug-in scheme which provides custom applications with the core EJBCA environment data. In the directory src/samples/plug-ins you will find a couple of complete demo plug-ins that can be added to an existing EJBCA installation without any configuration. See the src/samples/plugins/README file for details. Also see conf/plugins/plugin.properties.sample for instructions how to layout and configure your plug-ins.

plug-ins are built and packaged together with the rest of the EJBCA components into the "ejbca.ear" file.

Adding Your Own Rules to Regulate the Values of End Entity Fields

It is possible to define a set of rules to control the format of the End Entity fields. For example, it is possible to ensure that the subject DN serial number is always a number of six digits, or should always end with the letter 'N'.

Setting such rules is done by implementing the static function org.ejbca.core.model.ra.FieldValidator.validate(). In this function, you can define a rule that is applicable to a specific field in a specific End Entity profile. Should the field value not match the rule, a CustomFieldException should be thrown and the error message you set in the exception will be shown as the error message in the GUI. This rule will be checked each time an end entity is added or changed, whether is was added or changed by the GUI or otherwise.

To avoid losing these rules when updating the EJBCA version, the new FieldValidator class should be stored in a ejbca-custom folder. Please see the Handling changes in a separate tree section above.