Export and import CAs

Under certain circumstances, it can be wise to backup the CA's signature and encryption keys. Remember to protect the backup in the same way as the CA itself.

Soft token CAs can be exported and backed up. CAs with the keys on a HSM can naturally not be exported through EJBCA. Use the HSMs methods to back up such keys.

Soft token CAs can be imported using both the CLI and Admin GUI, while HSM CAs can only be imported using the CLI.

$ bin/ejbca.sh ca exportca TestCA ./TestCA.p12
Using JBoss JNDI provider...
Enter keystore password: foo123
$ 

$ bin/ejbca.sh ca importca TestCA /path/TestCA.p12 SignatureKeyAlias EncryptionKeyAlias
Using JBoss JNDI provider...
Enter keystore password: foo123
$ 

$ bin/ejbca.sh ca importca --help

Remove and restore CA soft keystore

Soft token CAs can have their keystore removed from the database. When the keystore is removed the CA can not issue certificates and its CA token status is set to 'offline'.

Warning: Before removing the keystore make sure you have exported it if you would like to be able to restore it later. See the section 'Export and import CAs'

To remove the catoken keys for "TestCA", enter the following from the $EJBCA_HOME directory:

$ bin/ejbca.sh ca removekeystore TestCA
Using JBoss JNDI provider...
$ 

To restore the catoken keys again for "TestCA" with the keystore exported as "TestCA-exported.p12", enter the following from the $EJBCA_HOME directory:

$ bin/ejbca.sh ca restorekeystore TestCA /path/TestCA-exported.p12 -s SignatureKeyAlias -e EncryptionKeyAlias
Using JBoss JNDI provider...
Enter keystore password: foo123
$ 

Renew CAs

You can renew CAs in different ways:

• Renew only CA certificate, using the same keys.
• Renew CA keys and certificate.

To renew only the CA certificate using the same keys you simply press the button "Renew CA". Your CA have to be on-line for this to work, so it can sign the new certificate if it's a self signed CA or the certificate request if it is a sub CA. Also if it is a subCA with the rootCA in the same EJBCA instance the root CA must also be on-line.

To renew the CA keys, set 'Next CA key' to '- Generate new key using KeySequence -'. After this you simply press "Renew CA".
Renewing the keys will not always work if you are using an HSM. It may work with some HSMs and not work with others.
You can report success and failures to us.

When using an HSM you can also make the renewal of keys manually. Simply generate new keys on the HSM with whatever tools you used the first time (preferably the EJBCA cli tools) and select the newly generated keys as the 'Next CA key'. Press 'Renew CA' to generate your new CA certificate.

Revoke CAs

If you want to revoke a CA you can do so by going to "Certificate Authorities" in the admin GUI. There is a button "Revoke CA".

• If you revoke a Root CA it will revoke all certificates in the database issued by the root CA, and create a CRL.
• If you revoke a Sub CA it will revoke all certificates in the database issued by the sub CA, and to the sub CA, and create a CRL. This works automatically if the sub CA and root CA is handled by the same EJBCA instance. If the Sub CA is signed by an external CA, the sub CA's certificate must be revoked by the external CA.
• If you revoke an external CA /sub CA to a CA in EJBCA) the external CAs certificate will be revoked and put on the CRL of the issuing CA in EJBCA.

Importing a Single Certificate

In order to import a single certificate, use the command:

bin/ejbca.sh ca importcert <username> <password> <caname> <status> --email <email> <certificate file> [--eeprofile <endentityprofile>] [--certprofile <certificateprofile>] [--revocation-reason <reason>] [--revocation-time <time>]

The parameters are as follows:

• username - Username of the end entity which should be owner of the certificate. If the end entity does not exist, it will be created automatically. If the end entity already exists, the imported certificate will be associated with it, and the end entity properties (subject, subject alternative names) will be updated.
• password - Password that will be set for the end entity (often called "enrollment code" in the public web).
• caname - The name of the CA which has issued the certificate. The certificate's issuer signature will be verified against this CA. If the signature does not match, the certificate will not be imported. The CA certificate must be present in the database (at least as an external CA).
• status - Status that should be set for the imported certificate. Supported values are ACTIVE (for valid certificate), and REVOKED (for revoked certificate). The revocation reason for REVOKED certificate will be set to Unspecified.
• email - E-mail that will be used for the end entity. If the e-mail is set to string null, it will be taken from the certificate itself.
• certificate file - Path to BASE64-encoded PEM file containing the end entity certificate.
• endentityprofile - End entity profile used for the certificate. The certificate will be verified against the constraints set forth by this end entity profile. If the constraints are violated by the certificate, it will not be imported. If no end entity profile is supplied, the default EMPTY profile will be used.
• certificateprofile - Certificate profile used for the certificate. Once the certificate is imported, it will be marked as belonging to the specified certificate profile. If the certificate profile is not specified, the fixed ENDUSER certificate profile will be used instead.
• revocation reason - Allows a revoked certificate to be imported with a specific revocation reason. Use the --help switch to see a list of valid revocation reasons. Will be set to UNSPECIFIED if not specified.
• revocation time - Allows a revoked certificate to be imported with a specific revocation time in the format yyyy.MM.dd-HH:mm. Will be set to the current time if not supplied.

Running the command without any parameters will display basic usage help, and a list of acceptable parameter values (for caname, status, endentityprofile, and certificateprofile).

Here's an example usage of the importcert command:

bin/ejbca.sh ca importcert myuser mypassword SomeCAName ACTIVE --email mymail@example.com mycertificate.pem --eeprofile EMPTY --certprofile ENDUSER

This command would create a new end entity (or use the existing one) in EJBCA called myuser with the supplied password, and add a new active (non-revoked) certificate for this user under the end entity profile EMPTY, using the certificate profile ENDUSER.

Importing Certificates in Bulk

In order to import certificates in bulk, use the commnad:

bin/ejbca.sh ca importcertdir <username-source> <caname> <status> <certificate dir> --eeprofile <endentityprofile> --certprofile <certificateprofile> [-resumeonerror]  [--revocation-reason <reason>] [--revocation-time <time>]

The parameters are as follows:

• username-source - Specifies how to derive the username of the end entity that will own the certificate. Supported values are CN, DN, and FILE. If set to CN, the username will be equal to the common name attribute present in the certificate subject. If set to DN, the username will be equal to the entire distinguished name (subject) of the certificate. If set to FILE, the username will be the same as the name of the file (extension included). If set to CN, and CN is not present in the subject, the import will first fall back to using DN, or if that is not available as well, to file name. If set to DN, and the subject is not present in the certificate, the import will fall back to using the file name as the username. The end entity will be automatically created if it does not exist already. If the end entity already exists, the imported certificate will be associated with it, and end entity properties will be updated.
• caname - The name of the CA which has issued the certificates. The certificate issuer signature will be verified against this CA. If the signature does not match, the certificate will not be imported. The CA certificate must be present in the database (at least as an external CA).
• status - Status that should be set for the imported certificates. Supported values are ACTIVE (for valid certificates), and REVOKED (for revoked certificates). The revocation reason for REVOKED certificates will be set to Unspecified.
• certificate dir - Path to the directory containing the certificate files. Each file should contain a single certificate. The directory should not contain subdirectories, or non-certificates. The file extension does not matter - all the files will be processed.
• endentityprofile - End entity profile used for the certificates. The certificates will be verified against the constraints set forth by the end entity profile. If the constraints are violated by the certificate, it will not be imported.
• certificateprofile - Certificate profile used for the certificates. Once the certificate is imported, it will be marked as belonging to the specified certificate profile.
• -resumeonerror - This optional switch can be used in order to force the import to proceed even if more serious errors are encountered. By default this option is not enabled. The errors that are covered by this switch, amongst others, are end entity profile constraint violations, problems with reading/parsing of certificate files etc.
• revocation reason - Allows a revoked certificate to be imported with a specific revocation reason. Use the --help switch to see a list of valid revocation reasons. Will be set to UNSPECIFIED if not specified.
• revocation time - Allows a revoked certificate to be imported with a specific revocation time in the format yyyy.MM.dd-HH:mm. Will be set to the current time if not supplied.

Running the command without any parameters will display basic usage help, and a list of acceptable parameter values (for username-source, status, endentityprofile, and certificateprofile).

Certificates that are already present in the database will be skipped during the import. Certificates that belong to a different CA than the one specified will be skipped as well. Any other discrepancy (like invalid file format, subdirectory, or violated end entity constraints) will stop the import operation, unless the -resumeonerror switch has been enabled. Certificates that have been imported up until the discrepancy will still remain in the database. For each certificate that has been skipped, the command will output its serial number and name of the file. The same information will be displayed for errors.

Once the import has finished, a short summary is displayed about the number of imported certificates, number of redundant (already present) certificates, and number of rejected certificates (that were not signed by the requested CA). No summary will be displayed if abnormal errors are encountered (i.e. anything besides the already present certificate or mismatched CA), unless the -resumeonerror switch has been enabled.

If the -resumeonerror switch has been enabled, the import will continue until all of the entries from the directory are processed. Errors will still be printed-out, and the summary will contain the following additional information:

