Custom Certificate Extensions

Customized extensions can be added and removed in the Custom Certificate Extensions tab in the System Configuration page in the Admin web. A simple extension only containing a static value can be added using the already implemented class BasicCertificateExtension, but more advanced custom extensions can be made available by implementing the CustomCertificateExtension interface and making the implementation available on the classpath using Java's ServiceLoader (see the BasicCertificateExtension for how to do so). By implementing the marker interface and setting property fields and default values, EJBCA can autogenerate a properties table for the extension.

Configuring Custom Certificate Extensions

Certificate extensions are configured in the Custom Certificate Extensions tab in the System Configuration page in the Admin web. Only administrators who are granted the access rule '/system_functionality/edit_available_custom_certificate_extensions' are allowed to add and remove custom certificate extensions.

The following properties are available for each extension:

  • OID : The unique Object Identifier (OID) of the extension (Required)

  • Display Name : Display name of the extension in the Edit Certificate Profile page. (Required)

  • Class Path : Full class name of the CertificateExtension implementation class. (Required)

  • Critical : Defines if the extension should be marked as critical in the certificate.

  • Properties : Properties are inherent to each extension implementation.

When adding a new Custom Certificate Extension, the OID and the Display Name are specified and a new Extension with the following default values is created:

  • Class Path : org.cesecore.certificates.certificate.certextensions.BasicCertificateExtension

  • Critical : False

  • Properties : Empty list of properties

Click on the newly created extension to edit these values.

After extensions have been added, it is possible to select them for a certificate profile in the Edit Certificate Profile page.

Removing a Custom Certificate Extension

When removing a custom certificate extension from the list of available extensions in the Custom Certificate Extensions tab in the System Configuration page, if that extension is actually in use in a certificate profile, it is not automatically removed form that certificate profile. However, the removed extension will not be usable or be a part of any certificate issued after the removal and will be displayed as OID (No longer used. Please unselect this option) in the Edit Certificate Profile page. To remove the extension from the certificate profile, it has to be manually unselected from the list of Used Custom Certificate Extensions in the Edit Certificate Profile page.

Also when removing an extension that is in use, a warning message will be displayed listing the certificate profiles that are still using this extension.

Basic Certificate Extension

In order to create a Basic Certificate Extension, you set the Class Path to 'org.cesecore.certificates.certificate.certextensions.BasicCertificateExtension' (default setting) and specify the properties encoding and value (value is optional if there is a property 'dynamic=true'). See the following table for the available encodings and how their value is interpreted:

  • DERBITSTRING : A String containing the characters '0' and '1'.

  • DERINTEGER : A String containing digits only in decimal digits.

  • DEROCTETSTRING : A String containing hex data representation.

  • DERBOOLEAN : The string 'true' or 'false'.

  • DERPRINTABLESTRING : A string containing valid printable string characters (a-z, 0-9).

  • DERUTF8STRING : A string in UTF-8 format.

  • DERIA5STRING : An ASN.1 IA5String containing valid printable string characters (a-z, 0-9).

  • DERNULL : Value isn't used, an empty value.

  • DEROBJECT : The hex encoded DER value of the extensions. You can use this to create any extension with sequences etc.

  • RAW : The hex encoded byte array value of the extensions. You can supply any data hex encoded to be used as the extension value bytes.

Examples of certificate extensions that you can configure with the BasicCertificateExtension are given in 'src/java/certextensions.properties'.

  • MS application policies

  • NetscapeCertType

  • NetscapeComment

  • NetscapeCARevocationURL

  • NetscapeRevocationURL

  • ...

If the the property dynamic is configured to true, the extension value may be taken from extension data supplied with the end entity. See Custom certificate extension data for how this can be added from admin web.

Implementing an Advanced Certificate Extension

To create an advanced extension, it is required to create a Java class extending the CertificateExtension abstract class. The method getValue is required and the current user data, CA and certificate profile are sent to the extension in order to generate dynamic extensions.

If your advanced extension needs to return a byte array that is not necessarly an ASN.1 structure, it is possible to override the getValueEncoded method as this is the method EJBCA will call when adding the extension to the certificate. See BasicCertificateExtension.java for an example of this special case.

In addition to static values defined in the Custom Certificate Extensions tab in the System Configuration page in the Admin web, it is also possible to get values from the extension data in the end entity's extended information store. A good choice is to use the extension oid as a prefix to the key of the property to associate the value with this extension.

Here is an example of a simple advanced extension. To add this extension to EJBCA create a new Extension in the Custom Certificate Extensions tab in the System Configuration page and make sure the full class name is set in the Class Path property, also make sure the class is accessible on the classpath.

public class SomeAdvancedCertificateExtension extends CertificateExtension {
private static String PROPERTY_SOMEPROPERTY = "someproperty";
/**
* The main method that should return a byte[] with the ASN.1 encoded data to be put
in the extension valud
* using the input data (optional) or defined properties (optional)
*
* @see
org.cesecore.certificates.certificate.certextensions.CertificateExtension#getValueEncoded
*/
@Override
public byte[] getValueEncoded(EndEntityInformation userData, CA ca, CertificateProfile
certProfile, PublicKey userPublicKey,
PublicKey caPublicKey, CertificateValidity val )
throws CertificateExtentionConfigurationException, CertificateExtensionException {
try {
// Optionally get dynamic values for this extension
//String dynamicValue = userData.getExtendedinformation().getExtensionData
(getOID() + ".someotherproperty");
String value = getProperties().getProperty("FOO");
DERPrintableString asn1value = new DERPrintableString(value);
return asn1value.toASN1Primitive().getEncoded();
} catch (IOException e) {
throw new CertificateExtensionException("Error constructing certificate
extension SomeAdvancedCertificateExtension.", e);
}
}
 
/**
* @deprecated use getValueEncoded instead.
*/
public ASN1Encodable getValue(EndEntityInformation userData, CA ca, CertificateProfile
certProfile, PublicKey userPublicKey, PublicKey caPublicKey, CertificateValidity val)
throws CertificateExtensionException, CertificateExtentionConfigurationException {
throw new UnsupportedOperationException("Use getValueEncoded instead");
}