Handling Changes in a Separate Tree
Customizing the User Interface
- RA User Interface
- Public Web
  - Customizing Public Web Pages using ejba-custom
Writing Plugins
- EJBCA Plugin Build System
  - Including External JARs on the Classpath
  - Including External Source Directories
- Plugin Interfaces
Adding Your Own Rules to Regulate the Values of End Entity Fields

EJBCA, as an open source product, can naturally be customized in order to meet your specific needs. That said, modifying the source code may lead to severe compatibility problems with future versions of EJBCA and make upgrading difficult. We would rather recommend implementing plugins according to the instructions below.

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.

Backup your database
Copy $EJBCA_HOME/conf/ to $EJBCA_HOME/../ejbca-custom/conf/
Copy $EJBCA_HOME/p12/ to $EJBCA_HOME/../ejbca-custom/p12/
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 fresh snapshot from the trunk. Restore the database and all the configurations 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 the User Interface

RA User Interface

The entire CSS of the RA Web can be customized and hot-deployed by uploading a custom CSS package on the CA Web (which in the case of a remote RA connected by Peers will be automatically downloaded and deployed). For more information, see Custom RA Stylesheets.

Public Web

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.

Writing Plugins

EJBCA Plugin Build System

To for example, extend the RA functionality considerably, possibly including additional database tables as well, you may consider using the EJBCA plugin 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 plugins that can be added to an existing EJBCA installation without any configuration.

There are two methods of creating plugins for EJBCA:

Including External JARs on the Classpath

This may be the easier method for some and involves pre-compiling your own JAR (preferably using one of our plugin interfaces and a manifest file, see below) and making sure it's available on the classpath. To enable this:

Modify the file plugin.properties.sample (renaming it to for example widget.properties) and place it in either conf/plugins in your local EJBCA directory, or under ejbca_custom/conf/plugins if you're using an external configuration directory.
Make sure that the file contains the following line:

plugin.ejbca.lib.dir=/home/demo/myplugin/dist/

where the directory points to the location of your compiled JAR file.

Including External Source Directories

The other variant is to create a source directory alongside EJBCA from which EJBCA can copy source files from. While this variant may be simpler to maintain due to sourcing the EJBCA libs directly from EJBCA, it may also be more difficult to set up a development environment against. To enable this:

Modify the file plugin.properties.sample (renaming it to for example widget.properties) and place it in either conf/plugins in your local EJBCA directory, or under ejbca_custom/conf/plugins if you're using an external configuration directory.
Make sure that the file contains the following line:

plugin.ejbca.ant.file=/home/demo/myplugin/build.xml

which points to the build file of your plugin.

For more information on setting this up, see plugin.properties.sample.

Plugin Interfaces

There are several plugin interfaces where you can extend functionality using your own classes. Using any of the interfaces mentioned below, including a manifest file in the JAR and making sure that the JAR is available on the class path (see above) during construction of the EJBCA EAR will lead to the plugins automatically appearing where relevant.

Developing Custom Publishers: For more information, see Custom Publishers in Publishers.
Writing Customized Services: It is possible to write customized component plugins that can be used with other standards (or customized plugins). 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 information, 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 plugins.

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 it 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 an ejbca-custom folder. See the Handling changes in a separate tree section above.