• Number of certificates that could not be read (because of malformed format or because they're directories).
• Number of certificates that have violated the end entity constraints (invalid number of subject/subject alternative name fields, wrong values for non-modifiable fields etc).
• Number of certificates that could not be read because of other errors.

CRL Update service worker

In the Admin GUI you can go to 'Edit Services' and add a new service. Edit the service and select the 'CRL Updater' worker and the interval you want to use. Don't forget to set the service to 'Active'.
This service will check, at the selected interval, if it is required to regenerate the current CRL (due to being expired or within the expiration threshold), and will generate a new one if needed.

Cron job

Yet another way to generate CRLs way is to have a cron job or equivalent call 'bin/ejbca.sh ca createcrl'. The 'createcrl' command will then check all active CAs if it is a need to update their CRLs, otherwise nothing is done.

If you want to force CRL generation for a CA, use 'bin/ejbca.sh ca createcrl caname'

Example crontab entry:

PATH=$PATH:/usr/java/jdk1.6.0_24/bin
@daily cd /home/ejbca;/home/ejbca/bin/ejbca.sh ca createcrl;

where '/usr/java/jdk1.6.0_24/bin' is the path to where 'java' can be found. '/home/ejbca' is where ejbca is installed.

Sample crontab to be installed with 'crontab -e':

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
CLASSPATH=$CLASSPATH:/root/ejbca
APPSRV_HOME=/usr/local/jboss
# m h dom mon dow command
00 0    * * *   cd /root/ejbca;./bin/ejbca.sh ca createcrl

Delta CRLs

EJBCA can issue delta CRLs. In the CA configuration, set 'Delta CRL Period' to the amount of time your delta CRLs will be valid if delta CRLs are issued. Command line interface and CRL Update service will generate delta CRLs if 'Delta CRL Period' is larger than 0.

Retrieving CRLs

EJBCA will store all generated CRLs unless you manually remove them from the database.

You can retrieve CRLs using the command line interface or Web UIs, either the latest CRL or a CRL with a specific CRL number.

• Command line interface: bin/ejbca.sh ca getcrl --help
• Public Web->Fetch CA CRLs, with additional 'crlnumber=<crl number>' parameter
• RA Web->CA Certificates and CRLs, with additional 'crlnumber=<crl number>' parameter

SCEP Configuration

The SCEP URL is:

http://HOST:PORT/ejbca/publicweb/apply/scep/ALIAS/pkiclient.exe

The URL contains a reference to a configuration alias 'ALIAS'. 'ALIAS' is an alphanumeric string that refers to the set of SCEP configurations that should be used when handling the SCEP reqest coming through this URL. It is possible to configure as many configuration aliases as desired through the command line or the AdminGUI. Documentation on how to create and configure the SCEP aliases in the command line are available when executing the following command from EJBCA home directory:

Creating a SCEP alias with the name 'scep' makes it available using the default URL (same URL as in previous versions), http://HOST:PORT/ejbca/publicweb/apply/scep/pkiclient.exe

./bin/ejbca.sh config scep

To manage SCEP aliases in the AdminGUI, go to System Functions -> SCEP Configuration

Level of SCEP support

EJBCA implements features from (at least) draft 11 of the SCEP specification. We implement the following SCEP messages:

• PKCSReq including Client Certificate Renewal
• GetCRL
• GetCACert
• GetCACertChain
• GetCACaps
• GetNextCACert

• GetCertInitial

• POSTPKIOperation
• SHA-1
• Client Certificate Renewal (Enterprise Edition Only)

EJBCA will not send back proper SCEP error messages in all cases of failure. The error messages are not completely implemented, although most of them are implemented.

Configuration

Configuring SCEP is done in the Admin GUI, under 'SCEP Configuration'. To be able to edit SCEP configuration, you have to have the '/edit_systemconfiguration' access.

./bin/ejbca.sh config scep updatealias --help

External RA SCEP Server (Enterprise Edition Only)

EJBCA supports the SCEP 'polling' RA model using the External RA API. Using this, a SCEP client can send a request to the External RA, and then wait, polling the RA for updates. When the request is processed by the CA, which fetches the pkcs10 request from the External RA, the certificate is sent back to the External RA. When the certificate is complete on the External RA, the RA sends back the SCEP certificate response the next time the SCEP client polls the RA. This feature is very useful to securely insulate the CA from the SCEP clients throughout the network.

Tested devices

./scep -k test.key -r test.pemreq -c ejbca-ca.pem -q foo123 -u http://localhost:8080/ejbca/publicweb/apply/scep/ALIAS/pkiclient.exe

openssl genrsa -out test.key

openssl req -key test.key -new -days 30 -out test.req -outform DER -config ../openssl/openscep.cnf

openssl req -key test.key -new -days 30 -out test.pemreq -outform PEM -config ../openssl/openscep.cnf

$ cd ejbca
$ cat > scepalias-camode.properties
scep.operationmode = ca
uploaded.includeca = true

$ bin/ejbca.sh config scep uploadfile --alias scep --file scepalias-camode.properties
$ bin/ejbca.sh ra addendentity --username=user --password=foo123 --dn="CN=User Usersson" --caname=ManagementCA --type=1 --token=USERGENERATED
$ cd ../jscep-cli-jdk6
$ openssl genrsa -out test.key
$ openssl req -key test.key -new -days 30 -out test.pemreq -outform PEM
$ java -jar target/jscepcli-1.0-SNAPSHOT-exe.jar --ca-identifier ManagementCA --challenge foo123 --csr-file test.pemreq --dn "CN=user" --key-file test.key --url http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe

Verbose = "yes"
Debug = "no"

CADir="/home/autosscep/"
CertDir="/home/autosscep/"
KeyDir="/home/autosscep/"

[CA]
DN="C=SE, O=EJBCA Sample, CN=ManagementCA"
URL="http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe"
CertFile="ManagementCA.cacert.pem"
EncCertFile="ManagementCA.cacert.pem"
[/CA]

[Certificate]
CertFile="mycert"
KeyFile="mykey"
CADN="C=SE, O=EJBCA Sample, CN=ManagementCA"

# Create a user with username "router4711" and password "foo123" in EJBCA
# to automatically enroll
# Note you need to add a user with exactly these fields in the DN in EJBCA
Email = "mymail@mydomain"
Country="SE"
State="BS"
Location="Stockholm"
Organization="PrimeKey"
CommonName="router4711"

ChallengePassword="foo123"
[/Certificate]

[CA]
DN="C=SE, O=EJBCA Sample, CN=ManagementCA"
URL="http://localhost:8080/scepraserver/scep/pkiclient.exe"
CertFile="scepra.pem"
EncCertFile="scepra.pem"
[/CA]

-- Connect with pix and enter admin mode
telnet 10.1.1.1 (default pwd cisco)
enable (default blank pwd)
configure terminal
-- Enable CA logging
debug crypto ca
-- Clear current PKI config
clear ca identity
-- Enter PKI config, i.e location of CA etc. Don't require CRLs, it's easier
ca identity pixca ca-ip:/ejbca/publicweb/apply/scep/pkiclient.exe
ca configure pixca ca 1 0 crloptional
ca authenticate pixca
-- wait --
-- Look at the fetched certificate
show ca certificate
ca save all
wr mem
-- Get a CRL if you really want to (if you did not configure CRL as optional you must)
ca crl request pixca
-- wait --
show ca crl
-- Generate keys and enroll for the certificate (user in ejbca has password foo123)
ca generate rsa key 1024
ca enroll pixca foo123
-- wait, wait, this will take a long time --
-- Look at the fetched certificate, this should now show both the pix cert and the ca cert
show ca certificate

pix(config)# show ca cert
Certificate
  Status: Available
  Certificate Serial Number: 594f643a6916d78d
  Key Usage: General Purpose
  Subject Name:
    C = SE
    O = PrimeKey
    CN = pix.primekey.com
    UNSTRUCTURED NAME = pix.primekey.com
    UNSTRUCTURED IP = 10.1.1.1
  Validity Date:
    start date: 14:42:29 GMT Sep 17 2005
    end   date: 14:52:29 GMT Sep 17 2007

CA Certificate
  Status: Available
  Certificate Serial Number: 7c7cf75236955a51
  Key Usage: General Purpose
    C = SE
    O = PrimeKey
    CN = pixca
  Validity Date:
    start date: 15:59:20 GMT Sep 16 2005
    end   date: 16:09:20 GMT Sep 14 2015

CMP and 3GPP/4G/LTE configuration guide

PrimeKey has created a detailed CMP configuration guide, with details how to configure EJBCA for 3GPP/4G/LTE networks using CMP. The guide is available together with a support subscription from PrimeKey.

An example cmpforopenssl command to test Vendor CA authentication with a three level Vendor CA PKI is:

./cmpclient --server 127.0.0.1 --port 8080 --path ejbca/publicweb/cmp/vendor --srvcert 3GPPCA.cacert.pem --ir --subject "C=SE,O=Test,CN=Network Element 32" --clcert nevcert.pem --newclcert nev-op-crt.der --newkey nev-op-key.pem --key nevkey.pem --extracert casubnevcert.pem

CMP Alias Configuration

• CMP Operational Mode: Client mode
• CMP Authentication Module: EndEntityCertificate
• Extract Username Component: CN
• Use Vendor Certificate Mode: Use and add CANevRoot as Vendor CA

Configuration

Configuring CMP is done in the Admin GUI, under 'CMP Configuration'. To be able to edit CMP configuration, you have to have the 'edit_systemconfiguration' access.

CMP over http

By default EJBCA support CMP over the http transport protocol. The URL for the CMP servlet is:
http://127.0.0.1:8080/ejbca/publicweb/cmp/ALIAS

ALIAS is a configuration alias specifying the set of CMP configurations to be used when handling a request sent through this specific URL. ALIAS can be any alphanumeric string. You can specify as many aliases as you need in the Admin GUI.

Example:
http://127.0.0.1:8080/ejbca/publicweb/cmp/cmpalias
Any CMP request sent through this URL will use the CMP configurations associated with the alias "cmpalias"

CMP over TCP

You can enable a CMP TCP service by changing the option "cmp.tcp.enabled" in conf/cmptcp.properties (copy conf/cmptcp.properties.sample to conf/cmptcp.properties first).
When re-deploying EJBCA this will start a TCP listener on the default port for CMP over TCP. You must run the application server as root to use the default port, since it is a low port (<1024). See the documentation in conf/cmp.properties for information about configuration options for TCP. We recommend using a non standard port > 1024.

CMP requests sent over TCP will be using CMP configurations associated with the configuration alias "tcp". Note that a CMP configuration alias with the name "tcp" does not exist per default. It has to be created (and/or altered) through the Admin GUI before any CMP request arrives through TCP.

Although EJBCA still supports CMP over TCP for now, it will not be supported for much longer. That is why we strongly recommend using CMP over HTTP instead.

CMP Message Authentication

EJBCA supports 4 modules for message authentication. Which modules to use, along with their parameters, can be set in the Admin GUI under 'CMP Configuration'.

The four supported modules are either password extractors or PKIMessage verifiers:

Password extractors (client mode only):

• RegTokenPwd: Extracts the password from the CMP request through the means of a regToken control (id-regCtrl-regToken) in the CRMF message. The regToken is a UTF8String containing the users password as registered in EJBCA. This module requires no parameters
• DnPartPwd: Extracts the password from the subjectDN of the user the request concerns. As a parameter, the DN part that contains the password should be specified. For example, if the subjectDN is "CN=name,C=se,UID=PASSWORD", the parameters should be set to "UID"

PKIMessage verifiers:

• HMAC: This module uses a shared secret to authenticate the CMP message:
  • In RA mode, the shared secret is set as a parameter to this module. If no parameter is specified, EJBCA will use the shared secret specified in the CA under "CMP RA Authentication Secret"
  • In client mode, the pre-registered end entity will be looked up in the database, and if there was a clear text password there, this password will be used to authenticate the message. If there is no clear text password associated with that end entity, the authentication will fail.
• EndEntityCertificate: When this module is used, the request sender should attach his certificate in the extraCert field in the PKIMessage and then sign the message with his private key.
  • In client mode, a user may only send a CMP request regarding his/her own certificate. Ejbca will then check if the certificate in extraCert does exist in its database and verifies that it belongs to the sender before verifying the signature. No parameters should be specified for this module in client mode.
  • In RA mode, as a parameter, this module expects the name of the CA that that has issued the certificate in the extraCert field. If a parameter is specified, EJBCA will then check if the certificate in extraCert does exist in the database, that it was issued by the right CA (the CA specified as a parameter) and that it belongs to a registered administrator in EJBCA with the right authorizations to perform the operations required in the request. If no parameter is specified, none of the mentioned checks will be performed, however, Ejbca will expect the CMP request to have been previously authenticated by other ways, for example, by sending the request inside a signed NestedMessageContent

More than one module can be specified by separating them with a ";". In case of more than one module specified, the first module will be used to for authentication testing. If the first module fails, the second module will be used for authentication testing, and so on until a successful authentication is done or all alternatives fail.

CMP Response Message

When a CMP request is successfull, EJBCA returns a protected CMP response message. The protection type of the response message can also be configered in the Admin GUI under "CMP Configuration". EJBCA supports two types of response message protection: 'pbe' and 'signature'.

If a CMP request fails, EJBCA returns an unprotected, unencrypted CMP error message.

Client mode for CMP

Client mode is used when the CMP client will act as an End Entity to EJBCA. This means that the End Entity must be pre-registered in EJBCA and that the client request is authenticated with this pre-registered end entity before a certificate is issued. This is the same authentication model as for regular enrollment, i.e. browser enrollment, using a username/password combination.

• The users DN is deducted from the request according to rules configured.
• The username in EJBCA must be pre-registered.
• The password for the user in EJBCA must be passed in the request (one-time password).
• If the Certificate Profile allows it, keyUsage, validity and extensions are also taken from the CertTemplate in the request message.
• Signature POPO is used.

To use client mode, no particular configuration is needed, since this is the default mode.

RA mode for CMP

RA mode is used when the CMP client will act as an RA to EJBCA. When the RA sends a certificate request to EJBCA, no user needs to be pre-registered in EJBCA. When EJBCA receives the request, the message will be authenticated. After it has been authenticated, a user is created and a certificate is issued.

• The users DN is taken from the CertTemplate in the request message send from the RA (i.e. the DN requested by the RA).
• The username in EJBCA is generated according to the options configured
• The password for the user in EJBCA is random.
• If the Certificate Profile allows it, keyUsage, validity and extensions are also taken from the CertTemplate in the request message.
• raVerify POPO is used.
• Messages are authenticated using one of the configured authentication modules.

If the same username is constructed (for example UID) as an already existing user, the existing user will be modified with new values for profile etc, and a new certificate will be issued for that user.

String subjectDN = "CN=bogusSubjectNested";
final byte[] nonce = "sendernonce".getBytes();
final byte[] transid = "trandis".getBytes();

PKIMessage crmfMsg = createCrmfReq();
//Signing crmfMsg
KeyPair eeKeys = getAdminKeys();
Certificate adminCert = getAdminCertificate();
ByteArrayInputStream    bIn = new ByteArrayInputStream(adminCert.getEncoded());
ASN1InputStream         dIn = new ASN1InputStream(bIn);
ASN1Sequence extraAdminCertSeq = (ASN1Sequence)dIn.readObject();
X509CertificateStructure extraCert = new X509CertificateStructure(ASN1Sequence.getInstance(extraAdminCertSeq));
crmfMsg.addExtraCert(extraCert);

final Signature sig = Signature.getInstance(PKCSObjectIdentifiers.sha256WithRSAEncryption.getId(), BouncyCastleProvider.PROVIDER_NAME);
sig.initSign(eekeys.getPrivate());
sig.update(crmfMsg.getProtectedBytes());
byte[] eeSignature = sig.sign();
crmfMsg.setProtection(new DERBitString(eeSignature));

PKIHeader myPKIHeader = new PKIHeader(new DERInteger(2), new GeneralName(new X509Name(subjectDN)), new GeneralName(new X509Name(((X509Certificate)cacert).getSubjectDN().getName())));
myPKIHeader.setMessageTime(new DERGeneralizedTime(new Date()));
// senderNonce
myPKIHeader.setSenderNonce(new DEROctetString(nonce));
// TransactionId
myPKIHeader.setTransactionID(new DEROctetString(transid));

PKIBody myPKIBody = new PKIBody(crmfMsg, 20); // NestedMessageContent
PKIMessage myPKIMessage = new PKIMessage(myPKIHeader, myPKIBody);
//Signing myPKIMessage
KeyPair raKeys = getRAKeys();
final Signature sig = Signature.getInstance(PKCSObjectIdentifiers.sha256WithRSAEncryption.getId(), BouncyCastleProvider.PROVIDER_NAME);
sig.initSign(rakeys.getPrivate());
sig.update(myPKIMessage.getProtectedBytes());
byte[] eeSignature = sig.sign();
myPKIMessage.setProtection(new DERBitString(eeSignature));

final ByteArrayOutputStream bao = new ByteArrayOutputStream();
final DEROutputStream out = new DEROutputStream(bao);
out.writeObject(myPKIMessage);
final byte[] ba = bao.toByteArray();
// Send request and receive response
final byte[] resp = sendCmpHttp(ba, 200);

CMP Operational Mode : RA Mode
Allow RA Verify Proof-of-Possession : check
CMP Response Protection : pbe
CMP Authentication Module : HMAC
CMP Authentication Parameters : password
RA Name Generation Scheme : DN
RA Name Generation Parameters : UID
RA Name Generation Prefix : cmp
RA End Entity Profile : CMP_ENTITY
RA Certificate Profile : CMP_CERT
RA CA Name : ManagementCA

Key Update Request (kur)

Also known as the Certificate Update request. When a key pair is due to expire, the relevant end entity may request a key update. The CMP request is signed and the sender attaches their certificate in the extraCert field in the CMP message.

Proof of possession

Proof of Possession (POP) is another part where CMP has gazillions of different options.
The following POPs in the CRMF are supported by EJBCA:

• raVerify - if "Allow RA Verify Proof-of-Possession" is checked, EJBCA will support the raVerify POP and in that case not do any verification of POP. By default this is false, because the standard does not recommend this option.
• signature - where the PublicKey is in the CertTemplate and the signature is calculated over the CertReqMsg.certReq (the standard procedure when the CertTemplate contains the subject and publicKey values).
• signature with POPOSigningKeyInput - where the PublicKey and subject DN is in POPOSigningKeyInput, possibly just copied from the CertTemplate. The signature is calculated over the POPOSigningKeyInput (if the values are also in the CertTemplate they must be identical).

Server Generated Keys

With CMP it is possible for clients to request server generated keys. The client requests this by one of the following in the CRMF certificate request:

• Leaving out the request public key in the CRMF request, as it is an optional field.
• Adding a subjectPublicKeyInfo containing an AlgorithmIdentifier followed by a zero-length BIT STRING for the subjectPublicKey (RFC4210 Appendix D.4).

These options of course open up a vast field of options. Adding in that the server want to restrict what type of keys the clients can request, and certify, there are a number of rather strict rules and business logic used by EJBCA. The below list highlights these choices, and apply only if server generated keys are allowed in the CMP alias configuration.

• If the request does not contain a request public key, key generation options are taken from the certificate profile that will be used to issue the certificate:
• The certificate profile must contain only one allowed key algorithm and one allowed key specification, for example 'RSA 1024' or 'ECDSA secp256r1'.
• If there is not a single distinct choice, the request will be denied and an error returned to the client.
• If the certificate profile contains a subjectPublicKeyInfo with the RSA algorithmId (rsaEncryption = 1.2.840.113549.1.1.1) the certificate profile must contain a single choice of key sizes allowed.
• If there is not a single distinct choice, the request will be denied
• If the certificate profile contains a subjectPublicKeyInfo with the ECDSA algorithmId (id_ecPublicKey = 1.2.840.10045.2.1) the subjectPublicKeyInfo must contain parameters where two choices are allowed:
• implicitlyCA - the certificate profile must contain a single choice of curves allowed, otherwise the request will be denied.
• namedCurve - with the OID of a supported named curve, which is among the allowed curves in the certificate profile.

These rules allow the CA administrator to control what server generated keys the CA will generate and return to the client, and can be sumarized as:

• A distinct choice of a single key algorithm and key size/curve, defined in the certificate profile.
• A choice of a single RSA key size and a set of EC curves, defined in the certificate profile and selected by the client in the request.

Only RSA and EC keys are supported at this moment.

Server generated keys are returned in the CertifiedKeyPair.privateKey field in the response, as defined in RFC4210 section 5.3.4 and section D.4. The EncryptedValue will contain the private key, encrypted using AES256 with a random symmetric key, in turn wrapped using the public key in id_regCtrl_protocolEncrKey (RFC4211 Appendix B have more details on the EncryptedValue).

Code example in Java for requesting server generated keys can be found in the test method CrmfRequestTest.test12ServerGeneratedKeys().

Certificate validity

Normally the validity period of issued certificates are controlled by the certificate profile. If you enable 'Allow validity override' in the certificate profile, and the CMP initialization- or certification request contains a validity time in the CRMF request template, this validity period will be used.

Certificate Key Usage

Normally the key usage extension of issued certificates are controlled by the certificate profile. If you enable 'Allow Key Usage Override' in the certificate profile, and the CMP initialization- or certification request contains a key usage in the CRMF request template, this key usage will be used.

Interoperability

ant cmpclient
cd dist/cmpclient
java -jar cmpclient.jar
java -jar cmpclient.jar crmf --help

java -jar cmpclient.jar crmf --dn "CN=tomas" --url http://192.168.122.230:8080/cmpProxy/raalias --authparam password --reqnewkeyspec RSA2048
openssl pkcs12 -export -inkey dest/tomas-key.pem -in /dest/tomas.pem -certfile ManagementCA.cacert.pem -name tomas -out dest/tomas.p12
java -jar cmpclient.jar update --dn "CN=tomas" --url http://192.168.122.230:8080/cmpProxy/clientupdate --keystore dest/tomas.p12 --keystorepwd foo123 --extraCertsFriendlyName tomas --includepopo --reqnewkeyspec RSA2048
openssl x509 -in dest/tomas.pem -text
java -jar cmpclient.jar revoke --issuer "CN=ManagementCA,O=EJBCA Sample,C=SE" --serno 17b9a7b8ce44b3fa --url http://192.168.122.230:8080/cmpProxy/raalias --authparam password

// Just preparations
final BigInteger certReqId = BigInteger.valueOf(1);
final byte[] senderNonce = "12345".getBytes();
final byte[] transactionId = "23456".getBytes();
KeyPairGenerator kpi = KeyPairGenerator.getInstance("RSA");
kpi.initialize(1024);
KeyPair keyPair = kpi.generateKeyPair();
// Now on to the CMP 
CertificateRequestMessageBuilder msgbuilder = new CertificateRequestMessageBuilder(certReqId);
X500Name issuerDN = new X500Name("CN=ManagementCA");
X500Name subjectDN = new X500Name("CN=user");
msgbuilder.setIssuer(issuerDN);
msgbuilder.setSubject(subjectDN);
final byte[]                  bytes = keyPair.getPublic().getEncoded();
final ByteArrayInputStream    bIn = new ByteArrayInputStream(bytes);
final ASN1InputStream         dIn = new ASN1InputStream(bIn);
final SubjectPublicKeyInfo keyInfo = new SubjectPublicKeyInfo((ASN1Sequence)dIn.readObject());
dIn.close();
msgbuilder.setPublicKey(keyInfo);
GeneralName sender = new GeneralName(subjectDN);
msgbuilder.setAuthInfoSender(sender);
// RAVerified POP
msgbuilder.setProofOfPossessionRaVerified();
CertificateRequestMessage msg = msgbuilder.build();
org.bouncycastle.asn1.crmf.CertReqMessages msgs = new org.bouncycastle.asn1.crmf.CertReqMessages(msg.toASN1Structure());
org.bouncycastle.asn1.cmp.PKIBody pkibody = new org.bouncycastle.asn1.cmp.PKIBody(org.bouncycastle.asn1.cmp.PKIBody.TYPE_INIT_REQ, msgs);
// Message protection and final message
GeneralName recipient = new GeneralName(issuerDN);
ProtectedPKIMessageBuilder pbuilder = new ProtectedPKIMessageBuilder(sender, recipient);
pbuilder.setMessageTime(new Date());
// senderNonce
pbuilder.setSenderNonce(senderNonce);
// TransactionId
pbuilder.setTransactionID(transactionId);
// Key Id used (required) by the recipient to do a lot of stuff
pbuilder.setSenderKID("KeyID".getBytes());
pbuilder.setBody(pkibody);
JcePKMACValuesCalculator jcePkmacCalc = new JcePKMACValuesCalculator();
final AlgorithmIdentifier digAlg = new AlgorithmIdentifier(new ASN1ObjectIdentifier("1.3.14.3.2.26")); // SHA1
final AlgorithmIdentifier macAlg = new AlgorithmIdentifier(new ASN1ObjectIdentifier("1.2.840.113549.2.7")); // HMAC/SHA1
jcePkmacCalc.setup(digAlg, macAlg);
PKMACBuilder macbuilder = new PKMACBuilder(jcePkmacCalc);
MacCalculator macCalculator = macbuilder.build("password".toCharArray());
ProtectedPKIMessage message = pbuilder.build(macCalculator);

// Just preparations
final byte[] senderNonce = "12345".getBytes();
final byte[] transactionId = "23456".getBytes();
BigInteger serNo = new BigInteger("aabbccdd");
X500Name issuerDN = new X500Name("CN=ManagementCA");
X500Name userDN = new X500Name("CN=user");
// Cert template too tell which cert we want to revoke
CertTemplateBuilder myCertTemplate = new CertTemplateBuilder();
myCertTemplate.setIssuer(issuerDN);
myCertTemplate.setSubject(userDN);
myCertTemplate.setSerialNumber(new ASN1Integer(serNo));
// Extension telling revocation reason
ExtensionsGenerator extgen = new ExtensionsGenerator();
CRLReason crlReason = CRLReason.lookup(CRLReason.cessationOfOperation);
extgen.addExtension(Extension.reasonCode, false, crlReason);        
Extensions exts = extgen.generate();
ASN1EncodableVector v = new ASN1EncodableVector();
v.add(myCertTemplate.build());
v.add(exts);
ASN1Sequence seq = new DERSequence(v);
RevDetails myRevDetails = RevDetails.getInstance(seq);
RevReqContent myRevReqContent = new RevReqContent(myRevDetails);
PKIBody myPKIBody = new PKIBody(PKIBody.TYPE_REVOCATION_REQ, myRevReqContent); // revocation request
// Message protection and final message
GeneralName sender = new GeneralName(userDN);
GeneralName recipient = new GeneralName(issuerDN);
ProtectedPKIMessageBuilder pbuilder = new ProtectedPKIMessageBuilder(sender, recipient);
pbuilder.setMessageTime(new Date());
// senderNonce
pbuilder.setSenderNonce(senderNonce);
// TransactionId
pbuilder.setTransactionID(transactionId);
// Key Id used (required) by the recipient to do a lot of stuff
pbuilder.setSenderKID("KeyId".getBytes());
pbuilder.setBody(myPKIBody);
JcePKMACValuesCalculator jcePkmacCalc = new JcePKMACValuesCalculator();
final AlgorithmIdentifier digAlg = new AlgorithmIdentifier(new ASN1ObjectIdentifier("1.3.14.3.2.26")); // SHA1
final AlgorithmIdentifier macAlg = new AlgorithmIdentifier(new ASN1ObjectIdentifier("1.2.840.113549.2.7")); // HMAC/SHA1
jcePkmacCalc.setup(digAlg, macAlg);
PKMACBuilder macbuilder = new PKMACBuilder(jcePkmacCalc);
MacCalculator macCalculator = macbuilder.build("password".toCharArray());
ProtectedPKIMessage message = pbuilder.build(macCalculator);

CertificateRequestMessageBuilder msgbuilder = new CertificateRequestMessageBuilder(BigInteger.valueOf(certReqId));
X509NameEntryConverter dnconverter = new X509DefaultEntryConverter();
X500Name issuerDN = X500Name.getInstance(new X509Name("CN=ManagementCA").toASN1Object());
X500Name subjectDN = X500Name.getInstance(new X509Name("CN=user", dnconverter).toASN1Object());
msgbuilder.setIssuer(issuerDN);
msgbuilder.setSubject(subjectDN);
final byte[]                  bytes = keyPair.getPublic().getEncoded();
final ByteArrayInputStream    bIn = new ByteArrayInputStream(bytes);
final ASN1InputStream         dIn = new ASN1InputStream(bIn);
final SubjectPublicKeyInfo keyInfo = new SubjectPublicKeyInfo((ASN1Sequence)dIn.readObject());
msgbuilder.setPublicKey(keyInfo);
GeneralName sender = new GeneralName(subjectDN);
msgbuilder.setAuthInfoSender(sender);
Control control = new RegTokenControl("foo123");
msgbuilder.addControl(control);
Provider prov = Security.getProvider(BouncyCastleProvider.PROVIDER_NAME);
ContentSigner popsigner = new JcaContentSignerBuilder("SHA1withRSA").setProvider(prov).build(keyPair.getPrivate());
msgbuilder.setProofOfPossessionSigningKeySigner(popsigner);
CertificateRequestMessage msg = msgbuilder.build();
GeneralName recipient = new GeneralName(issuerDN);
ProtectedPKIMessageBuilder pbuilder = new ProtectedPKIMessageBuilder(sender, recipient);
pbuilder.setMessageTime(new Date());
// senderNonce
pbuilder.setSenderNonce(senderNonce);
// TransactionId
pbuilder.setTransactionID(transactionId);
org.bouncycastle.asn1.crmf.CertReqMessages msgs = new org.bouncycastle.asn1.crmf.CertReqMessages(msg.toASN1Structure());
org.bouncycastle.asn1.cmp.PKIBody pkibody = new org.bouncycastle.asn1.cmp.PKIBody(org.bouncycastle.asn1.cmp.PKIBody.TYPE_INIT_REQ, msgs);
pbuilder.setBody(pkibody);
ContentSigner msgsigner = new JcaContentSignerBuilder("SHA1withRSA").setProvider(prov).build(keyPair.getPrivate());
ProtectedPKIMessage message = pbuilder.build(msgsigner);

CMP Operational Mode : RA Mode
CMP Response Protection : pbe
CMP Authentication Module : HMAC
CMP Authentication Parameters : password

./openssl cmp -cmd ir -server localhost:8080 -path ejbca/publicweb/cmp/opensslra -srvcert ManagementCA.cacert.pem -user NewUser -pass password -certout clcert1.pem -newkey key1.pem -keyfmt PEM -certfmt PEM -subject "/CN=NewUser/O=My Organization/C=SE"

./cmpclient --server localhost --port 8080 --path ejbca/publicweb/cmp --srvcert ManagementCA.cacert.crt --ir --user mykeyid --password password --newclcert clcert.der --newkey key.pem --subject "CN=User Name;O=My Organization;C=SE"

CMP Authentication Module : HMAC
CMP Authentication Parameters : password
Extract Username Component : CN

bin/ejbca.sh ra addendentity user1 --password password "CN=user1,O=My Organization,C=SE" ManagementCA 1 USERGENERATED
bin/ejbca.sh ra setclearpwd user1 password
bin/ejbca.sh ra setendentitystatus user1 10

./openssl cmp -cmd ir -server localhost:8080 -path ejbca/publicweb/cmp/opensslclient -srvcert ManagementCA.cacert.pem -user user1 -pass password -certout clcert1.pem -newkey key1.pem -keyfmt PEM -certfmt PEM -subject "/CN=user1/O=My Organization/C=SE"

./cmpclient --server localhost --port 8080 --path ejbca/publicweb/cmp --srvcert ManagementCA.der --ir --user mykeyid --password password --newclcert clcert.der --newkey key.pem --subject "CN=user1;O=My Organization;C=SE"

CMP Authentication Module : EndEntityCertificate
CMP Authentication Parameters : ManagementCA (use the CA that issues your client authentication certificate)
Extract Username Component : CN

bin/ejbca.sh ra setclearpwd user1 password
bin/ejbca.sh ra setendentitystatus user1 10

./openssl cmp -cmd ir -server localhost:8080 -path ejbca/publicweb/cmp/openssleec -srvcert ManagementCA.cacert.pem -cert clcert.pem -key key.pem -certout clcert1.pem -newkey key1.pem -keyfmt PEM -certfmt PEM -subject "/CN=user1/O=My Organization/C=SE"

bin/ejbca.sh ra setendentitystatus user1 10
./openssl cmp -cmd cr -server localhost:8080 -path ejbca/publicweb/cmp/openssleec -srvcert ManagementCA.cacert.pem -cert clcert.pem -key key.pem -certout clcert1.pem -newkey key1.pem -keyfmt PEM -certfmt PEM -subject "/CN=user1/O=My Organization/C=SE"

Use Vendor Certificate Mode : checked
Vendor CA : 3GPP-CA

./openssl cmp -cmd ir -server localhost:8080 -path ejbca/publicweb/cmp/3gpp -srvcert ManagementCA.cacert.pem -cert devicecert.pem -key devicekey.pem -certout clcert1.pem -newkey key1.pem -keyfmt PEM -certfmt PEM -subject "/CN=device/O=My Organization/C=SE"

Sample CMP workflow

A typical PKI work-flow using CMP involves enroling a device with a certificate and then having the device automatically renew the certificate when it is about to expire.

1. Generate a key pair
2. Initial enrollment of client certificate using a one-time enrollment code
3. Generate a new key pair
4. Renew with a new certificate for the new key pair, authenticated using the old key pair and certificate

The above steps can be simulated in reality using the openssl and cmpforopenssl client, but also using the EJBCA cmpclient.
This works with a default cmpalias (named cmp) configured with parameters:

CMP Authentication Module : HMAC
CMP Authentication Parameters : password
Extract Username Component : CN

1. Generate a key pair:

$ ./openssl genrsa -out certs/cl_key.pem 2048 

2. Initial enrollment:
Before initial enrollment you add a new End Entity in EJBCA, in this example with user name cmptest and subject DN 'CN=cmptest', and enrollment code 'CMP-pwd'.

$ ./openssl cmp -cmd ir \
           -server ejbca-server:8080 \
           -path ejbca/publicweb/cmp \
           -srvcert certs/3GPPCA.pem \
           -user cmptest \
           -pass CMP-pwd \
           -newkey certs/cl_key.pem \
           -certout certs/cl_cert.pem \
           -subject "/CN=cmptest" 

3. Generate a new key pair:

$ ./openssl genrsa -out certs/cl_new_key.pem 2048

4. Renew with a new certificate:

$ ./openssl cmp -cmd kur \
           -server ejbca-server:8080 \
           -path ejbca/publicweb/cmp \
           -srvcert certs/3GPPCA.pem \
           -key certs/cl_key.pem \
           -cert certs/cl_cert.pem \
           -newkey certs/cl_new_key.pem \
           -certout certs/cl_new_cert.pem 

Custom handling of certificate request

It is possible to add a custom plug-in class to handle a certificate request. The class implementing this plug-in must implement the org.ejbca.core.protocol.ExtendedUserDataHandler interface.

The idea is that the implementation uses information from the certificate profile or name and the request itself to manipulate the request before it is processed the normal way. This is done when 'processRequestMessage' (see source code of the interface) is called. The used certificate profile name is passed as 'otherData'.

In the Admin GUI under "CMP Configuration", set "Certificate Request Handler Class" to the name of the plug-in class to enable it. You may then add additional properties that you can use in your implementation.

In EJBCA there is already an implementation included. This implementation writes to the unid-fnr DB (see separate unid document). To activate this plug-in just set the following configurations:

Certificate Request Handler Class : org.ejbca.core.protocol.unid.UnidFnrHandler
Unid Data Source : java:/UnidDS

Note that you have to set this using the CLI as it is not possible in the Admin GUI:

bin/ejbca.sh config cmp updatealias --alias cmpalias --key certreqhandler.class --value org.ejbca.core.protocol.unid.UnidFnrHandler
bin/ejbca.sh config cmp updatealias --alias cmpalias --key uniddatasource --value java:/UnidDS

You also have to create the Unid mapping database, see the separate unid document referenced above.

CMP Error Messages

When an error occurs during CMP processing some different CMP error messages, or HTTP error codes can occur. Depending on at which stage the error is encountered and its type, different error messages are returned. Below is a exhaustive list of CMP error codes (don't use as definite guide, do you own testing).

CMP Proxy (EJBCA Enterprise only)

In some installations it may be desirable to terminate the client connection in a DMZ before connecting further to the CA. In this case the client never has a direct network connection to the CA machine. In such a scenario you can use the CMP proxy module. Clients use the CMP proxy, as it would otherwise use EJBCA. The proxy in turn connects to EJBCA gets the answer and forwards it back to the client.

The proxy is a stand alone module that runs on another machine than the CA itself.

See EJBCA_HOME/modules/cmpProxy/resources/README for information how to build and use the proxy.

cmp.backend.hmacPasswordValidationRequired=true

cmp.backend.hmacPassword.keylist=[ca1:foo][ca2:bar]

cmp.backend.signatureRequired=true

cmp.backend.issuerchainpath

Stand-alone OCSP responder

You can set up separated OCSP responders in EJBCA. Using this you can isolate the CA from the Internet and still be able to answer OCSP request. You can set up firewalls so that only outgoing traffic is allowed from the CA, and nothing to the CA.

Separated OCSP responders is also good when you don't require high-performance clustering for the CA, but you do need high-performance for the OCSP responders. This is a common setup, if the CA only issues certificates once every year for one million users, this does not put much pressure on the CA, but the OCSP responders can be put under high load continuously.

See the OCSP Installation document for information how to set up stand-alone, separated OCSP responders.

OCSP User Guide

More information about certain features, such as OCSP extensions, can be found in the OCSP User Guide.

Simple OCSP client

To try out and test your OCSP installation you can use the EJBCA client toolbox, (see below). You can also use the API directly from your java program.

Adobe Reader

A good example of using OCSP is to check digitally signed PDF documents using Adobe Reader.

To be able to verify certificates in Adobe Reader, you must first add the CA certificate as trusted in Adobe Reader. You can do that in the menu Document->Trusted Identities. Choose Certificates in the drop-down list and click 'Add contacts', now you can browse to the CA-certificate that you have downloaded in DER format (for example by choosing download to IE on the public EJBCA pages). The CA certificate must have been saved with a name ending with '.cer'. After adding the new contact, you have to click 'Edit trust' and check at least 'Signatures and as trusted root' and 'Certified documents'. This works the same using both internal and external OCSP responders.

Certificates that have an 'OCSP service locator' will be verified against the OCSP responder. You can configure this in the certificate profile used to issue certificates.

If you sign PDF documents with embedded OCSP responses those responses must include a nextUpdate field, and the timestamp must be within the thisUpdate and nextUpdate period of the OCSP response.

Web Services authentication

The Web Services interface requires client certificate authentication from administrators, in the same way as the admin GUI does. If you have a client certificate that works on the admin GUI you should also be able to use it for the web service interface.

Configuring Web Services behavior

The sample property file conf/jaxws.properties.sample contains more information on how to configure the behavior of the EJBCA WS. Copy this to conf/jaxws.properties, edit and redeploy.

If the end entity profile informations must be used to define default values when you create a user, the flag "Allow merge DN Webservices" must be checked in the end entity profile.

If multiple instances of a component exist, the merge is done from end to beginning, and the remaining values of this component type will be placed at the end. For example, if you want to merge:

dn=cn=foo,..., dc=dc1, ..., dc=dc2, ...

with

dn=..., dc=mdc1, ..., dc=mdc2, ..., dc=mdc3, ...

the result will be:

dn=cn=foo, ..., dc=mdc1, ..., dc=mdc2, ..., dc=mdc3, ...

Configuring Web Services CLI

Edit dist/ejbca-ws-cli/ejbcawsracli.properties before running the EJBCA WS CLI. This files contains descriptions of what can be configured. Please note that this directory is recreated each time you build EJBCA, so copy it to a separate location if you intend to rebuild or redeploy EJBCA and keep the configuration.

Configuration for the Web Services CLI requires a P12 or JKS keystore. You can easily try the WS CLI using the superadmin.p12 keystore generated during the installation or generate a new JKS using the Admin GUI. Below is a short description how to create a JKS for a user on the command line, and adding the new user to the superadministrator role.

bin/ejbca.sh ra addendentity <1> <2> "C=..,O=..,CN=<1>" ManagementCA 1 JKS
bin/ejbca.sh ra setclearpwd <1> <2>
bin/ejbca.sh batch <1>
bin/ejbca.sh roles addmember "Temporary Super Administrator Group" ManagementCA WITHCOMMONNAME EQUALCASEINS <1>

Using the Web Services CLI

Included in the EJBCA Client Tool Box is a Web Service CLI tool.

To use the client do the following, copy the directory with all included files to the computer you want to remotely administer from. Then create a JKS or P12 file with the appropriate access rights (See the Using API section for details) and finally configure the file ejbcawsracli.properties. In this file you should specify the hostname of the CA server, the name of the keystore and the password to unlock it. Documentation for each setting is in the file ejbcacsracli.properties.

Use 'ejbcaClientToolBox.sh EjbcaWsRaCli' for a list of each subcommand and 'ejbcaClientToolBox.sh EjbcaWsRaCli "subcommand"' for detailed help how to use the cli.

Example usage: ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req testuser2 foo123 2048 NONE tmp

ejbcaClientToolBox.sh EjbcaWsRaCli revokeendentity testuser2 SUPERSEDED false

Using the Web Service API for Integration

You can use the Web Service interface to integrate EJBCA from other applications.

If you are using another language than Java you should start by downloading the WSDL file at http://hostname:8080/ejbca/ejbcaws/ejbcaws?wsdl. With this you can use your programming language tools to generate client stubs.

When using java you can find the required libs in 'dist/ejbcawscli' and it's 'lib' subdirectory.

Some programming examples:

To initialize the web service:

  CryptoProviderTools.installBCProvider();	
  String urlstr = "https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl";
	
  System.setProperty("javax.net.ssl.trustStore","p12/wstest.jks");
  System.setProperty("javax.net.ssl.trustStorePassword","foo123");  
	
  System.setProperty("javax.net.ssl.keyStore","p12/wstest.jks");
  System.setProperty("javax.net.ssl.keyStorePassword","foo123");      
                             
  QName qname = new QName("http://ws.protocol.core.ejbca.org/", "EjbcaWSService");
  EjbcaWSService service = new EjbcaWSService(new URL(urlstr),qname);
  ejbcaraws = service.getEjbcaWSPort();  

Example call to find all users having 'Smith' in their subject dn:

  UserMatch usermatch = new UserMatch();
  usermatch.setMatchwith(UserMatch.MATCH_WITH_DN);
  usermatch.setMatchtype(UserMatch.MATCH_TYPE_CONTAINS);
  usermatch.setMatchvalue("Smith");
  List<UserDataVOWS> result = ejbcaraws.findUser(usermatch);

Example generating a certificate from a PKCS10 request:

  UserDataVOWS user1 = new UserDataVOWS();
  user1.setUsername("WSTESTUSER1");
  user1.setSubjectDN("CN=WSTESTUSER1");
  user1.setCaName("ManagementCA");
  user1.setEmail(null);
  user1.setSubjectAltName(null);
  user1.setEndEntityProfileName("EMPTY");
  user1.setCertificateProfileName("ENDUSER");
			
  KeyPair keys = KeyTools.genKeys("2048", AlgorithmConstants.KEYALGORITHM_RSA);
  PKCS10CertificationRequest  pkcs10 = new PKCS10CertificationRequest("SHA256WithRSA",
  CertTools.stringToBcX500Name("CN=NOUSED"), keys.getPublic(), null, keys.getPrivate());

  CertificateResponse certenv =  ejbcaraws.certificateRequest(user1,
                                                              CertificateHelper.CERT_REQ_TYPE_PKCS10,
                                                              new String(Base64.encode(pkcs10.getEncoded())),
                                                              null,
                                                              CertificateHelper.RESPONSETYPE_CERTIFICATE);
		
  X509Certificate cert = certenv.getCertificate(); 		

Example checking the revocation status of a certificate:

  RevokeStatus revokestatus = ejbcaraws.checkRevokationStatus(cert.getIssuerDN.toString,cert.getSerialNumber().toString(16));
  if(revokestatus != null){
    if(revokestatus.getReason() != RevokeStatus.NOT_REVOKED)){
      // Certificate is revoked
    }else{
	  // Certificate isn't revoked
    }
  }else{
	// Certificate doesn't exist
  }	  

Developing against the web service SOAP API

The SOAP API is compatible with all development languages that can handle SOAP messages. This includes programming languages such as Java, C# and PHP. The normal approach is to use your programming languages tools to generate client stubs, which are classes to be used in your client program. For Java, such stub classes are already included as part of the clientToolBox WS client we provide.

Client stubs are generated from the WSDL file, which includes all information to use the WS API. The WSDL can be accessed from your installed EJBCA at https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl. In the WSDL all methods and parameters are described, but without detailed documentation. For a simple example lets take the getProfile method. This is described in the WSDL as:

<xs:complexType name="getProfile">
  <xs:sequence>
    <xs:element name="arg0" type="xs:int"/>
    <xs:element minOccurs="0" name="arg1" type="xs:string"/>    
  </xs:sequence>
</xs:complexType>

You can see that there are two parameters to the method arg0 that is an integer and arg1 that is a string. From the Javadoc API documentation we provide for the WS API you can find detailed description of the arguments. The WS API documentation contains detailed descriptions and in particular the EjbcaWS class is most interesting.
Here you can see for the methods the parameters, return value, privileges needed to use the method (based on the TLS client certificate) and errors that can occur, returned as SOAP error classes.
For the getProfile method there is documented:

Parameters:
    profileId - ID of the profile we want to retrieve.
    profileType - The type of the profile we want to retrieve. 'eep' for End Entity Profiles and 'cp' for Certificate Profiles
Returns:
    a byte array containing the specified profile in XML format

Now you can use your client stubs, in any programming language you want to call the WS SOAP getProfile method with an integer and a string parameter, getting back a profile in XML format.

Sample code

See the file modules/ejbca-ws/src/org/ejbca/core/protocol/ws/common/IEjbcaWS for more detailed instructions of the API. Sample code can be taken from:

• The JUnit tests for the WS-API: modules/systemtests/src/org/ejbca/core/protocol/ws/EjbcaWSTest.java
• The WS-API CLI: modules/ejbca-ws-cli/src/org/ejbca/core/protocol/ws/client/*.java
• An example RA Admin sample program written in Java (for an older version of EJBCA though) and using the web services API may be downloaded from the WebServiceRA project on SourceForge. For more information, see the Web Services custom RA section of the Guides.
  A short movie demonstrating the program may be viewed on YouTube, or downloaded from SourceForge.

Accessrules required when using the Web Service API

All the calls requires HTTPS client authentication. The keystore used must be set up as a regular administrator and access rules according to the following:

Common for all calls (except isAuthorized, existsHardToken, isApproved that only needs a valid trusted certificate):

• /administrator
• /ca/'related CA'

editUser:

• /ra_functionality/create_end_entity and/or edit_end_entity
• /ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity

findUser, findCert:

• /ra_functionality/view_end_entity
• /ra_functionality/'end entity profile of the user'/view_end_entity

pkcs10Request, pkcs12req:

• /ra_functionality/view_end_entity
• /ra_functionality/edit_end_entity (only required for non key recovery)
• /ra_functionality/keyrecovery (only required for key recovery)
• /ra_functionality/'end entity profile of the user'/view_end_entity
• /ra_functionality/'end entity profile of the user'/keyrecovery (only required for key recovery)
• /ra_functionality/'end entity profile of the user'/keyrecovery (only required for non key recovery)
• /ca_functionality/create_certificate

certificateRequest, softTokenRequest:

• /ra_functionality/create_end_entity and/or edit_end_entity
• /ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity
• /ca_functionality/create_certificate

revokeCert, revokeToken: These calls support approvals.

• /ra_functionality/revoke_end_entity
• /ra_functionality/'end entity profile of the user owning the cert'/revoke_end_entity

revokeUser: This call support approvals.

• /ra_functionality/revoke_end_entity
• /ra_functionality/'end entity profile of the user'/revoke_end_entity
• /ra_functionality/delete_end_entity (only if users should be deleted)
• /ra_functionality/'end entity profile of the user'/delete_end_entity (only if users should be deleted)

fetchUserData: It is possible to turn of authorization of this call in the jaxws.properties

• /userdatasourcesrules/'user data source'/fetch_userdata

genTokenCertificate: Important this call also supports approvals, and the default behaviour is when someone without the '/administrator' access is creating a call then will a GenerateTokenApprovalRequest be created. This behaviour can be turned off in the jaxws.properties file.

• /ra_functionality/create_end_entity and/or edit_end_entity
• /endentityprofilesrules/'end entity profile of user'/create_end_entity and/or edit_end_entity
• /ra_functionality/revoke_end_entity (if overwrite flag is set)
• /endentityprofilesrules/'end entity profile of user'/revoke_end_entity (if overwrite flag is set)
• /ca_functionality/create_certificate
• /ca/'ca of all requested certificates'
• hardtoken_functionality/issue_hardtokens

getHardTokenData: Important this call also supports approvals, and the default behaviour is when someone without the '/administrator' access is creating a call then will a ViewHardTokenApprovalRequest be created. This behaviour can be turned off in the jaxws.properties file.

• /ra_functionality/view_hardtoken
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

getHardTokenDatas:

• /ra_functionality/view_hardtoken
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

republishCertificate:

• /ra_functionality/view_end_entity
• /endentityprofilesrules/'end entity profile of the user'/view_end_entity
• /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

customLog: No CA access rule is required.

• /secureaudit/log_custom_events (must be configured in advanced mode when editing access rules)

deleteUserDataFromSource:

• /userdatasourcesrules/'user data source'/remove_userdata (for all the given user data sources)

getCertificate: no requirement of the '/administrator' flag

• /ca_functionality/view_certificate

caCertResponse, caRenewCertRequest:

• /ca_functionality/renew_ca

createCryptoToken (Available in Enterprise Edition only):

• /cryptotoken/modify

generateCryptoTokenKeys (Available in Enterprise Edition only):

• /cryptotoken/keys/generate/'related CryptoToken'

createCA (Available in Enterprise Edition only):

• /

addSubjectToRole, removeSubjectFromRole (Available with Enterprise Edition only):

• /ca/'related CAs (All the CAs that issued the certificates of every member in the the related role)'
• /system_functionality/edit_administrator_privileges

getCertificatesByExpirationTime, getCertificatesByExpirationTimeAndIssuer, getCertificatesByExpirationTimeAndType:

• No other access rules are required

Error codes on web services

Business error code have been added in order to discriminate exception of type EjbcaException.

The following code sample shows how to use error codes :

try {
    ejbcaraws.editUser(user1);
} catch(EjbcaException_Exception e) {
    if(org.cesecore.ErrorCode.CERT_PROFILE_NOT_EXISTS.getInternalErrorCode().equals(e.getFaultInfo().getErrorCode().getInternalErrorCode())) {
        log.error("No such certifcate profile.");
    }
}
    

All error codes are described in org.cesecore.ErrorCode.

You can also take a look at src/test/org/ejbca/core/protocol/ws/CommonEjbcaWSTest.java to see how the error code can be used.

WS transaction logging

The logging is done the same way as the logging for the OCSP responder is done. See OCSP Audit and Account Logging. But different tags are used:

• LOG_TIME : The time the call took place
• SESSION_ID : A random 32 Byte long String generated when the OCSP-responder is started.
• LOG_ID : An integer identifying that starts from 1 and is increased for every received request.
• REPLY_TIME : The time it took to return from the WS method.
• METHOD : Name of the called WS method.
• ERROR_MESSAGE : An error message with information of the error. If the call returned successfully then 'NO_ERROR'.
• ADMIN_DN : Subject DN for the client certificate in the call.
• ADMIN_ISSUER_DN : Issuer DN of the client certificate in the call

The configuration is done in conf/jaxws.properties.

In jboss-log4j.xml 'org.ejbca.core.protocol.ws.logger.TransactionLogger' should be used as category name for the appender.

WS message debugging

When integrating it can be good to log the SOAP messages in order to debug and see what is going on behind the scenes. You can accomplish this by adding the following to JAVA_OPTS:

-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true 

In JBoss 7/EAP6/WildFly 9 and 10 this can be done by adding the above line to JAVA_OPTS in JBOSS_HOME/bin/standalone.conf.

Introduction

EJBCA Enterprise Edition implements Certificate Transparency (CT) as specified in RFC 6962. The purpose of CT is to create public audit logs of all certificates issued by the public SSL/TLS CAs. The presence of audit records is planned to be required for EV certificates in Google Chrome from February 2015 (and other web browsers and non-EV certificates later on as well). Note that CT is only relevant for CAs issuing public SSL/TLS certificates; other types of CAs should not use CT. More information can be found on the CT website.

From a CA's point of view, CT works by publishing certificates from the CA to the log servers and retrieving Signed Certificate Timestamps (SCTs) in response (this is a single operation, so requesting an SCT for a certificate publishes it also). The resulting SCTs can then be sent to end-users in a TLS handshake in three different ways: in a certificate extension, in a stapled OCSP response and/or in a TLS extension. EJBCA supports all of these, including combinations. The following sections describe how to configure EJBCA in one or more of these modes.

Prerequisites

Your EJBCA installation needs the ct module, which is only present in the enterprise edition (contact PrimeKey for details). Depending on the CT modes you need, there are some extra preparations.

ocsp.extensionoid=*1.3.6.1.4.1.11129.2.4.5
ocsp.extensionclass=org.ejbca.core.protocol.ocsp.extension.certificatetransparency.OcspCtSctListExtension

Adding CT logs

CT log servers are configured under System Configuration. They do not become active until they are enabled per certificate profile. The following parameters have to be configured in a log:

• Log URL : The log URL, e.g. http://something/, for example https://ct.googleapis.com/testtube/.
• Public Key : The log's public key, in PEM or DER format. Usually this is an Elliptic Curve key.
• Timeout : Connection timeout in milliseconds. Five seconds is the default. Note that certificate issuance and/or OCSP response generation must wait for the log server to respond, so do not set it too high. Note that zero is not a valid value for the timeout.
• Label: Specify which label to place the log under. See "CT log labels" below.

The log server needs to accept certificates issued by your CAs. For local testing you can install your own instance of the sample log server from the CT open source project, and add your root CA to the list of trusted CAs. For a production system (or testing of one) you must contact the log operator to have your root CA added.

For redundancy, it's recommended to add more logs to each label than the minimum required. That way certificate issuance will not fail if a single log is down. It is also a good idea to specify a short timeout value and/or enable the "ct.fastfail.enabled" option in conf/cesecore.properties, so a failing log does not slow down all requests.

Regarding performance: EJBCA will connect to every log having one of the labels selected in the certificate profile, in the order they have been added and in parallel. It will keep fetching SCTs until 'Maximum number of SCTs' is reached. EJBCA will fail issuance if it is unable to fetch at least the number of SCTs given by the parameter 'Minimum number of SCTs' specified in the certificate profile. If the number of retrieved SCTs exceeds the max value, the log(s) last in order will be excluded.

You may change the order in which the logs are contacted by moving them up or down in the 'System Configuration' page.

EJBCA audit logging

The submission of pre-certificates is logged to the EJBCA audit log. When a pre-certificate has been submitted to the required number of CT log servers, then a SUCCESS is audit logged. Otherwise a FAILURE is logged. If the generation of the pre-certificate fails, then no CT log submission is performed and nothing is logged.

Activating CT

CT logs must be activated in your certificate profiles. See the user guide.

Redacting DNS labels in SubjectAlternativeName

In the SubjectAlternativeName extension, if part of the DNS should be a secret, that part can be redacted and replaced by the String "(PRIVATE)" in the precertificate that will be published to the Certificate Transparency Log. See the user guide.

Using an outgoing proxy server to send to CT logs

For security reasons using an outgoing proxy server from the CA to the CT logs is a common request. The CT log function will make use of Java/JBoss proxy configurations. There are two ways to configure the proxy properties in JBoss:

• In standalone.sh append to JAVA_OPTS:

-Dhttp.proxyHost=HostName/IPaddress
-Dhttp.proxyPort=PortNumber
-Dhttps.proxyHost=HostName/IPaddress
-Dhttps.proxyPort=PortNumber

• In standalone.xml append to system-properties:

<property name="http.proxyHost" value="HostName/IPaddress"/>
<property name="http.proxyPort" value="PortNumber"/>
<property name="https.proxyHost" value="HostName/IPaddress"/>
<property name="https.proxyPort" value="PortNumber"/>

Both ways works, but don't forget to reconfigure the proxy settings if you upgrade/change the JBoss instance.

Legacy Script based Autoenrollment

Script based Autoenrollment is a legacy way of doing autoenrollment and uses login scripts and VB scripts to automatically enroll clients. It is kept for legacy reasons. More information can be found in the Guides.
The Native autoenrollment (above) provides a more seamless experience.

Local Key Generation

In systems with distributed RA's, using key recovery, it might be desired to store the key pairs used for recovery in a database belonging to another instance than the CA. With local key generation, the keys are stored in the RA's database and are encrypted with a crypto token (e.g. from a HSM) in the RA, so the key material is inaccessible to the operators of the CA (provided that they are restricted from logging in to the RA). The certificates and end-entities, however, remain stored in the CA and can be managed (e.g. revoked) from there.

In order to activate local key generation, the steps below are to be followed (this is performed on the RA which should keep the key recovery data):

• Under system configuration, set 'Enable Key Recovery' and 'Force Local Key Generation'
• Select the crypto token to be used for encryption of the key pairs (key recovery data).
• Select the desired key for encryption

Recovery data entries belonging to certificates enrolled before local key generation was enabled will remain in their initial database. Enabling local key generation doesn't change the way key recovery is performed by an administrator, nor the work flow of approvals, or access rules required. Keep in mind that the role handling the peer connector requires (at least) access to the same set of rules as the administrator of the external RA (e.g. to perform a key recovery).

Technical details

What the operation "bin/ejbca.sh ra keyrecovernewest", or "recover key" in the Admin GUI, or keyRecoverNewest in the WS API actually does is that it marks the user/certificate for key recovery. This means that the next time you make a call to generate a keystore (p12/jks/pem) for the user the CA will get the private key, held encrypted in the recovery database, and the existing user certificate or a new certificate, and create a keystore for the user with this old key pair. The actual recovery would then happen when you make a call to i.e. pkcs12Req in the WS API, or if keystore type is P12, JKS or PEM in the Admin GUI.

The keys are stored in the database in the table KeyRecoveryData. The data is stored encrypted in a CMS message, as a serialized Java KeyPair. The certificate is not stored in KeyRecoveryData, but only in CertificateData. The encryption key used for the CMS message encryption is the issuing CAs 'keyEncryptKey', and can thus be a key on the HSM. The actual CMS data encryption (RFC ??) is performed with AES256_CBC, using a random generated AES key (for this specific CM message). The AES key is wrapped using the RSA key in 'keyEncryptKey'. This is fully according to the best practices, open, stable, CMS standard.

There are additional columns in the KeyRecoveryData table enabling change of the 'keyEncryptKey' of the issuing CA. The columns cryptoTokenId and keyAlias gives an exact pointer to the Crypto Token, and specific key, used to encrypt the data. When decrypting data this specific key, with this alias, on the CAs Crypto Token, is first tried, and only if that fails the CAs 'keyEncryptKey' is tried. In additon the public Key Id (same as exists in CertificateData) of the public key used to encrypt the data is stored in the column publicKeyId. This means that even if keys changed it is possible to identify the exact public key used to decrypt the data.

Similarly the column serialNumber column of the table KeyRecoveryData matches the column serialNumber in the table CertificateData.

Uploading Modified CSS And Logo

RA Style content is uploaded from the 'System Configuration' menu in the Admin GUI. Go to 'System Configuration -> 'Custom RA Styles'. The page will display a list of previously uploaded styles or an empty list if no content has been added yet.

To upload RA logo: Browse for a single .png or .jpg file to replace the RA logo with.

To upload CSS files: Browse for either a single .css file or a .zip containing multiple .css files. The uploaded files must have the same name as the file they're replacing. Most of the RA appearance can be modified in w_e_styles.css, however, any CSS can be replaced. Below is a list of currently replaceable CSS files:

            base-context.css
            base.css
            base-min.css
            buttons-core.css
            buttons.css
            forms.css
            forms-nr.css
            grids-core.css
            grids.css
            grids-responsive.css
            grids-responsive-old-ie.css
            grids-units.css
            menus-core.css
            menus.css
            menus-dropdown.css
            menus-horizontal.css
            menus-scrollable.css
            menus-skin.css
            pure.css
            pure-nr.css
            tables.css
            pure.css
            ra.css
            w_e_style.css
        

It is not necessary to upload both logo and CSS. Only upload what you intend to replace. Finally, give the uploaded styles a name and click 'Import'.

In order to upload custom RA Syles, the following access rules are required:

• /administrator/
• /system_functionality/edit_systemconfiguration/

Applying Styles To Administrator Roles

Once styles are uploaded, it has to be bound to a role to take effect. This is done from the Admin GUI in 'Administrator Roles'. In order to apply a custom style to a role, go to 'Administrator Roles' and select the desired style from the drop down menu under the label 'RA Styles'. The next time members of this role login to the RA Web, their new style will be applied. Keep in mind that images and CSS files are browser cached, hence the changes might not appear until the browser cache is invalidated or cleared manually.

If an administrator belongs to multiple roles with RA Styles applied, the desired style can be changed from the 'Preferences' menu in the RA Web.

ICAO Specific Options

ICAO introduces some extensions and modifications to X509 standards. Those features should not be enabled for non-ICAO CA users since it would be possible to run some non-standardized X509 operations with unwanted results.

EAC CVC PKI (EJBCA Enterprise only)

You can use EJBCA Enterprise for EAC ePassport PKI creating CVCAs, DVs and issuing IS certificates. Usage of EJBCA for a complete PKI for CVC CAs are explained in this document.

End entity email notifications

Email notification can be sent when status changes for an end entity, for example when a new user is added (status changes to new).

To configure email notifications in EJBCA:

1. You must create a new end-entity profile to be able to issue certificates to end users using email notifications. Under the RA functions, choose "Edit End Entity Profiles" and add a new profile. Select the profile and go into 'Edit End Entity profile'. In this page you can Enable Send Notifications and create the notification message. Make sure the checkbox 'Use Send Notification' is checked.
2. Add a new end entity. You must select the new end entity profile you created above. Make sure the checkbox 'Send Notification' is checked. Enter the from-address and subject. Enter a message using the variables defined for dynamic substitution in the next section. Use ${NL} for newline in the mail message.

The Notification Recipient can have a few different values:

• USER: send notification to the email registered for the end entity.
• foo@bar.com: send notification to the specified email address. Multiple email addresses can be entered comma separated.
• CUSTOM: plug-in mechanism to retrieve addresses your own way. See interface org.ejbca.core.model.ra.raadmin.ICustomNotificationRecipient for implementation details. Enter a string like "CUSTOM:org.ejbca.MyCustomPluginClass" to use.

You can also use substitution variable in the notification sender and recipie/nt fields. See samples below.

The Notification Events specify which status changes for a user that will trigger a notification. The default values are suitable to send an email to a user when he/she should go and pick up a certificate. You can also select for example STATUSGENERATED to send email notifications to an administrator when the user picks up the certificate.

When STATUSREVOKED is selected, the notification will be triggered either if the entire user is revoked or if an individual certificate is revoked or re-activated (even though the End Entity's status will not change by the individual certificate revocation or re-activation).

Tip: If you configure autogenerated password in end entity profile you don't need to enter one in the adduser page. A generated one will automatically be sent with the email.

If you want to re-send a notification for a user, reset the status to NEW.

Dynamic Substitution Variables

Parameters that can be used with different usages of email notification. All parameters isn't always set, it depends on the input data.

The following parameters can be set:

• ${NL} = New Line in message
• ${DATE} or ${current.DATE} = The current date

Variables used with userdata:

• ${USERNAME} or ${user.USERNAME} = The user's username.
• ${PASSWORD} or ${user.PASSWORD} = The user's password, or "enrollment code" as it is called in most pages in the public web.
• ${UID} or ${user.UID} = The user's unique identifier.
• ${CN} or ${user.CN} = The common name of the user.
• ${SN} or ${user.SN} = The serial number (in DN) of the user.
• ${O} or ${user.O} = The user's organization.
• ${OU} or ${user.OU} = The user's organizational unit.
• ${C} or ${user.C} = The user's country.
• ${user.E} = The user's email address from Subject DN.
• ${user.EE.EMAIL} = Ther user's email address from the End Entity data.
• ${user.SAN.EMAIL} = The user's email address from Subject Alternative Name, RFC822Name field.
• ${user.TIMECREATED} = The time the user was created.
• ${user.TIMEMODIFIED} = The time the user was modified.
• ${requestAdmin.CN} = The common name of the requesting administrator.
• ${requestAdmin.EE.EMAIL} = The email address of the administrator adding the end entity according to the administrator's End Entity data.
• ${requestAdmin.SAN.EMAIL} = The email address of the administrator adding the end entity according to the administrator's Subject Alternative Name, RFC822Name field.
• ${approvalAdmin.XX} variables from below can be used to get the administrator who adds an end entity.

Variables used with approvals:

• ${approvalAdmin.USERNAME} = The last approving administrator's username
• ${approvalAdmin.CN} = The common name of the last approving administrator.
• ${approvalAdmin.SN} = The last approving administrator's DN serialNumber.
• ${approvalAdmin.O} = The last approving administrator's organization
• ${approvalAdmin.OU} = The last approving administrator's organization unit
• ${approvalAdmin.C} = The last approving administrator's country
• ${approvalAdmin.E} = The last approving administrator's email address from Subject DN
• ${approvalRequestID} = The ID of the approval request that was created

Variables used with expiring certificates:

• ${expiringCert.CERTSERIAL} = The serial number of the certificate about to expire
• ${expiringCert.EXPIREDATE} = The date the certificate will expire
• ${expiringCert.CERTSUBJECTDN} = The certificate subject DN
• ${expiringCert.CERTISSUERDN} = The certificate issuer DN

Variables used with revocation or re-activation of individual End Entity certificates:

• ${revokedCertificate.CERTSERIAL} = The serial number of the revoked certificate
• ${revokedCertificate.EXPIREDATE} = The date the revoked certificate will expire
• ${revokedCertificate.CERTSUBJECTDN} = The certificate subject DN
• ${revokedCertificate.CERTISSUERDN} = The certificate issuer DN
• ${revokedCertificate.REVOCATIONSTATUS} = The new revocation status of the certificate (Active/Revoked)
• ${revokedCertificate.REVOCATIONREASON} = The new revocation reason of the certificate (unspecified, keyCompromise, ...)

Examples

In certain circumstances, e.g. when you need to comply with PCI or the lighter levels of FIPS-140/160, it may be required to configure a 2 step issuance process. This can by done by using the notifications. Create 3 email notifications:

1. To: USER
   Email notification to -just- the user with the URL to pick up the cert and the username. Make clear in the message that he or she will be contacted by the approving admin with the password.
2. To: ${approvalAdmin.E}
   Email notification to the apporiving admin with the password (but not the username) and a message which makes clear that this password is to be passed to the user - by phone or f2f (but not by email).
3. To: ca-team@foo... **
   Email notification of the issuing to the auditor mailing lists - without above username/password.

An example URL to include in an email can be to directly take the user to the screen to generate a keystore:
https://server:8443/ejbca/enrol/keystore.jsp?action=generatetoken&hidemenu=true&textfieldusername=${USERNAME}&textfieldpassword=${PASSWORD}

Configuring Approvals

Approvals are configured for each CA, in the 'Certificate Authorities' page and for each certificate profile in the 'Certificate Profiles' page. Just select the actions that needs approval and the approval profile (see bellow) to use and save. The actions 'Add End Entity', 'Change End Entity' and 'Change User Status' are all covered by the setting 'Add/Edit End Entity'. 'Revoke End Entity', 'Revoke Certificate', 'Revoke Token' and 'Reactivate Certificate' are covered by setting 'Revocation'. Approvals will be required if the CA or the certificate profile enforces it. In case of both the CA and the certificate profile specify different approval profiles for the same actions, both approval profiles will apply in sequence; first the approval profile set in the CA, then the approval profile set in the certificate profile.

It is also worth noting that no administrator is allowed to take action regarding the same approval request more than once.

Approval Profiles

There are two types of approval profiles: Accumulative Approval Profile and Partitioned Approval Profile.

Both types of approval profiles allow for configuring a notification to be send to the end user and/or to the administrator expected to approve the request (See 'Approval Notification' section below). Both profile types allow also to set expiration period for the approval and for the request (See 'Explanation of approval status' section below).

Also see the User Guide for detailed information about Approval Profile fields.

Authorizing Approving Administrators

In order to authorize an administrator to review approval requests do one of the following.

Using Basic Rule Sets:

Give a role the role template of SuperAdmin, CAAdmin or RAAdmin with Approve End Entities selected.

The SuperAdmin and CAAdmin gives access to approve rules not associated with any end entity profile (i.e dual authenticated CA configuration (Not implemented yet)) while the RAAdmin only can approve actions related to authorized end entity profiles.

Using Advanced Rule Sets:

There are three new access rules:

• '/cafunctionality/approve_caaction', a rule that gives access to non end entity profile related actions like approving CA editing and creation (not implemented yet). An administrator must have either this rule or the '/rafunctionalty/approve_end_entity' in order to access the 'Approve Actions' web pages.
• '/rafunctionalty/approve_end_entity', a rule (along with the corresponding end entity profile rule) that gives access to end entity profile related access rules, like adding and editing end entities. The administrator must also have the 'approve_end_entity rule' for at least one of the '/endentityprofilerules/' in order to approve any actions.
• '/endentityprofilerules/<endentityprofilename>/approve_end_entity'see previous rule.

Two Different Approval Requests

In the system there are basically two different classes of requests. One is requests to do some action, like adding an end entity, and that is executed directly after the last required administrator has approved the action. This type is called 'Executable Action Request'. The other type are requests to get hold of some information, like hard token PUK codes or archived keys. This kind of request is approved when the last administrator gives his consent and is valid for a defined period of time (set in the approval profile). In this case the requesting administrator is supposed to poll the approval request if it has been approved or not. These requests are called 'Non-Executable Action Requests'.

Explanation of approval status

Here follows an explanation of what the different approval requests statuses.

• Waiting: Means that the action request is waiting to be processed by authorized administrators, request are valid for the time specified in the approval profile (Request Expiration Period) before it is set to status Expired.
• Approved: Means that the action request is approved and is valid for the amount of time specified in the approval profile (Approval Expiration Period). After this, it is set to Expired. Used by action requests that are not executable.
• Rejected: Means that the action request is rejected and won't be allowed. The rejection lasts the amount of time specified in the approval profile (Approval Expiration Period). After this it is set to Expired and a new request can be done. Used by action requests that are not executable.
• Expired: Means that the action request isn't valid any more and cannot be processed. The requesting administrator has to make a new request in order to approve it.
• Expired and Notified: Same as 'Expired' but also indicates that the requesting administrator has been notified about that his request have expired.
• Executed: Means that the action request have been executed successfully. Used by action requests that are executable.
• Execution Failed: Means that the action request failed for some reason during execution, see log for more information. Used by action requests that are executable.
• Execution Denied: Means that the action request hasn't been approved and will not be executed. The difference with status 'Rejected' is that this status is only used with executable requests and do not have any expire time. This means that the requesting administrator can apply again directly after the rejection.

Approval Notification

EJBCA approval functionality have been enhanced to send e-mail notifications to administrators affected by the approval workflow and/or the end user.

Notifications are configured per approval partition. An approval notification is sent for a partition when the partition:

• has been acted upon
• becomes approvable due to the previous step being finished
• no longer is approvable since a parellel partition has been rejected or the request has expired

Remember to configure mail-server settings in the mail.properties file.

Configuration

Setting up self registration consists of three steps: creating end-endity and certificate profiles that should be available, configuring email notifications, and configuring self registration in web.properties.
First, at least one end-entity profile should be created as follows:

• The SubjectDN and SubjectAltName fields that should be available must be added. Fields that are marked as modifiable can be modified freely, otherwise only pre-defined values can be selected by the user. See the user guide for further information.
• The user's e-mail can be verified by sending an auto-generated password to it (but this is not the only way to verify the user). The email domain field must be enabled with the Use checkbox, and auto-generated passwords must be enabled. Optionally the domain field may be constrained to particular choices, see the user guide section on end-entity profiles.
• E-mail validation works by sending the password in a notification message. For this reason, Send Notification must be enabled (check Use and Default), and the other notification fields below it should be filled in. See the section on email notifications.
• By the default the user will be prompted to fill in the username, but the username can also be generated from a field in the end-entity profile such as CN (common name), see below.

Note that sending of a password in an email is not the only way to do things. You can for example use multiple notifications where an enrollment link is sent to the user, but the password is sent to an administrator, or an out-of-band delivery service (through local email), or printed on paper. The solutions are highly configurable and adaptable.

E-mail sending must be configured in mail.properties to work. You may also want to enable notifications to the administrators when there are new approval requests, under System Functions / System Configuration.

To make the end-entity profiles available in the user interface, certificate types must be added in web.properties using the web.selfreg.certtypes.<identifier>.* properties (the identifier can be chosen arbitrarily). Each certificate type defines an end-entity profile and a certificate profile, and what name should be displayed in the user interface. If the username should be generated from a field, then this can be configured using the usernamemapping sub-property. Finally, to enable self registration, the property web.selfreg.enabled must be set to true.

Configuration

Multiple services and clustering

A service worker should never run simultaneously on two nodes, or simultaneously on one node. 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 have 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 of the service is already running on another node and 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 don't 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.

Currently Available Services

CRL Update Service

The CRL Updater checks if any of the configured CAs need a new CRL and updates it if necessary. The worker have no additional settings and only supports the periodical interval and no action.

Certificate Expiration Check Service

A worker that checks if a CA have certificates about to expire and sends an email notification the the end user and/or administrator. The worker have the following settings:

• CAs to Check - Select here which CAs that should be searched for expiring certificates.
• Certificate Profiles to Check - If any certificate profile is selected from this list, the notification service will require that certificates are issued by the selected CAs AND that they are issued using one of the selected certificate profiles. Leaving this list empty will cause the service to search for certificates just based on the CA selection.
• Time before notification is sent - The number of Days/Hours/Minutes/Seconds that should remain of the certificates validity before the notification is sent.
• Send notification to end user - Check this if a notification should be sent to the owner of the certificate. Observe that the end user must have an email set in the user database (not necessarily in the certificate) in order for the service to send the notification.
• Notification Subject to End User - The e-mail subject.
• End User Message - Message body of the notification. Substitution variables can be used here as defined in the 'Email Notifications' section.
• Send notification to Administrator - Check this if a notification should be sent to some defined administrator-mail address. The address of the administrator is configured in the Mail Action component.
• Notification Subject to Administrator - The e-mail subject.
• Administrator Message - Message body of the notification. Substitution variables can be used here as defined in the 'Email Notifications' section.

Note: you may configure multiple certificate expiration services set with different Time before notification is sent values in order to further alert the user or administrator that a certificate is about to expire.

User Password Expire Service

A worker that 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. The worker have the same basic setting as the 'Certificate Expiration Check Service', except for 'Time before notification is sent' which is replaced by:

• Time until user password expire - The number of Days/Hours/Minutes/Seconds that a user should be able to enroll for a certificate, i.e. the time before the user's password expire.

Renew CA Service

The renew CA service can be used to automatically renew CAs that are about to expire. This might be used for SubCAs that are valid only short periods of time. The specific settings are:

• CAs to Check - which CAs should be checked, and renewed if they are about to expire.
• Time before CA expires to renew - the amount of time before the CA actually expires that the service should renew the CA.

Publisher Queue Process Service

The publisher queue process service processes the publisher queue. In the publisher queue, entries where publishing failed is collected. This service will try to re-publish entries from this queue. The specific settings are:

• Publishers to check - which publishers should this service check and re-publish for. You can run one service for each publisher or one service for all publishers.

To read on how the algorithm to prevent excessive database load etc is done, the easiest way is to read in the java file for class PublishQueueProcessWorker.

The same algorithm as for the CRL update worker is used to make sure the service only runs in one instance on one node.

HSM Keepalive Service

The service periodically (with configured interval) goes through all available Crypto Tokens and makes a test signature if the following conditions are met:

• The crypto token is a PKCS#11 crypto token, i.e. have a PKCS#11 library path configured.
• The crypto token is active.
• The crypto token have a key with alias 'testKey'.

This will ensure that all configured PKCS#11 slots are used regularly, preventing connection timeouts that could lead to service downtime. You only need to enable this service if you encounter HSM timeouts. The occurance of such timeouts depend on the specific HSM used, neworking equipment etc.

Remote Internal Key Binding Updater

The service periodically (with configured interval) connects to the configured peer system using a Peer Connector and checks expiration of visible, usable and enabled Internal Key Bindings' certificates. For renewal to work, the issuing CA has to be usable on the system where this service is running and the same end entity that was used to issue the previous certificate must still exist.

• Time before certificate expires: How long before the current bound certificate expires it should be renewed.
• Renew key pair: Option to renew the key pair automatically before issuing a new certificate.

CRL Downloader

The service periodcally download a CRL from provided URL and imports it into EJBCA, including updating any revocation information for the certificates. Information on how to use this on a Validation Authority can be found in the OCSP User Guide, Populating the OCSP responder database using the CRL download service.

• CAs to Check: select the imported CA (or select ANY to process all external X509 CAs with a configured external CDP)
• Ignore nextUpdate and always download the CRL: select this option to force a download of the CRL whenever the service is executed instead of only downloading the CRL when the last known CRL indicates that a new one will be available.
• Maximum allowed size to download (bytes): The Service will refuse to process CRLs that are larger then this limit.
• Period: How often the Service should check if a new CRL needs to be downloaded.
• Active: Check to activate the service.

If the downloaded CRL from the external CDP contains the Freshest CRL extension, the service will try to download and process any such URL that uses "http" as protocol.

Writing Customized Services

It is possible to write customized component plug-ins that can be used with other standard (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 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 have 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

HSM modules available in the Admin GUI

Since EJBCA 6.0 you can manage crypto tokens fully in the Admin GUI or CLI. The admin GUI tries to be user friendly and automatically show you the HSMs available in your system. When creating a new Crypto Token (Crypto Tokens->Create New) you can select between Soft and PKCS#11 crypto tokens.

• The PKCS#11 option is only available if EJBCA can find any known PKCS#11 modules in the file system.

If EJBCA finds any available known PKCS#11 modules in the file system, you can select PKCS#11 as Type. As PKCS#11 Library there is a list of the available known HSMs found in the file system.

If the PKCS#11 option is not available or your desired HSM is not in the list of available Libraries there are a few options to configure:

• If you are using JBoss 7 you must make the java PKCS#11 classes exportable. See JBoss specific installation notes.
• You can configure PKCS#11 modules that are not already known to EJBCA in conf/web.properties. See conf/web.properties.sample how to add new known modules and override existing (overriding should not be needed since you can add new locations with the same name).

How to create and use Crypto Tokens for HSMs in the Admin GUI is describe in the User Guide, Managing Crypto Tokens and Managing CAs.

The rest of this chapter will mostly be more technical and describe the underlying operations and technical features of using HSMs and PKCS#11.

Configuring HSMs

The GUI configuration of CAs is actually backed by a properties field where properties unique to a particular CAs usage of the HSM is specified. All implemented HSM modules are using the same property keywords to define the identity and the purpose of the keys to be used. These keywords are:

• certSignKey - the key to be used when signing certificates, can be RSA or ECDSA.
• crlSignKey - the key to be used when signing CLSs, can be RSA or ECDSA.
• keyEncryptKey - the key to be used for key encryption and decryption, this must be an RSA key.
• testKey - the key to be used by HSM status checks, can be RSA or ECDSA.
• hardTokenEncrypt - the key to be used for hardtoken encryption and decryption. PUK will be decrypted by this key.
• defaultKey - the key to be used when no other key is defined for a purpose. If this is the only definition then this key will be used for all purposes.
• pin - optional pin code used for auto-activation of CA token, see below. Not recommended for high security set-ups, but very useful in some cases.

You may omit defaultKey if you want to be sure that the right key is used, but then all the other keys must be specified. It's recommended that the certificate and CRL signing keys are linked to the same key since different keys are rarely supported by verifying applications.

When implementing support for a new HSM the 'KeyStrings' class could be used to manage the key properties described above. When it is an JCA/JCE API for the HSM it could also be wise to extend the BaseCAToken class.

The same activation code must be used for all keys used by a CA.

There are four additional key properties that can (optionally) be used when renewing CA keys and to produce roll-over certificates. Some of these (in particular the 'next' keys) are only used when using API methods (such as WS).

• previousCertSignKey - this is the alias of the previous signature key, as opposed to 'certSignKey' which is the current signature key.
• previousSequence - this is the sequence identifying the previous signature key, as opposed to the current sequence that is held in the CA token. This sequence will replace the current sequence in the caRef field when signing a request with the CAs previous key.
• nextCertSigningKey - this is the alias of a new generated key on the HSM. When updating a CA signed by an external CA this is used to send a request, but the CA is still active using the old key. When the certificate response is received this key is activate and moved to certSignKey/crlSignKey.
• nextSequence - this is the sequence identifying the next signature key.

Supported and tested HSMs are described below, with sample configurations and HSM specific documentation.

Since EJBCA 3.6 the recommended HSM connector is to use the PKCS#11 interface. Older JCE implementations are deprecated and removed (contact us if you need to migrate).

Testing PKCS#11 keys for use by EJBCA

To test keys on the HSM for use by EJBCA you can use the EJBCA Client Toolbox.

ant clientToolBox
cd dist/clientToolBox
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test

The command will give further instructions about the parameters requires, PKCS#11 library and slot.

Auto-activation of Crypto Tokens

The 'pin' property is used to be able to automatically activate a CA token. The activation code may be specified in the property field with the keyword 'pin'. If this property is not specified then the CA has to be manually activated after each restart or re-deployment of EJBCA.
Manual activation is done in the admin-GUI under 'Basic Functions->View Information', or using the cli 'bin/ejbca.sh ca activateca'.

The 'pin' property can use a clear text password or an encrypted one.

pin foo123
pin 6bc841b2745e2c95e042a68b4777b34c

These two properties contains the same password. The encrypted pin value can be obtained with the command 'bin/ejbca.sh encryptpwd':

$ bin/ejbca.sh encryptpwd foo123
Using JBoss JNDI provider...
Please note that this encryption does not provide absolute security, ....
Enter word to encrypt:
hidden
Encrypting pwd...
6bc841b2745e2c95e042a68b4777b34c

NOTE: This encrypted password is not high security encryption. If 'password.encryption.key' property haven't been customized it won't provide more security than just preventing accidental viewing because an EJBCA built-in encryption key will be used. If an attacker gets hold of the encrypted password and the 'password.encryption.key' haven't been customized, it is easy for anyone to decrypt the password using the source code of EJBCA.

HSMs and DSA or ECDSA

Support for DSA or ECDSA in HSMs are dependant on the support for the algorithms in the HSM. You have to check if that support is available.

See Using ECDSA with an HSM in for some details and issues with HSMs and ECDSA.

Generic PKCS#11 provider

A PKCS#11 wrapper has been used to implement support for tokens with PKCS#11 libraries. The PKCS#11 provider have been tested with Utimaco CryptoServer and nCipher nShield/netHSM and SafeNet ProtectServer and SafeNet Luna and AEP Keyper and ARX CoSign and Bull TrustWay.

Besides the keys previously described the Crypto Token property field (matching with user friendly values of the Crypto Token in the Administration GUI) should contain the following properties:

• sharedLibrary - the path to the HSM PKCS#11 library (/etc/utimaco/libcs2_pkcs11.so, /usr/safenet/lunaclient/lib/libCryptoki2_64.so etc)
• slotLabelType - the type of slot reference, see below
• slotLabelValue - the value of the slot reference (1, myslot etc).

The slot label type can be one of the following

• SLOT_NUMBER - Any positive integer, can be used to refer to slots in any HSM with consecutive slot numbering.
• SLOT_INDEX - Any positive integer, prefaced by an 'i'.
• SLOT_LABEL - The PKCS#11 standard allows for using strings for labeling slots. This label may also be an integer or an 'i' followed by an integer (like a number or an index)
• SUN_FILE - The slot specified by a SUN config file. The slot label can be left blank.

Optionally a few extra properties fields can be used:

• attributesFile - a file specifying PKCS#11 attributes (used mainly for key generation).
• keyspec - key specification used when generating new HSM keys from within the admin GUI. Keyspec that is used as first choice when generating new keys in the GUI of form "1024" for RSA keys, "DSA1024" for DSA keys and secp256r1 for EC keys. If keyspec is not given EJBCA tries to generate a key with the same specification as the current cert signing key.

An attributes file is in the format specified in the JavaTM PKCS#11 Reference Guide and the examples further down in this file.

Before EJBCA 3.11 there were no default attributes used when no 'attributesFile' existed. Now there is a built in default configuration used when no attributesFile is specified. Unless you have some strange HSM not working well with the defaults(see below) you should NOT use an 'attributesFile'. Below is an example of an 'attributesFile' (that should not be used) which will give generated keys same attribute values as the default:

name=SafeNet
library=/opt/PTK/lib/libcryptoki.so
slot=1
attributes(*, CKO_PUBLIC_KEY, *) = {
  CKA_TOKEN = false
  CKA_ENCRYPT = true
  CKA_VERIFY = true
  CKA_WRAP = true
}
attributes(*, CKO_PRIVATE_KEY, *) = {
  CKA_TOKEN = true
  CKA_PRIVATE = true
  CKA_SENSITIVE = true
  CKA_EXTRACTABLE = false
  CKA_DECRYPT = true
  CKA_SIGN = true
  CKA_UNWRAP = true
  CKA_DERIVE = false
}
disabledMechanisms = {
  CKM_SHA1_RSA_PKCS
  CKM_SHA256_RSA_PKCS
  CKM_SHA384_RSA_PKCS
  CKM_SHA512_RSA_PKCS
  CKM_MD2_RSA_PKCS
  CKM_MD5_RSA_PKCS
  CKM_DSA_SHA1
  CKM_ECDSA_SHA1
}

The only occasion that we know of where the default is not working is when the module protected slot of a Thales/nCipher HSM is used; then the file must exist and have 'CKA_PRIVATE = false' (see below).

The default attributes that are applied to each key generated by EJBCA will assure that:

• All needed operations could be done.
• The private part of the key is stored in the HSM but not the public part (which is in a certificate that is stored on the HSM).
• It will be impossible to read the private part of the key from the HSM.

The default configuration will also disable some signing mechanisms. The disabled mechanisms are for signing when the data to be signed is hashed by PKCS#11 before using the private key in the HSM. When these mechanism are disabled the sun PKCS#11 wrapper provider will do the hashing instead of the of the HSM. This will speed up the signing in most cases, especially when your HSM is on another host. This will not have any security impacts since no secret in the HSM is used for the hashing.

However it will be possible not disable these hash/signing mechanisms, see the PKCS#11 section of '$EJBCA_HOME/conf/cesecore.properties'. You could try not to disable the mechanisms if you get the error CKR_FUNCTION_NOT_SUPPORTED (0x54) from PKCS#11 when signing.

The tool "EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool" is used administrate and generate keys. Use it without parameters to get all valid options. Keys may be generated in two ways. Examples:

dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate hsmp11.so 2048 defaultKey 1

dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate hsmp11.conf 2048 defaultKey

The first example is using built in default and are then using specified slot and PKCS#11 library. The second is using a configuration file. The contents of the file is specified in the PKCS#11 wrapper documentation from Oracle. Often it is enough to use the default but with some HSM it necessary to define some PKCS#11 attributes for the generated key.

All keys to be used has to be generated before the application server is started.

attributes(*,CKO_PRIVATE_KEY,*) = {
  .
  .
  CKA_LABEL = 0h6b657931
}

Utimaco CryptoServer

The Utimaco PKCS11 module have a configurable timeout (AppTimeout) that clears all session information if you do not use the keys for some time. The default time-out is 30 minutes, which may be way too short if your CA is not very very active. We recommend that you set this timeout to a longer value, several days.
Put a configuration file in /etc/utimaco/cs2_pkcs11.ini:

[Global]
Timeout = 5000
Logging = 0
Logpath = /tmp

[CryptoServer]
Device     = TCP:3001@172.16.175.128
Timeout    = 600000
AppTimeout = 172800
SlotCount  = 100

The timeout in this example of 172800 seconds will allow your CA to idle for a long time.

When using a PKCS#11 token you should first create keys with the command: $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate

Each CA should have its own slot.

Each slot must have been initialized before keys could be generated on the them. This includes setting a user PIN for it. The slot must also require login. Tools for doing this is not provided from EJBCA. The HSM vendor should provide this tool.

Here follows an example on how to initialize a slot and generate keys to be used by EJBCA. The password is user1:

./p11tool Slot=1 InitToken=officer1
./p11tool Slot=1 Label=CVCA LoginSO=officer1 InitPin=user1
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 4096 signKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry signKey.
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 2048 defaultKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry defaultKey.
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 512 testKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry testKey.

You can view the pkcs11 objects created with the command:

./p11tool Slot=1 Login=user1 ListObjects

This is a example of a property field when creating the CA:

defaultKey defaultKey
certSignKey signKey
crlSignKey signKey
testKey testKey
pin user1
sharedLibrary /opt/utimaco/p11/libcs2_pkcs11.so
slotLabelType=SLOT_NUMBER
slotLabelValue=1

Utimaco have an emulator for their CryptoServer LAN HSM that can be used for test and development. If you have the emulation kit there is a howto in doc/howto/cryptoserver-lan-emulator.txt with steps to follow in order to use it with EJBCA.

You can check the status of a CryptoServer LAN device, for example the emulator with:

./csadm Device=TCP:3001@172.16.175.128 GetState

nCipher nShield/netHSM

This subsection describes how the nShield card from nCipher is used.

First the card has to be installed and admin and operator card sets has to be created. This is described in step 1.

Step 2 describes environments variables that must be set before generating keys and installing a new CA.

Step 3-5 describes PKCS#11 keys are generated and how different CAs within an installation is configured to use these keys. In earlier versions of this manual it was also described how the nCipher JCA provider could be used by EJBCA. This has been removed since PKCS#11 keys are better in every respect.

Make sure you have all necessary software and drivers installed and created the user and group nfast. In Linux should the software be installed to /opt/nfast or the location environment variable NFAST_HOME is pointing to.

login as the nfast user: 'sudo su nfast'

Set the nCipher box to initialization mode by setting the switch to mode 'I'.

Clear the nCipher box by pressing the reset button on the device

Check that the mode is in 'pre-initialization mode' and not in 'operational':

nfast@donny:/home/lars/work$ /opt/nfast/bin/enquiry
Server:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number        41C5-BA04-6D2C
 mode                 operational
 version              2.23.6
 speed index          147
 rec. queue           442..642
 level one flags      Hardware HasTokens
 version string       2.23.6cam5, 2.22.6cam7 built on Apr 25 2005 18:15:46
 checked in           00000000431dca98 Tue Sep  6 18:58:00 2005
 level two flags      none
 max. write size      8192
 level three flags    KeyStorage
 level four flags     OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred
 module type code     0
 product name         nFast server
 device name
 EnquirySix version   4
 impath kx groups
 feature ctrl flags   none
 features enabled     none
 version serial       0
 remote server port   9004

Module #1:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number        41C5-BA04-6D2C
 mode                 pre-initialisation
 version              2.22.6
 speed index          147
 rec. queue           9..152
 level one flags      Hardware HasTokens InitialisationMode PreMaintInitMode
 version string       2.22.6cam7 built on Apr 25 2005 18:15:46
 checked in           00000000426636cd Wed Apr 20 13:02:37 2005
 level two flags      none
 max. write size      8192
 level three flags    KeyStorage
 level four flags     OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred
 module type code     6
 product name         nC1002P/nC3022P
 device name          #1 nFast PCI device, bus 0, slot 13.
 EnquirySix version   5
 impath kx groups     DHPrime1024
 feature ctrl flags   LongTerm
 features enabled     StandardKM
 version serial       24
 rec. LongJobs queue  8
 SEE machine type     gen1AIF

Create the security world with the command :

$ /opt/nfast/bin/new-world -i -Q 1/1
15:04:50 WARNING: Module #1: preemptively erasing module to see its slots!

Create Security World:
 Module 1: 0 cards of 1 written
 Module 1 slot 0: empty
 Module 1 slot 0: unknown card
 Module 1 slot 0:- passphrase specified - overwriting card
Card writing complete.

security world generated on module #0; hknso = 6807e0b031c4f797b739ec33ca7dba05279cf54f
$

The '-Q K/N' option tells how many administration cards that are created N. K of these cards will be needed to restore a module with a backup of the security world. '1/1' is a bad choice in production but will do in this example. Choose K>=3 and N>K in production.

Change mode on the switch on the device to mode 'O'.

Press the 'Clear' button again.

Check with 'enquiry' that the mode have changed to 'Operational'

Example on creation of operator cards:

$ /opt/nfast/bin/createocs -m 1 -Q 2/3 -N ejbca -M -p -T 0

Creating Cardset:
 Module 1: 0 cards of 3 written
 Module 1 slot 0: Admin Card #1
 Module 1 slot 0: empty
 Module 1 slot 0: blank card
 Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 1')
 Module 1: 1 card of 3 written
 Module 1 slot 0: remove already-written card #1
 Module 1 slot 0: empty
 Module 1 slot 0: blank card
 Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 2')
 Module 1: 2 cards of 3 written
 Module 1 slot 0: remove already-written card #2
 Module 1 slot 0: empty
 Module 1 slot 0: blank card
New passphrases do not match; please try again.
 Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 3')
Card writing complete.

cardset created; hkltu = 8d30f2ab5bdccacd8a4333aefed2c0ea1ff0e6db
$

This will generate 3 cards of the card set named 'ejbca'. Any 2 of these cards will be needed when generating keys and starting ejbca. Different card sets could be used for different CAs.

Load the card set so that keys protected by the card set could be generated:

$ /opt/nfast/bin/preload -c ejbca pause
Loading cardsets:
ejbca on modules 1

Loading `ejbca':
 Module 1 slot 0: `ejbca' #3 (`EJBCA card 3')
 Module 1 slot 0:- passphrase supplied - reading card
 Module 1 slot 0: `ejbca' #3 (`EJBCA card 3'): already read
 Module 1 slot 0: empty
 Module 1 slot 0: `ejbca' #2 (`EJBCA card 2')
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Loading complete; now pausing

Login as the user that is running the application server. This user must be a member of the nfast group.
The following environment variables should be set for this user:

• JAVA_HOME (/usr/local/jdk1.6.0_16 or similar)
• APPSRV_HOME (/home/jboss/jboss-5.1.0.GA or similar)
• EJBCA_HOME (/home/jboss/ejbca or similar)
• NFAST_HOME (/opt/nfast)

Start a new window and login as the same user (jboss user).

Now 3 keys protected by the key set 'ejbca' are created like this:

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1
Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry default.

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1
Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key (RSAPrivate) on modules 1
Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry crypt.

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1
Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-27cfdae84bf4298f2dde83cd00980a81bcf095bf key (RSAPrivate) on modules 1
Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry test.

To start EJBCA, preload must be running with the required key stores loaded. In this example this was done in step 2. Preload is now used to start jboss:

$ ~nfast/bin/preload -c ejbca $APPSRV_HOME/bin/run.sh

Choose PKCS#11 as "CA Token Type".

Properties are defined according to the "Generic PKCS#11 provider" section above.

All preloaded operator card sets (OCSs) has it's own slot. It is not possible to predict the slot ID. But the index of the slot in the slot list is predictable. "slotListIndex" must therefore be used. If only one OCS is preloaded this index is always 1.

If several CAs is sharing same OCS (and hence slot) each key (identified by a key label) may only be used for one CA but the test key. Same test key could be used for all CAs.

Example with previous generated keys where signRoot is used for CAs signing, and defaultRoot is used for everything else (encryption):

When preload is used no authentication code is needed to activate a CA. You could give any value for the authentication code when activating. The 'pin' property could be used in the configuration to automatically activate a CA. The value of this property could be anything.

defaultKey defaultRoot
testKey test
keyEncryptKey cryptRoot
hardTokenEncrypt cryptRoot
pin dummy
slotLabelType SLOT_INDEX
slotLabelValue 1
sharedLibrary /opt/nfast/toolkits/pkcs11/libcknfast.so

Module protected keys do not need an operator card set. Hence no PIN code is needed to active such a key. A CA could be configured to use a keystore with module protected keys.

When using PKCS#11 slot 0 is used to indicate module protection. The only other thing except using slot 0 you have to do is to use a configuration file when creating the key. The file could look like this:

name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex=0
attributes(*,CKO_PUBLIC_KEY,*) = {
  CKA_TOKEN = false
}
attributes(*,CKO_PRIVATE_KEY,*) = {
  CKA_TOKEN = true
  CKA_PRIVATE = false
  CKA_SIGN = true
  CKA_DECRYPT = true
}
disabledMechanisms = {
  CKM_SHA1_RSA_PKCS
  CKM_SHA256_RSA_PKCS
  CKM_SHA384_RSA_PKCS
  CKM_SHA512_RSA_PKCS
  CKM_MD2_RSA_PKCS
  CKM_MD5_RSA_PKCS
  CKM_DSA_SHA1
  CKM_ECDSA_SHA1
}

If a 1/N card set is used then preload don't have to be used (but it can be used). If preload is not used then jboss could be made to start automatically at boot time.

For PKCS#11 simple do not use the preload command. The authentication code is now needed when activating the CA.

It is also possible to use more than one OCS. This is needed when you want different CAs protected by different OCSs.

The key to get this working is to set the environment variable CKNFAST_LOADSHARING=1. This environment variable is also implicitly set when running with preload.

To get a list of all available slots do:

$ CKNFAST_LOADSHARING=1 ~nfast/bin/ckinfo
PKCS#11 library CK_INFO
       interface version 2.01
                   flags 0
          manufacturerID "nCipher Corp. Ltd               "
      libraryDescription "nCipher PKCS#11 1.58.48         "
  implementation version 1.58

slots[0] CK_SLOT_INFO
         slotDescription "                                                                "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 5
                   flags & CKF_TOKEN_PRESENT
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[0] CK_TOKEN_INFO
                   label "loadshared accelerator          "
          manufacturerID "nCipher Corp. Ltd               "
                   model "                "
            serialNumber "                "
                   flags 201
                   flags & CKF_RNG
                   flags & CKF_DUAL_CRYPTO_OPERATIONS
       ulMaxSessionCount 1024
     ulMaxRwSessionCount 1024
             ulMaxPinLen 18446744073709551615
             ulMinPinLen 0
     ulTotalPublicMemory CK_UNAVAILABLE_INFORMATION
      ulFreePublicMemory CK_UNAVAILABLE_INFORMATION
    ulTotalPrivateMemory CK_UNAVAILABLE_INFORMATION
     ulFreePrivateMemory CK_UNAVAILABLE_INFORMATION
        hardware version 0.00
        firmware version 0.00
                 utcTime "                "

slots[1] CK_SLOT_INFO
         slotDescription "1of2_0                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[1] Token not present
slots[2] CK_SLOT_INFO
         slotDescription "2of3_0                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[2] Token not present
slots[3] CK_SLOT_INFO
         slotDescription "ejbca                                                           "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[3] Token not present
slots[4] CK_SLOT_INFO
         slotDescription "2of3_1                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[4] Token not present
slots[5] CK_SLOT_INFO
         slotDescription "1of2_1                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 7
                   flags & CKF_TOKEN_PRESENT
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00


slots[5] CK_TOKEN_INFO
                   label "1of2_1                          "
          manufacturerID "nCipher Corp. Ltd               "
                   model "                "
            serialNumber "ee6071c52a77370c"
                   flags 20D
                   flags & CKF_RNG
                   flags & CKF_LOGIN_REQUIRED
                   flags & CKF_USER_PIN_INITIALIZED
                   flags & CKF_DUAL_CRYPTO_OPERATIONS
       ulMaxSessionCount 1024
     ulMaxRwSessionCount 1024
             ulMaxPinLen 18446744073709551615
             ulMinPinLen 0
     ulTotalPublicMemory CK_UNAVAILABLE_INFORMATION
      ulFreePublicMemory CK_UNAVAILABLE_INFORMATION
    ulTotalPrivateMemory CK_UNAVAILABLE_INFORMATION
     ulFreePrivateMemory CK_UNAVAILABLE_INFORMATION
        hardware version 0.00
        firmware version 0.00
                 utcTime "                "

You then got to identify your OCSs with the slot index. The "label" in the list gives the name you gave to your OCS when creating it. Then you get the slot list index from the x in "slot[x]. Use this for "slotListIndex" in the CA properties.

When using a 1/n OCS one card of the OCS must be inserted when activating a CA. If the OCS is persistent then the card could be removed and you could then activate another CA by inserting its OCS.

To make the OCS persistent use the "-p" argument at "createocs" time, if this is not the case as soon as the card is removed then the cardset will unload itself.

When using k/n OCS where k>1 you got to load all OCSs to be used with preload and then start the application server also with preload. Example:

$ ~nfast/bin/preload -c 2of3_0 pause
-- follow instruction to insert cards and enter pins. --
-- then press ctr-z --
$ bg 
$ ~nfast/bin/preload -c 2of3_1 exit
-- follow instruction to insert cards and enter pins. --

When the application server then is started with preload, CAs defined for slot list index 2 and 4 could be activated. When activating a CA when running preload no PIN has to be given. Also when the application server is started with preload then only CAs of preloaded slots could be activated (not preloaded 1/n slots could not be used).

nCipher load balancing

If you want to use the Loadsharing with multiple modules, be it PCI cards of NetHSM's then you must ensure you have a 1/N OCS and the N quorum to be able to have enough cards to be inserted in every HSM you want to load balance the key at server/CA start up when logging in.

Same security world got to be loaded in all modules participating.

After setting up the first netHSM, do the following on the second:

• Use the panel of the second netHSM to configure the rfs
• Use the panel of the second netHSM to load the security world
• Use the panel of the second netHSM to configure clients
• on each client run: /opt/nfast/bin/nethsmenroll

With load balancing you need to have CKNFAST_LOADSHARING=1. Preload implicitly sets CKNFAST_LOADSHARING.

Example of starting jboss:

ejbca@host:/usr/local/ejbca> CKNFAST_LOADSHARING=1 ../jboss/bin/run.sh

When activating a CA you need a smart card from the OCS of the corresponding slot inserted in both HSMs. The OCS got to be 1/n since preload can not be used.

Sample catoken.properties for generating the initial ManagementCA on the netHSM.

defaultKey defaultKey
certSignKey defaultSign
crlSignKey defaultSign
testKey testKey
sharedLibrary /opt/nfast/toolkits/pkcs11/libcknfast.so
slotLabelType=SLOT_INDEX
slotLabelValue 1

AEP Keyper

The document xxxxxxKeyperInstallation.pdf (xxxxxx is six digits) in the KeyPer UserGuides describes how the HSM is installed, the details start in section 3.5 (Configuring the Keyper HSM for the first time). As default there is only one slot - 0. The document xxxxxxKeyperP11.pdf describes the PKCS#11 interface in details.

ARX CoSign

This HSM only works on Windows. The installation is done with an installer and the setup with a GUI.

All generated keys will be on slot 1. The PIN code used when activating the keys could be anything since the authentication is made when login on to the user that runs EJBCA. The shared library is called C:\windows\system32\sadaptor.dll

Bull Trustway Proteccio

The "Installation and User's Guide" describes how the HSM is installed and how how PKCS#11 tokens are created and how a backup of a token is done. But it might be helpful to mention some additional things:

1. A virtual HSM correspond to a PKCS#11 token.
2. The number of the virtual HSM corresponds to the PKCS#11 slot ID of the token.
3. The PKCS#11 user PIN is the "PKCS#11 application authentication" in the "Personalizing a virtual HSM" step.
4. If "CIK startup mode" is selected for the virtual HSM personalization you must start the HSM manually before EJBCA can use it.
5. Make sure that backup-restore work before taken the HSM in production since the first versions did not backup the certificate of a key which is needed by the java wrapper.

Bull Trustway PCI Crypto Card

This is an old HSM. New installations will probably use Proteccio.

Do the installation of the card according to Install_and_Use_cc2000.pdf. When the card is "installed" it is ready to use with EJBCA. Only one slot (slot index 0) is available. The slot is not protected by any PIN so an undefined 'pin' (empty) property may be used in the configuration.

When using PKCS11HSMKeyTool and starting EJBCA, libcc2000_tok.so and libgpkcs11cc2000.so must be in the library path. Examples:

lars@maud:~/work/test/ca$ ls -al ../../bullInstall/linux
total 412
dr-xr-xr-x 4 lars lars   4096 28 nov 14.28 .
drwxr-xr-x 4 lars lars   4096 20 apr 21.05 ..
dr-xr-xr-x 6 lars lars   4096 20 apr 21.38 CardAdmin_java
-r-xr-xr-x 1 lars lars  35804 28 nov 14.15 cc2000_lx24.tgz
-r-xr-xr-x 1 lars lars  74955 28 nov 14.15 cc2000_src.tgz
-r-xr-xr-x 1 lars lars     14 28 nov 14.15 cc2000S_release
-r-xr-xr-x 1 lars lars    633 28 nov 14.15 desinstall
-r-xr-xr-x 1 lars lars    171 28 nov 14.15 gpkcs11cc2000.rc
dr-xr-xr-x 2 lars lars   4096 28 nov 14.28 include
-r-xr-xr-x 1 lars lars   7209 28 nov 14.15 install
-r-xr-xr-x 1 lars lars 101788 28 nov 14.15 libcc2000_tok.so
-r-xr-xr-x 1 lars lars 146820 28 nov 14.15 libgpkcs11cc2000.so
-r-xr-xr-x 1 lars lars   3843 28 nov 14.15 LisezMoi.txt
-r-xr-xr-x 1 lars lars   3410 28 nov 14.15 ReadMe.txt
lars@maud:~/work/test/ca$ LD_LIBRARY_PATH=../../bullInstall/linux ../../java/jboss/bin/run.sh

$ LD_LIBRARY_PATH=~/work/bullInstall/linux $EJBCA/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ../../bullInstall/linux/libgpkcs11cc2000.so 2048 defaultkey i0

SafeNet Luna

$ /usr/lunasa/bin/ctp admin@lunasa.int.primekey.com:server.pem .

$ sudo /usr/lunasa/bin/vtl addServer -n lunasa.int.primekey.com -c server.pem
$ sudo /usr/lunasa/bin/vtl createCert -n milton

$ /usr/lunasa/bin/vtl verify

The following Luna SA Slots/Partitions were found: 

Slot    Serial #        Label
====    ========        =====
 1      950784001       partition1
 2      950784002       partition2

lunash:>hsm login
lunash:>partition activate -partition partition1 -password btqx-EFGH-3456-7/K9

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so 2048 rsa2048_1 1
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password: 
Created certificate with entry rsa2048_1.
$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so secp160r1 secp160r1_1 1
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password: 
Created certificate with entry secp160r1_1.

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /usr/lunasa/lib/libCryptoki2_64.so 1
Test of keystore with ID 1.
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-libCryptoki2_64.so-slot2] Password: 

Testing of key: rsa2048_1
SunJCE version 1.7SunPKCS11-libCryptoki2_64.so-slot2 version 1.7; modulus length: 2048; byte length 245. The docoded byte string is equal to the original!
Signature test of key rsa2048_1: signature length 256; first byte 28; verifying true
Key statistics. 
Signings per second: 369; Decryptions per second: 135

Testing of key: secp160r1_1
Signature test of key secp160r1_1: signature length 48; first byte 30; verifying true
Key statistics. 
Signings per second: 68 No crypto available for this key.

sharedLibrary=/usr/lunasa/lib/libCryptoki2_64.so
slotLabelType=SLOT_NUMBER
slotLabelValue=1
certSignKey=myECCKey
crlSignKey=myECCKey
defaultKey=default

./cmu list -display=index,handle,class,keyType,label

./cmu selfSign -privatehandle=87 -CN="caSign00001" -startDate=20020101
-endDate=20451231 -serialNum=0133337f

SafeNet ProtectServer

fakeroot alien -c $CDROM/Linux64/ptkc_sdk/ETcpsdk-3.32.00-1.x86_64.rpm
sudo dpkg -i ./etcpsdk_3.32.00-2_amd64.deb

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf -c10

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctconf -fc

LD_LIBRARY_PATH=/opt/PTK/lib /opt/PTK/bin/ctkmu t -s5 -lroot

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 2048 defaultSign 5
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 2048 default 5
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/PTK/lib/libcryptoki.so 512 test 5

certSignKey defaultSign
crlSignKey defaultSign
defaultKey default
testKey test
sharedLibrary=/opt/PTK/lib/libcryptoki.so
slotLabelType=SLOT_NUMBER
slotLabelValue=5

./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 5
...
Testing of key: test
SunJCE version 1.7SunPKCS11-libcryptoki.so-slot3 version 1.7; modulus length: 2048; byte length 53. The docoded byte string is equal to the original!
SunPKCS11-libcryptoki.so-slot3 RSA private key, 512 bits (id 4, token object, sensitive, extractable)
Signature test of key test1: signature length 64; first byte 3d; verifying true
Signings per second: 257
Decryptions per second: 260

ctkmu -s <slot nr> t

cd /opt/ETCprt/bin/linux-x86-64
./ctkmu c -tec -nfoo -aPSVXxTRD -s1 -CP-256
./ctcert c -s1 -lfoo
./ctkmu l -s1

./ctcert c -k -lfoo -tec -s1 -CP-256 -d30y

SmartCard-HSM

SmartCard-HSM is a lightweight hardware security module in a Smart Card, MicroSD or USB form factor providing a remotely manageable secure key store to protect your RSA and ECC keys.

• Accessing your SmartCard-HSM from EJBCA
• Shared control over key usage

SoftHSM

SoftHSM2 works very well with EJBCA, and after initializing a slot you can use it nicely by creating a new Crypto Token in the Admin GUI. The 'user PIN' is what you will use to activate the token in EJBCA.

sudo apt-get install softhsm2

In order to use it as a normal user you have to make /var/lib/softhsm/tokens available to your normal user (for writing in order to create keys), and /etc/softhsm/* readable by the user. After setting privileges, you can use softhsm as normal user.

softhsm2-util --init-token --free --label myslot

It turns out that the Ubuntu package for SoftHSM2 is not always initializing properly (depending on Ubuntu verion you are running on) so you may have to create missing directories etc. If you get an "ERROR: Could not initialize the library" when running the above there is a directory missing, and a token not initialized.

sudo mkdir /var/lib/softhsm/tokens
sudo chmod a+rwx /var/lib/softhsm
sudo chmod a+rwx /var/lib/softhsm/tokens
sudo chmod a+rx /etc/softhsm
sudo chmod a+r /etc/softhsm/*
softhsm2-util --init-token --free --label myslot

Now you can go on and initialize other slots as well. Note that if you provide the --slot parameter to SoftHSM2 it will most likely not actually become the slotnumber you specify. You can list the slots with:

softhsm2-util --show-slots

PKCS11 Spy

You can debug PKCS11 sessions, all calls made, using OpenSC's P11Spy. From EJBCA 6.8.0 it is included by default in known P11 implementation in con/web.properties.

Stop JBoss, install p11spy and set a couple of environment variables that are used in the JBoss terminal.

apt-get install opensc-pkcs11
export PKCS11SPY=/usr/local/lib/softhsm/libsofthsm2.so
export PKCS11SPY_OUTPUT=logfile.log

Start JBoss, and create a new PKCS11 Crypto Token using the PKCS11Spy 'PKCS#11 Library'.

Support for new HSMs

EJBCA uses PKCS#11 so in theory can support any HSMs that provide a decent PKCS#11 implementation. If the HSM is peculiar you may have to provide specific attribute parameters as descibed for an 'attributesFile' above.

Using SHA256WithRSAandMGF1 (RSASSA-PSS)

Out of the box in Java PKCS#11 RSASSA-PSS is not supported. The software in EJBCA supports it, but the Java PKCS#11 provider does not.

At the time of writing, Oracle Java does not have support for SHA256WithRSAandMGF1 (also known as RSASSA-PSS) in the PKCS#11 provider. PrimeKey has made a patch which is waiting for approval in the OpenJDK. You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.

This issue is registered in the EJBCA issue tracker as ECA-2014.

The patch should work on all HSMs that have support for SHA256WithRSAandMGF1.

With the patch applied you can create CAs using HSMs with the SHA256WithRSAandMGF1 (and SHA384 and SHA512) algorithm.

Extending Sun PKCS#11 to set CKA_MODIFIABLE=false

In order to change the CKA_MODIFIABLE attribute of a private key to FALSE directly after it has been generated the Sun PKCS#11 implementation must be extended. This extension must be done by adding classes to "Installed Extensions" classpath. See https://docs.oracle.com/javase/tutorial/ext/basics/install.html

This is achieved by putting the '$EJBCA_HOME/dist/ext/cesecore-p11.jar' in one of the directories that is defined by the 'java.ext.dirs' system property. You can put the jar in '$JAVA_HOME/jre/lib/ext'. You may also change the property to include the directory of the jar. Here is an example:

JAVA_OPTS="-Djava.ext.dirs=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/ext:$EJBCA_HOME/dist/ext" $JBOSS_HOME/bin/standalone.sh

But be sure to keep '$JAVA_HOME/jre/lib/ext' in the classpath.

To enable the feature in EJBCA you have to set 'pkcs11.makeKeyUnmodifiableAfterGeneration=true' in $EJBCA_HOME/conf/cesecore.properties

If you use '$EJBCA_HOME/dist/ejbcaClientToolBox.sh' you don't have to bother with the java.ext.dirs setting. The script is taking care of it.

Everything will work without this jar in the classpath but if it is not in classpath the CKA_MODIFIABLE will be TRUE for every key that is generated. A warning will be written once to the log to notify about this.

The reason to set CKA_MODIFIABLE to FALSE is that it should not be possible to set CKA_DERIVE to TRUE. If CKA_DERIVE is true it might be possible to extract the private key from some HSMs (CVE-2015-5464), although most vendors have now patched this by not allowing weak key derivation schemes.

Some HSMs (for example SoftHSM2) refuses to set CKA_MODIFIABLE to FALSE (the PKCS#11 standard says that this behavior is OK).
On some HSMs other behavior may arise.

In summary you need to test this very carefully if you want to try it. A good way to test is to use clientToolBox with a generate-test cycle:

$EJBCA_HOME/dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate (to generate a new key)
$EJBCA_HOME/dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool test (to test, in a new PKCS#11 session if it is usable)

If you also generate keys through the Admin GUI, you should test this, including restarting JBoss between generation and usage.

Generated keys and certificate

When generating a CA in EJBCA up to three keys and certificates are generated:

• A CA signing keypair and certificate
• An encryption keypair, used for encrypting keyrecovery information
• An OCSP signer keypair and certificate

Using ECDSA with an HSM

See the section about HSM property parameters to see which keys can be of different sorts. Note that the keyEncryptKey can not be ECDSA, but should be an RSA key. Your HSM must support both ECDSA and RSA keys. You can use PKCS11HSMKeyTool from the clientToolBox to generate keys and certificate requests from an HSM.

PrimeKey has made a patches for the java issues with ECDSA. These patches are waiting for approval in the OpenJDK 7. You can get a compiled patch together with an installation script for Linux operating systems (can be adapted for Windows as well) from PrimeKey.

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so brainpoolP160r1 keyAliasBp160 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /usr/lunasa/lib/libCryptoki2_64.so 1

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /etc/utimaco/libcs2_pkcs11.so brainpoolP160r1 keyAliasBp160 1
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /etc/utimaco/libcs2_pkcs11.so 1
  

./ctconf -fcE

./ctkmu idp -s 1 -t ec -n brainpoolP160r1 brainpoolP160r1.txt

./ctcert c -k -l bpkey -tec -s1 -CbrainpoolP160r1 -d30y

./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 1

sharedLibrary=/opt/PTK/lib/libcryptoki.so
defaultKey=bpkey
slotLabelType=SLOT_NUMBER
slotLabelValue=1

ECC named curves vs explicit parameters

Normally you want to generate requests and certificates using named curves encoded in certificates and requests, this is what IETF recommends. In some cases you need to generate the request and certificate with explicit parameters instead, this is for instance mandated by ICAO for usage in CSCA's and DS's for ePassports.

• When generating requests with clientToolBox PKCS11HSMKeyTool certreq you can specify a flag to use explicit parameters instead of named curves. Named curves is the default.
• When creating CAs with ejbca.sh ca init you can specify a flag to use explicit parameters instead of named curves. Named curves is the default.
• When EJBCA issues certificate with public keys from certificate requests (csr's) the key in the certificate will be the same as in the csr. If the csr uses explicit parameters, so will the issued certificate.

If you generate a CA with explicit ECC parameters in the CA certifiate you will not be able to run commands like 'ejbca.sh ca listcas' because Java only supports named curves when serializing certificates. You can resolve this by adding the BC provider as the first provider:

$ sudo vi /etc/java-7-openjdk/security/java.security

security.provider.1=org.bouncycastle.jce.provider.BouncyCastleProvider
(renumber the ones below)

After editing this (make sure you edit the right file) you need to restart JBoss.

Named curves

EJBCA supports the curves that BouncyCastle supports, they include named curves from Nist, SEC and X9.62. New curves may be supported without this list being updated, give it a try! See Bouncycastle wiki for more information about ECDSA curves.

X9.62 curves:

• prime192v1
• prime192v2
• prime192v3
• prime239v1
• prime239v2
• prime239v3
• prime256v1

• sect571r1
• sect409r1
• sect283r1
• sect233r1
• sect163r2
• secp521r1
• secp256r1
• secp224r1
• secp384r1

• P-224
• P-256
• P-384
• P-521
• B-163
• B-233
• B-283
• B-409
• B-571

• brainpoolp160r1
• brainpoolp160t1
• brainpoolp192r1
• brainpoolp192t1
• brainpoolp224r1
• brainpoolp224t1
• brainpoolp256r1
• brainpoolp256t1
• brainpoolp320r1
• brainpoolp320t1
• brainpoolp384r1
• brainpoolp384t1
• brainpoolp512r1
• brainpoolp512t1

ImplicitlyCA curves

X9.62 provides 3 alternatives for the parameters that can be found in an EC public key. One of these is named implicitlyCA and indicates that the parameters are defined else where, implicit in the name of the certification authority (CA) that issued the key. In this situation the actual parameters appear in the ASN.1 encoding of the key as a DER encoded NULL.
As the definition says, when the key is used, the parameters will have to come from elsewhere. In EJBCA the parameters are configured in conf/cesecore.properties.

When creating a new CA using the implicitlyCA facility, you first configure your curve parameters in conf/cesecore.properties and issue commands:

• ant clean
• ant deployear

When issuing client certificates where the client public key uses implicitlyCA, you must allow key length 0 in the certificate profile, because EJBCA can not read the key length, since the parameters are defined elsewhere.

See Bouncycastle wiki for more information about the implicitlyCA facility.

The curve parameters in conf/cesecore.parameters are configured in Bouncycastle using the following code:'

ECCurve curve = new ECCurve.Fp(
    new BigInteger(ecdsa.implicitlyca.q), // q
    new BigInteger(ecdsa.implicitlyca.a, 16), // a
    new BigInteger(ecdsa.implicitlyca.b, 16)); // b
org.bouncycastle.jce.spec.ECParameterSpec implicitSpec = new org.bouncycastle.jce.spec.ECParameterSpec(
    curve,
    curve.decodePoint(Hex.decode(ecdsa.implicitlyca.g)), // G
    new BigInteger(ecdsa.implicitlyca.n)); // n
ConfigurableProvider config = (ConfigurableProvider)Security.getProvider(BouncyCastleProvider.PROVIDER_NAME);
config.setParameter(ConfigurableProvider.EC_IMPLICITLY_CA, implicitSpec);

Creating client certificates

You can also issue normal requests for client certificates using ECDSA keys.
All certificates signed by an ECDSA CA will naturally use ECDSA signatures, regardless if the client keys are RSA or ECDSA.

When batch generating client keys using the cli command 'bin/ejbca.sh batch' you configure the type of client keys that will be generated in the file conf/batchtool.properties. The possible parameters are explained there. If using the implicitlyCA facility the same parameters as configured for the ca in conf/cesecore.properties are used.

Limitations

When using the 'implicitlyCA' mode only one set of curve parameters can be set for the whole EJBCA instance. This means that if you have several CAs using ECDSA with 'implicitlyCA', they will all use the same curve parameters. You can mix 'implicitlyCA' with named curves any way you like though.

Setting up Peer Connectors for Outgoing Connections

Outgoing connections are allowed by default and can be disabled by administrators authorized to /peer/modify recursive.

A Peer Connector is a representation of a remote EJBCA instance and can be referenced by other components like Publishers and Services. Each Peer Connector maintains a pool of outgoing re-usable (HTTP Keep-Alive) connections and new connections are only created when needed.

To authenticate to a peer, you need to configure an AuthenticationKeyBinding. The AuthenticationKeyBinding is the EJBCA instance identity and consists of a client SSL X509 certificate and a key pair in one of the instance's Crypto Tokens. Ensure that the AuthenticationKeyBinding is configured to trust the peer's server SSL certificate or the connection will fail. AuthenticationKeyBinding settings are only read when a Peer Connector's connection pool is started and if the client certificate is updated this will not take effect until a connection pool is Reset.

For each configured Peer Connector, you can see the human readable name, connection end point and current connection status. You can Ping any of the peers to check connectivity and the result is the round-trip time from and to the application over the secure connection (giving a more accurate view of the actual round trip time than a network ping using the ICMP protocol).

Only the first connection to a peer using the same client certificate will be subject to a full authentication check and subsequent requests will share the same credential. This means that an initial Ping request to a peer system will be significantly slower than the next one.

Incoming connections

Incoming connections are not allowed by default and can be enabled by administrators authorized to /peer/modify recursive.

In the list of incoming connections, you can see systems that have successfully connected to the EJBCA instance with a client certificate trusted by the application server's SSL configuration. If the client certificate presented by the connecting system is already part of an Administrator Role, the name of this role will be shown.

Management operations for an EJBCA Peer System

Once an EJBCA instance has been authorized to connect and manage another EJBCA instance, operations on the peer can be performed through the Admin GUI of the authorized instance.

The administrator initiating these operations needs to be authorized to the /peer/view /peer/manage access rules and additionally any relevant CA.

Serving Registration Authority requests via Peer Connections

The Registration Authority (RA) added in EJBCA 6.6.0 can be run either locally or remotely using long-hanging Peer Connections from CA to RA.

The CA will connect to the RA and listen for requests, grab either the first pending or wait for one, and return the request to the CA. Once the CA is done processing the request, it will reconnect to the same RA and deliver the result and then wait for a new request.

Audit Logging

All validation results are audit logged and also logged in the server logs for more detail.

Key Validators

Key Validators are rather intuitively meant to validate the quality of keys, foremost as a result of incoming CSRs. There are currently three types of Key Validators:

bin/ejbca.sh ca updatepublickeyblacklist --command add --dir <directory of blacklisted public keys>
			

openssl req -key blacklisted-privatekey.pem -out blacklisted.csr -new
openssl rsa -in blacklisted-privatekey.pem -pubout > tmp/blacklisted-publickey.pem
			

bin/ejbca.sh ca updatepublickeyblacklist --command add --mode fingerprint --keyspecs RSA2048 --dir <directory where blacklist fingerprint file resides>
			

bin/ejbca.sh ca updatepublickeyblacklist --command remove --mode fingerprint --dir <directory where blacklist fingerprint file resides>
			

Certificate Field Validators

One may also wish to validate issuance based on other values which can't be evaluated during end entity creation. Currently, only one such validator has been implemented, the CAA Validator.

example.com. 243	IN	CAA	0 issue "ca.org"

15:49:07,017 INFO  [org.cesecore.keys.validation.KeyValidatorSessionBean] (default task-24) VALIDATOR_VALIDATION_FAILED;FAILURE;VALIDATOR;CORE;msg=CAA Validator 'CAA Validator' failed issuance of certificates 
to issuer primekey.com, with messages: 
[Not allowed to issue certificate for dnsName *.allow.klaan.nu. Result type was: Issuance of wildcard certificates for this domain is prohibited. Parameters: {} Message: 
, Allowed to issue certificate for dnsName *.klaan.nu. Result type was: May issue, no CAA results for domain. Parameters: {} Message: 
, Not allowed to issue certificate for dnsName allow.klaan.nu. Result type was: Rejected due to issuer not having a CAA record at domain's DNS, or issuance being prohibited. Parameters: {} Message: ].			
			

15:50:58,930 INFO  [org.cesecore.audit.impl.log4j.Log4jDevice] (default task-8) 2017-09-20 15:50:58+02:00;VALIDATOR_VALIDATION_SUCCESS;SUCCESS;VALIDATOR;CORE;ejbca;1865017768;;caaklaan1;msg=CAA Validator 'CAA Validator' 
has permitted issuance of certificates to issuer primekey.com, with messages: 
[Allowed to issue certificate for dnsName *.klaan.nu. Result type was: May issue, no CAA results for domain. Parameters: {} Message: 
, Allowed to issue certificate for dnsName a.allow.klaan.nu. Result type was: May issue. Parameters: {} Message: primekey.com
, Allowed to issue certificate for dnsName b.allow.klaan.nu. Result type was: May issue. Parameters: {} Message: primekey.com].			

Common Validator Settings

To control the behaviour while certificate issuance, for every validator the following base restrictions can be applied:

• Description - a general decription of the Validator, not used for any validation purposes.
• Apply for Certificate Profiles - Validate keys for these certificate profiles only. If nothing is selected in this list, no validation will be performed.
• Apply for all Certificate Profiles - Validate keys for all certificate profiles, the list above will be ignored.
• If Validation failed - Define behaviour if key validation fails (i.e. abort issuance, log error message to trigger monitoring systems, etc.). All failed issuance also adds a record in the security audit log.
• If Validator was not applicable: - Define behaviour if the input is not applicable for the selected validator (i.e. abort issuance, log error message to trigger monitoring systems, etc.). This handles the case when for example a CSR with ECC keys is passed to an RSA key validator.

Publisher Access Rules

The presumed administrator of publishers is the built in CA Administrator role, or more specifically a role with access to /ca_functionality/edit_publishers. Besided that, only the following publishers will be available for a given role:

• Publishers assigned to a CA that the role has access to.
• Publishers not assigned to any CA.
• EJBCA Enterprise only: Validation Authority Peer Publishers, given that the role has access to /peer/view

LDAP Naming

A good book to understand LDAP naming is "Understanding and Deploying LDAP Directory Services". The recommended method of choosing a naming suffix is the one described in RFC2247 that maps a DNS domain to a DN. If my DNS domain is bigcorp.com it will map to the DN "dc=bigcorp,dc=com". The top node in my LDAP directory will then be "dc=bigcorp,dc=com".

The dc component support is mandated by all of the X.509 RFCs now. For example, if I have this directory:

dc=bigcorp,dc=com
    |
    +-dc=fi
    |
    |
    +-dc=se
        |
        +-cn=Mike Jackson

The most understandable method is taking the subject name in forward order, like: cn=Mike Jackson,dc=se,dc=bigcorp,dc=com

If the DN is ordered like this it should be published to the correct object in the tree.

If the DN is ordered reverse, like: dc=bigcorp,dc=com,dc=se,cn=Mike Jackson EJBCA will reorder it incorrectly to forward order, so the publishing will be wrong.

Therefore... Use forward order like this: 'cn=Mike Jackson,dc=se,dc=bigcorp,dc=com' if using the dc model or
'cn=Mike Jackson,o=bigcorp,c=se' if using the o,c model.

An example image of an LDAP structure can be seen below in HOWTO-LDAP-tree.png.

Making unique LDAP DNs is the next challenge. If you are in a small organization having the CN will probably work fine, but in a larger organization there are probably several people with the same name. Somehow the names must be made unique, and one way is to introduce numbers, initials etc in the CN. Another way that we recommend is to use uid in the LDAP DN instead. LDAP DNs will then looks like "uid=tomas,dc=bigcorp,dc=com". Uid is the users username, normally used for login etc, and you probably already have some procedure to create unique usernames already.

LDAP Basics

LDAP has an unusual structure, if you are not used to X.500 style naming. Things are either branches, or leaf nodes. You can't just drop an object anywhere you like; You need to create the framework to support it. Sort of like if you wanted to put entries in /etc/hosts, if the directory /etc did not exist.

First you mkdir /etc, Then you create the file. Then you start putting things in the file. The difference with LDAP and x.500 is that instead of paths separate by slashes, you have paths separated by commas and '=' signs.

For example, if you want to make an object "cn=ldaphost,ou=hosts,dc=yourdom,dc=com", you first have to make sure "dc=yourdom,dc=com" exists.
Then make sure
"ou=hosts,dc=yourdom,dc=com" exists.
THEN you can try
"cn=ldaphost,ou=hosts,dc=yourdom,dc=com"

EJBCA does not create branches in LDAP. You have to put them there with other means, before you start publishing.

bin/ejbca.sh ra addendentity ldap password "C=SE,O=Foo,CN=ldap.foo.se" MyCA 1 PEM SERVER

Configure LDAP publishers

A Publisher is a session bean that implements the IPublishSession interface and is used to store certificates and CRLs for entities. EJBCA have support for endless number of publishers simply by defining publishers in the Admin GUI. The user of EJBCA can implement own publishers, but EJBCA already comes with a publisher for LDAP.

EJBCA uses a notion of base DN to publish to different LDAP structures. The DN used in the certificate can be different from the LDAP structure.

CN=somename,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,DC=somemachine,DC=primekey,DC=se

ldap:///CN=Test%20MS%20SC%20Logon%20CA%20v1,CN=somename,CN=CDP,CN=Public%20Key%20Services,CN=Services,
CN=Configuration,DC=somemachine,DC=primekey,DC=se?certificateRevocationList?base?objectClass=cRLDistributionPoint

Configure OpenLDAP

The objectclass 'inetOrgPerson' is used by default to store certificates.

Example:

dn: cn=Mike Jackson,ou=people,dc=company,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Mike Jackson
sn: Jackson
userCertificate;binary::

CAs are published in the form:

dn: cn=ejbca,dc=jackson,dc=net
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: ejbca
cACertificate;binary:
certificateRevocationList;binary:
authorityRevocationList;binary:

To configure OpenLDAP (version 2.2.5) to include the 'inetOrgPerson' you must add the following lines to slapd.conf. This is already the default in recent releases:

include         /etc/ldap/schema/cosine.schema
include         /etc/ldap/schema/inetorgperson.schema

Don't forget to add the top object by creating an LDIF file (org.ldif):

dn: o=AnaTom,c=SE
objectclass: dcObject
objectclass: organization
o: AnaTom
dc: AnaTom

dn: cn=Admin,o=AnaTom,c=SE
objectclass: organizationalRole
cn: Admin

And using the command:

ldapadd -x -D "cn=Admin,o=AnaTom,c=SE" -W -f org.ldif

Check what you have in the LDAP by:

ldapsearch -x -b 'o=AnaTom,c=SE' '(objectclass=*)'

bin/ejbca.sh ra addendentity ldap foo123 "C=SE,O=Foo,CN=ldap" null ManagementCA null 1 PEM SERVER
bin/ejbca.sh ra setclearpwd ldap foo123

bin/ejbca.sh batch

# Use SSL
TLSCipherSuite HIGH:MEDIUM:+SSLv3
TLSCertificateFile /etc/ldap/ldap.pem
TLSCertificateKeyFile /etc/ldap/ldap-Key.pem
TLSCACertificateFile /etc/ldap/ldap-CA.pem

./slapd -h "ldap:/// ldaps:///"

OPENLDAP_START_LDAPS="yes"

SuSEconfig

rcldap start

bin/ejbca.sh ca getcacert MyCA myca.der -der

keytool -import -trustcacert -alias MyCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file myca.der

- sudo apt-get install slapd ldap-utils
- sudo dpkg-reconfigure slapd
  Configure slapd with your domain and admin password (primekey.com in this case).
- sudo /etc/init.d/slapd restart
- 'ps -ef|grep slap' 
  should show a slapd running
- ldapsearch -x -b 'dc=primekey,dc=se' '(objectclass=*)'
  To look at the results
- slapcat -l backup.ldif
  Make backup
- slapadd -l backup.ldif
- /etc/init.d/slapd restart
  Restore backup

- ldapadd -x -D "cn=admin,dc=PrimeKey,dc=com" -W -f primekey.ldif
  where primekey.ldif is:

dn: dc=PrimeKey,dc=com
dc: PrimeKey
objectclass: dcObject
objectclass: organization
o: PrimeKey Solutions AB
description: Parent Object for PrimeKey LDAP Directory

dn: ou=Standard,dc=PrimeKey,dc=com
ou: Standard
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all Standard Certificates

dn: ou=High,dc=PrimeKey,dc=com
ou: High
objectClass: top
objectClass: organizationalUnit
description: Parent Object for all High Certificates

OpenDJ

OpenDJ is a modern, standards compliant, java based, LDAP server that is easy to set up and use. It also comes with GUI tools to manage and query.

The graphical LDAP browser is accessible from the Control Panel->Manage Entries. You can start/stop OpenDJ from within the Control Panel or with bin/start-ds and stop-ds.

Management tasks such as creating new attributes and object types are easy to do in the Control Panel GUI.

OpenDJ listens to port 1389 by default, but it also occupies other ports stopping it from running on the same server as JBoss.
If you want to change the management port (default 4444) after installation you can edit confif/config.ldif and config/tools.properties.

Custom schemas

See doc/ldapschema for files with custom schemas and attribute types to add to your LDAP schema.

Custom publishers

# Example file. Should be named META-INF/services/org.ejbca.core.model.ca.publisher.ICustomPublisher
com.example.ejbca.MyCustomPublisher
com.example.ejbca.AnotherCustomPublisher

#!/usr/bin/env bash

echo $* >> /home/user/publisherlog.txt

cp $1 /home/user/cert.crt

outputfolder=/tmp/sampledcertificates/
default.samplingmethod=SAMPLE_ALL
profileid.2234644354.samplingmethod=SAMPLE_NONE
profileid.1645141026.samplingmethod=SAMPLE_PROBABILISTIC
profileid.1645141026.pvalue=0.25

hostnames=localhost
port=1636
basedn=dc=example,dc=com
logindn=cn=Directory Manager
loginpassword=foo123
usessl=true

# Optional properties:
logconnectiontests=true
connectiontimeout=5000
readtimeout=30000
storetimeout=60000

{                                                                       
	"status": "revoked",                                              
	"revocationReason": "keyComprimise",                             
	"pem": "-----BEGIN CERTIFICATE-----\n                             
	MIIDWTCCAkGgAwIBAgIIAZmQ+6dVVfgwDQYJKoZIhvcNAQEFBQAwOzEVMBMGA1UE\n
	AwwMTWFuYWdlbWVudENBMRUwEwYDVQQKDAxFSkJDQSBTYW1wbGUxCzAJBgNVBAYT\n
    	AlNFMB4XDTE0MDMwNDEwNTEyM1oXDTE2MDMwMzEwNTEyM1owETEPMA0GA1UEAwwG\n
	c3NsZm9vMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2nqbOm3ocTTm\n
    	jU49UgP7ugnhg427zHaPdJjWuMt1ZopVzF/46EEsHIfxyGL59J3otgMEXXBJgJwC\n
    	QuZgtqfByAgKIWvrgcxBhvkCe6NRjNAJv0DPaxsEJRqpQEFxV3Eo24eOpN+mxWIm\n
    	6h3N3vTgaaDBQTQMvcb3MndJDWte4+HoBwMtuJdfRapIjcCIkyfiNJKkS4NMvYGw\n
    	G+lrReq4Za0Qhyqejjf4BB+QdE7xetZAtck9HAUlM28/zUuilPNeyftK7lR1Qcyp\n
    	MxIYo6YI2mDbSDre7pr21srZB5lBdOP3dAb5B5MFZ7d4qqljygEb0HuUXedqu4pj\n
    	8e4VNtv7EwIDAQABo4GKMIGHMB0GA1UdDgQWBBR3QlV5l7AvnfNN7D6sILhjMNHs\n
    	LTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFMIAelgt0T0LdOBNNFKBKb5rcu4V\n
    	MA4GA1UdDwEB/wQEAwIF4DAnBgNVHSUEIDAeBggrBgEFBQcDAQYIKwYBBQUHAwIG\n
    	CCsGAQUFBwMEMA0GCSqGSIb3DQEBBQUAA4IBAQADfEI0DgJVBHe63YCC8AhLo+VX\n
    	Fudi97WmCJGfHMx42HaaQvHtIvvpCw8TUZ08k49gUv+qtRlznaKFQb02DjbWgyeY\n
    	TKuCwueiXhMIb7i4Af1+cMFrajBGOYrjYkbGGOwfyN8KcOrQxQk30vBf47DGRtX8\n
    	80fV12f1NWng1KD3ye7VcTnFQTkbwvZAT2aDQorqND8c7Pn8dEpPNnpP67EsLIvH\n
    	biLb4qeaMa0pr21cE2LMV7ZhdyNbziiITB2oNsrdLIcKeTGKqmGSLDec6N0DPnmb\n
    	NlJNaBcs77G2JSJfh908HEtaVqH+u5cKElV3pRSBbS9Z6DcAlwaC64G6tKs0\n    
    	-----END CERTIFICATE-----"                                        
}

{                                                                       
	"error": "An error message from the server.",                                              
}

Publisher Queue and failures

To achieve robust publishing there is a publisher queue. When a publisher fails the published data is stored in a separate table in the database, the PublisherQueueData. This queue can then be processed by a service (see Publisher Queue Process Service in the Services section).

Publishers can also be configured not to publish directly at all, but to store everything in the queue, which is later processed. The benefit of this approach is that publishing is instant. When issuing certificates the CA does not have to wait for all publishers to finish. If there are many publishers this might delay the issuing process slightly.

Publisher Settings:

• 'Current length' - displays the number of new entries in the queue in the intervals <1 min, 1-10 min, 10-60 min and >60 min.
• 'No direct publishing, only use queue' - when enabled, the publisher does not try to publish directly but instead pushes the update to the queue for later processing by a Publish Queue Process Service.
• 'Keep successfully published items in database' - when enabled items stored in the publisher queue will not be removed when real publishing has been done, status will merely be changed from PENDING to SUCCESS.
• 'Use queue for CRLs' - determines if the publisher queue should handle CRLs or not for this publisher.
• 'Use queue for certificates' - determines if the publisher queue should handle certificates or not for this publisher.

Adding a new language to the admin GUI

Java uses unicode internally, so the things that needs to be taken care of are:

1. Make sure your system locale is set correctly, so Java will recognize input of your nations language. If Java does not automatically recognize your locale you might need to specify it as options to Java during startup (i.e. in JBoss and cmd line commands such as ejbca.sh). java -Duser.language=2-char-language-code -Duser.region=2-char-country-code example for Swedish: java -Duser.language=sv -Duser.region=SE
2. Your database must also recognize the locale so it does not strip down to plain ascii. This is database and JDBC-driver dependent.

The Admin GUI is meant to support multiple languages through language files in modules/admin-gui/resources/languages. In order to add a language you should do the following:

1. Rename the language file you have created to languagefile.languagecode.properties, where languagecode is the 2-letter language code (ISO 639-1), e.g. 'zh' for Chinese, and place it in the 'modules/admin-gui/resources/languages' directory.
2. Edit conf/web.properties (create with conf/web.properties.sample as template if you don't have one). Change 'web.availablelanguages' and add your language code to the value. i.e.: web.availablelanguages=en,bs,de,es,fr,it,ja,pt,sv,uk,zh,vi
3. You may have to change the default page encoding in 'web.contentencoding' to for example ISO-8859-1 instead of the default UTF-8.
4. Clean and re-deploy ejbca with 'ant clean' followed by 'ant deploy'. Restart JBoss and your browser after this.

Now it should be possible to select 'zh' in the system configuration as default language and in the administrator preferences page. The language will be changed when the administrator go to a web page.

Internal Internationalization

It's also possible to translate internal log comments, some exception messages and approval notifications. This is done separately in it's own resource files since this is done internally in the core application and not in the web-layer.

The language used internally is configured in the conf/cesecore.properties file by setting the properties intresources.preferredlanguage and intresources.secondarylanguage to the language you want to use. The letters should be the same as the xx name in the intresources.xx.properties files in the src/intresources directory. The secondary resource file is used if the resource isn't found in the preferred language. This is a global setting that cannot be overridden by administrators own settings in the web-layer.

altNames

Adding custom OIDs in altNames works the same way as for DN. When a custom OID is used the altName string in the database will be for example "rfc822Name=foo@bar.com, 1.1.1.1=foobar".
A Custom OID is always added as OtherName using a simple UTF8String. See RFC3280 for definition of the OtherName altName.
The OtherName consists of:

• The custom oid
• An UTF8String with the value

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");
    }
}

Removing an Extended Key Usage

When removing an extended key usage from the list of available usages in the 'Extended Key Usages' tab in the 'System Configuration' page, if that usage is actually in use in a certificate profile, it is not automatically removed from that certificate profile and has to be removed manually by unselecting it from the list of 'Extended Key Usage' in the 'Edit Certificate Profile' page. If not unselected in the certificate profile, the removed extension will still be a part of any certificate issued after the removal but will only be displayed as an OID in the 'Edit Certificate Profile' page.

Also when removing an extended key usage that is in use, a warning message will be displayed listing the certificate profiles that are still using it.

Security Audit log vs System log

A PKI system have three different type of log:

• Security Audit Log - Use for PKI auditors to audit important security PKI events that the system performed.
• System Log - Used to monitor daily operations in the system, debug and track down errors etc.
• Transaction Log - Used for accounting of specific functions, mainly validation (OCSP).

The Security Audit Log is specified in detail what it does log, and it does not log other things. The Security Audit log logs important events such as "Certificate issued", "Certificate Profile edited", "Administrator accessed resource". One of the most important aspects to consider is that the Security Audit log does not log things that do not happen. Things that do not happen are for example invalid requests that the system rejects, becuase the PKI system did not perform any important auditable event.

The System Log logs all events that are interesting to monitor, such as rejecting invalid requests, reading profiles etc.

The main purpose of the Security Audit Log is to provide information to an auditor, and the auditor wants to know what the system has done, what certificates were issued etc, but is not so interested in what the system did not do.

The Security Audit Log is stored in the database and the System Log is stored in log files. By default the System Log also contains the Security Audit Log, but this can be configured.

The OCSP Transaction Log is described in the OCSP install guide. The WS Transaction Log is described in Web Service chapter.

Security Audit Log

The are two different logging devices available for official security audit events (creation of certificate etc). What log devices to use, can be configured in conf/cesecore.properties.

These devices should not be confused with the info/debug output that is sent to Log4J directly. You can find more information on how to configure Log4J in doc/howto/log4j.txt.

It is recommended to only allow new log-posts to the database-tables. More information on this can be found in doc/howto/HOWTO-database.txt.

... INFO  [Log4jDevice] 2015-03-20 12:47:51+01:00;EJBCA_STARTING;SUCCESS;SERVICE;EJBCA;StartServicesServlet.init;;hostname;;msg=Init, EJBCA 6.3.1Alpha (working copy) startup.

mysql> select * from AuditRecordData where eventType='EJBCA_STARTING' ... \G
               pk: 24861ebf7f00010106e5a024d82c694d
additionalDetails: ...  Init, EJBCA 6.3.1Alpha (working copy) startup.  ...
        authToken: StartServicesServlet.init
         customId: NULL
      eventStatus: SUCCESS
        eventType: EJBCA_STARTING
           module: SERVICE
           nodeId: hostname
    rowProtection: 1:2:123:4d2f6...
       rowVersion: 0
    searchDetail1: hostname
    searchDetail2: NULL
   sequenceNumber: 17640195
          service: EJBCA
        timeStamp: 1426205614754

System Log

The system log is logged using Log4J, and has several different levels of log. You can configure which log level is actually logged.

• ERROR - Errors that should cause the IT staff to look into the system. It could be fatal so the system stopped working.
• WARNING - Warnings about misconfiguration. The system is still working, but functionality could be degraded.
• INFO - Informational messages that are interesting for monitoring purposes and statistic purposes.
• DEBUG - Debug information useful to see details of what is happening in the system.
• TRACE - Trace information that can be useful to track down bugs or small missconfigurations. Very rich output showing detailed trace of what happpens in the system code.

Configuration of the System log depends on what application server you are using. See the installation section for information about your application server. The recommended place to configure logging is in the application server, i.e. JBoss. You can configure logging very advanced.

In JBoss you can easily enable and disable DEBUG logging, and switch back to INFO logging at runtime. The first time you want to configure DEBUG log level you can run the following JBoss CLI commands:

/subsystem=logging/logger=org.ejbca:add
/subsystem=logging/logger=org.cesecore:add
/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG)
/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)

You can later switch between DEBUG and INFO logging in runtime, for example to set back INFO logging (normal production level):

/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=INFO)
/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=INFO) 

In JBoss 7/EAP6/WildFly10, if you configure the logging section of standalone.xml.

For example, you can make a more advanced logger, logging EJBCA events to a separate ejbca.log log file that rotates by size every 32MB, and keep maximum 31 rotated log files

<subsystem xmlns="urn:jboss:domain:logging:3.0">
    <console-handler name="CONSOLE">
        <level name="INFO"/>
        <formatter>
            <named-formatter name="COLOR-PATTERN"/>
        </formatter>
    </console-handler>
    <periodic-rotating-file-handler name="FILE" autoflush="true">
        <formatter>
            <named-formatter name="PATTERN"/>
        </formatter>
        <file relative-to="jboss.server.log.dir" path="server.log"/>
        <suffix value=".yyyy-MM-dd"/>
        <append value="true"/>
    </periodic-rotating-file-handler>
    <size-rotating-file-handler name="EJBCAFILE" autoflush="true">
        <formatter>
            <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
        </formatter>
        <file relative-to="jboss.server.log.dir" path="ejbca.log"/>
        <rotate-size value="32M"/>
        <max-backup-index value="31"/>
        <append value="true"/>
    </size-rotating-file-handler>
    <logger category="com.arjuna">
        <level name="WARN"/>
    </logger>
    <logger category="org.jboss.as.config">
        <level name="DEBUG"/>
    </logger>
    <logger category="sun.rmi">
        <level name="WARN"/>
    </logger>
    <logger category="org.ejbca">
        <level name="DEBUG"/>
        <handlers>
            <handler name="EJBCAFILE"/>
        </handlers>
    </logger>
    <logger category="org.cesecore">
        <level name="DEBUG"/>
        <handlers>
            <handler name="EJBCAFILE"/>
        </handlers>
    </logger>
    <root-logger>
        <level name="INFO"/>
        <handlers>
            <handler name="CONSOLE"/>
            <handler name="FILE"/>
        </handlers>
    </root-logger>
    <formatter name="PATTERN">
        <pattern-formatter pattern="%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"/>
    </formatter>
    <formatter name="COLOR-PATTERN">
        <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"/>
    </formatter>
</subsystem>

Log Signing

There are many ways to fulfil requirements on log signing, aka signed log files.

• The built in EJBCA Database Integrity Protection.
• Sign logs with external tools as they are being rotated.

Exporting Audit Logs

All installations have their specific requirements how audit logs should be handled. There are several ways to Export Audit Logs.

• Rotate system log files (including the audit log) and archive/process the rotated log files
• Use a SYSLOG appended to send the System log (including the Audit log) to a central log server that performs monitoring functions
• Export the database audit log using the Local Database CLI
• Export the database audit log using database tools
• Export a specific view from the View Log page in Admin GUI to an XML file
• Export a specific view from the View Log page in Admin GUI to a signed CMS (Cryptographic Message Syntax)

Log Monitoring

When monitoring logs from EJBCA the common trigger to monitor for are ERROR events in the System Log. Example where there is a error to initialize an (this is a specific example and not applicable to all HSMs) HSM during startup:

10:46:53,099 ERROR [org.cesecore.keys.token.p11.Pkcs11Wrapper] (default task-9) Wrong arguments were passed to sun.security.pkcs11.wrapper.PKCS11.CK_C_INITIALIZE_ARGS.getInstance threw an exception

An error event like this should trigger an operator to take a look at the system to gauge what is wrong.

Client Toolbox

ClientToolBox is a set of tools that are built as a stand alone package, which can be put on any machine and run independently of EJBCA. If contains among other things a very rich Web Service CLI.

Local Command line interface

The local CLI can be run directly on the CA machine, and contains many functions that can be used in scripts, or come to rescue when your admin certificate has expired or you have accidentally revoked your admin privileges for the admin GUI.

EJBCA have command line interfaces (CLI) to both the CA and RA, and some other operations.

The best documentation for the cli can be found by running it. bin/ejbca.sh bin/ejbca.sh ca bin/ejbca.sh ra ... this will give a list of all available cli commands. To find out which options are available for a specific command, simply run the command with no options: bin/ejbca.sh ra addendentity This will give documentation about available options. To access the usage information for some commands, that does not take parameters, the option '-?' can normally be provided.

-u <username> -p

-u <username> --clipassword=<password>

-u <username> --clipassword=file:<filename>

bin/ejbca.sh ca listcas -u ejbca --clipassword=file:/tmp/pwd.txt

bin/ejbca.sh clearcache -all

Local Database CLI (EJBCA Enterprise only)

You can build and run the local database CLI with the commands:

ant ejbca-db-cli
cd dist/ejbca-db-cli
./run.sh

The cli contains command that directly accesses a database, export, import, copy, verify audit log and OCSP monitoring. Run the command to get a description about all available commands.

To verify database protection just make sure that you have conf/databaseprotection.properties configured. If you are using database protection for your CA, you can use the same file. For verification, you can also use a verification token, without the private key, so you can do verification on another host from the CA. The file conf/databaseprotection.properties.sample provide example configuration and documentation for the various options.

You can also use the DB tool to create databaseprotection in case you started off not enabling it, and want to enable it later.

• Shut down EJBCA
• Configure databaseprotection.properties and build ejbca-db-cli (so the propereties file is included in dist/ejbca-db-cli/conf)
• Export the database with db-cli
• Drop the database
• Import the database with db-cli

Validation/Conformance Check Tool (EJBCA Enterprise only)

The Validation/Conformance Tool is a tool for running tests on issued certificates or OCSP responses to see that they match the configured criteria.

Other Configuration

To change ports (default public http=8080, public https=8442, private https=8443) you must edit conf/web.properties. Change the properties httpserver.pubhttp, httpserver.pubhttps and httpserver.privhttps. After making the change, run 'ant deploy', 'ant web-configure', and re-start the application server.

Asn1Dump

You can make an asn1 dump of a certificate in order to study the asn1 produced:

bin/ejbca.sh asn1dump <filename-of-pem-encoded-certs or filename-of-der-encoded-asn1>
Ex: bin/ejbca.sh asn1dump managementca.pem

Batch creation of certificates

Certificates can be created batch-wise with EJBCA. The class org.ejbca.ui.cli.batch.BatchMakeP12 creates keystore files for all users designated as NEW or FAILED in the local RA database. To be able to batch generate certificates, the users must be registered with clear text passwords. To set a clear text password for a user use

bin/ejbca.sh ra setclearpwd username password
bin/ejbca.sh ra setendentitystatus username 10

The same is accomplished in the Admin-GUI by checking the checkbox 'Batch generation' when adding the user.

To generate keystore files for all users with status NEW or FAILED, run

bin/ejbca.sh batch 

This will generate files for users if their clear text passwords are NOT null.

Without arguments 'batch' generates keystore files for all NEW or FAILED users. To generate a keystore file for a specific user, enter command

bin/ejbca.sh batch username

Generated keystore files are stored in a subdirectory (to the current directory) called 'p12'. If the directory does not exist, it will be created. Make sure this directory is WELL protected, since the information contained in keystore files are secret (private keys). The format of keystores generated, PKCS12, JKS or PEM, is defined when adding the user in the database (using 'bin/ejbca.sh ra addendentity' or the admin-GUI).

Fetching certificates and CRLs

Certificates and CRLs can be fetched through the public web-interface. They can also be fetched directly from the 'CertificateStoreSession' session bean or using the command 'bin/ejbca.sh ca getcrl'

Other deployment scenarios

EJBCA can be run with servlets and EJBs or only with EJBs. The servlets are only a publicly available front-end to the beans. If the CA is deployed integrated in another JEE application, this front-end may not be needed.

Handling changes in a separate tree (EJBCA >= 3.5)

You can keep your personal modifications of EJBCA in a separate tree. 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/

Please note that

• 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

Adding your own public web-pages

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

Plug-in interfaces

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

• Publishers.
• Services.
• External User Data Sources.
• Custom Certificate Extensions.
• Custom email notification recipients.

And of course, 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.

EJBCA plugin 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 plugin scheme which provides custom applications with the core EJBCA environment data. In the directory src/samples/plugins you will find a couple of complete demo plugins 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 plugins.

Plugins 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.

General Performance Tips

Normally in a PKI extreme performance is not really an issue. A default installation of EJBCA can easily issue tenths of certificates per second, which is more than enough even for very large installations. For OCSP it is more important, but OCSP is also more light weight so the default performance there is hundreds of requests per second.

In more specialized PKI installations there can however be the need to issue hundreds of certificates per second. Therefore we provide a small list of configuration items that can maximize performance of EJBCA to issue more than 100 certificates per second (depending on hardware etc).

• Enable database indexes, see doc/sql-scripts.
• Disable logging to database in cesecore.properties, only use Log4jLogDevice. This removes a database insert and gives a big boost.
• Configure Log4j to log only to file, not console, and use only INFO or ERROR logging, not DEBUG. This can give a small improvement.
• Disable use of CertReqHistory in CA configuration. This removes a database insert and gives a big boost.
• Disable finishUser in CA configuration. Verify that this is ok first by reading the documentation for this feature. This can save a database read and update.
• Enable all caches in cache.properties. If you cache indefinately you can use the cli command 'bin/ejbca.sh clearcache' if configuration changes are made. This can give a small improvement. See also info about the clear all caches button.
• Do not enforce any uniqueness (keys, DN, Subject DN SerialNumber) in CA configuration. This will ensure no extra selects are made and can give a small improvement.
• Minimize the number of indexes in the database, only use the ones that are absolutely needed. This makes inserts in the database a bit faster and can give additonal 10%.
• Use the native JBoss connectors for http and https. This can give an additional 10%.
• If you have a lot of certificates (>100M) it might be a good idea to use a separate table for the storage of the encoded certificates. See the database.useSeparateCertificateTable property in ./conf/database.properties.sample

Throw away CA

EJBCA can be configured to function as a Throw Away CA. In this mode EJBCA simply functions as a high speed certificate factory, issuing certificates but not storing any trace of them in the local database.

Using EJBCA in Throw Away CA-mode curtails some functionality, foremost the following:

• You can not search for issued certificates.
• You can not revoke certificates, and thus not use CRLs or OCSP.
• You can not enable some limitations such as Enforce unique DN or Enforce unique public keys.

If these limitations are acceptable you can gain some benefits by using Throw Away CA-mode:

• Maximum performance since no database queries are done. Enable to maximum caching and EJBCA will not make a single call to the database.
• Minimal storage requirements. Since no issued certificates are stored in the database only EJBCA configuration needs storage.

Limiting Database Query Size

Certain types of queries can, whether intentionally or not, generate massive amounts of results. In order to not clog up the database driver, EJBCA has a default maximum value of 500 results for certain tables, which affects the following data sets:

• Certificates
• End Entities
• Hard Token Usernames

Should one want to lower or raise the query limit, one may do so under System Configuration. For safety, there is still a hard upper limit of 25,000 entries.

Limiting Database Query Timeout

Certain types of searches can, whether intentionally or not, generate database heavy queries (even full table scans). In order to not overload the database, EJBCA will try to limit for how long a query is allowed to run for certain searches before aborting. For such limitations to work, both you database and Java DataBase Connector (JDBC) driver must support this. This setting currently affects the following searches:

• RA GUI Search for certificates
• RA GUI Search for end entities

Should one want to lower or raise the default of 10000 ms (10 seconds) in the query timeout, one may do so under System Configuration. Setting the value to 0 mean that EJBCA will not try to enforce any query timeout and it will default to you appliaction server and database configuration.