Overview

Customized extensions are added and removed in the Admin Web System Configuration page on the Custom Certificate Extensions tab. A simple extension only containing a static value can be added using the already implemented class BasicCertificateExtension and 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. For more information, refer to BasicCertificateExtension.java. By implementing the marker interface and setting property fields and default values, EJBCA can auto-generate a properties table for the extension.

Configuring Custom Certificate Extensions

Certificate extensions are configured on the Custom Certificate Extensions tab (Admin Web>System Configuration>Custom Certificate Extensions). 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:

Property	Description
OID	The unique Object Identifier (OID) of the extension. Mandatory value. May also be defined as a wildcard identifier.
Display Name	Display name of the extension in the Edit Certificate Profile page. Mandatory value.
Class Path	Full class name of the CertificateExtension implementation class. Mandatory value.
Critical	Defines if the extension should be marked as critical in the certificate.
Required	By default enabled, making the extension value required. Either from the configured static value or by requested dynamic value. Clearing Required allows a request to optionally contain the defined extension. In its absence, it will be ignored.
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.

Wildcard OID

The extension OID may be configured as a wildcard, e.g. *.1.2.3. Doing this will match the configuration with any requested OID, matching the pattern (i.e. ending with .1.2.3). Once matched, the dynamic value from the request will be used in the certificate. Since the wildcard in itself isn't a valid OID, an actual OID which matches the wildcard must always be present in the request (unless Required is cleared, in which case it is ignored). Hence, wildcard configurations cannot fall back on the defined static value if the extension is missing from the request.

Removing a Custom Certificate Extension

If removing a custom certificate extension, currently in use in a certificate profile, from the list of available extensions in the Custom Certificate Extensions, a warning is displayed listing the certificate profiles using the extension. The extension will not be removed from the certificate profile since it is still used but the removed extension will not be usable or be 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 a extension in use from the certificate profile, manually clear the extension from the list of Used Custom Certificate Extensions on the Edit Certificate Profile page.

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').

The following table lists available encodings and how their value is interpreted.

Encoding	Value
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	Empty value, not used.
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 property dynamic is configured to true, the extension value may be taken from extension data supplied with the end entity. For more information on how to add extension data using the Admin Web, see Custom Certificate Extension Data.

Implementing an Advanced Certificate Extension

To create an advanced extension, you need 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 necessarily 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. For more information, refer to BasicCertificateExtension.java.

In addition to static values defined Admin Web>System Configuration>Custom Certificate Extensions, 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.

The following shows an example of an advanced extension. To add this extension to EJBCA create a new Extension on System Configuration>Custom Certificate Extensions and make sure the full class name is specified in the Class Path property and that 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");
	}
} 