User Guide

Administrative tutorials

There are additional documentation and administrative tutorial movies at http://wiki.ejbca.org/.

Administrating EJBCA

You can administer EJBCA using a web browser and the admin-GUI, this is the easiest way. The admin-GUI requires SSL with authentication using client certificate, i.e. strong authentication.

You can also use the command line interface (cli) which is called by 'bin/ejbca.sh'. If you call ejbca.sh you get a list of available commands, and you can get help for all commands by calling them without arguments, i.e:

bin/ejbca.sh ca
bin/ejbca.sh ra adduser
etc etc

EJBCA client toolbox

There are also a set of different tools that could be used without an EJBCA.

Build these tools with:

ant clientToolBox

The directory './clientToolBox-dist' is then created. You may then move this directory to any location.

To use any of the tools just call 'ejbcaClientToolBox.sh' in this directory. You may call the script from any location.

If you put the directory in your PATH then you just have to write 'ejbcaClientToolBox.sh' to call it.

If you call the script without any arguments you get a list of all valid first arguments which specifies the tool to use. Example:

ejbcaClientToolBox.sh

Then just one argument gives help about the specified tool. Example:

ejbcaClientToolBox.sh ocsp

Backup and restore of EJBCA

To backup an EJBCA installation you need to:

• Backup the database
• Backup all $EJBCA_HOME/conf/**
• Backup all $EJBCA_HOME/p12/**

• Restore database
• Unzip new EJBCA
• Restore conf and p12
• Run "ant deploy" to configure JBoss and deploy EJBCA. If you are using another application server, consult the Installation doc for deployment.

If you are using soft keystores for the CAs this is all that is needed. If you are using an HSM you need to backup your keys in the HSM as well. How this backup and restore is done depends on the HSM you are using. Consult the documentation for your HSM.

SSL certificate expire

The SSL certificate used for SSL in JBoss (SSL is used for the admin-GUI) is stored in APPSRV_HOME/server/default/conf/keystore.jks. The default validity time for the SSL certificate is two years. When this expire, you must generate a new one.

You can do this through the admin-GUI by:

1. Go to 'List/Edit End Entities' and search for user 'tomcat'.
2. 'Edit_End_Entity' and set the 'Password' to the same as httpsserver.password in your conf/ejbca.properties and 'Status' to 'New'.
3. Open up a command line in EJBCA_HOME and run 'bin/ejbca.sh batch'.
4. Copy EJBCA_HOME/p12/tomcat.jks to APPSRV_HOME/server/default/conf/keystore.jks, or run 'ant deploy'. Ant deploy will do some other things as well, so if you are not sure, just copy the file.
5. Restart JBoss.

You can also do everything using the CLI:

1. bin/ejbca.sh ra setuserstatus tomcat 10
2. bin/ejbca.sh ra setclearpwd tomcat <password from httpsserver.password>
3. bin/ejbca.sh batch
4. cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
5. Restart JBoss.

Creating more CAs

After installation, that creates a default admin CA you can create more CAs using the admin GUI.

Your CAs can be either root CAs, subordinate CAs to another CA in EJBCA or subordinate CAs to an external CA. The initial admin CA is a RootCA.

You can also use the command line interface (cli) 'bin/ejbca.sh ca init' to create new CAs, although a better idea is to do it from the Admin GUI. Ex: 'bin/ejbca.sh ca init TestRoot "C=SE,O=PrimeKey,CN=EJBCA" 2048 365 2.5.29.32.0' will create a root CA with the DN 'C=SE,O=PrimeKey,CN=EJBCA'. The keylength is 2048 bit (RSA) and the validity of the root certificate is 365 days. Quote the DN so it is treated as one argument.

PKIX requires that a CRL always is available even if it is empty. When creating a new CA the CA certificate is stored and published (if any Publishers are configured), and the initial CRL is created and stored/published.

Subordinate CAs are created using the admin GUI, you can not use the cli for that.

Creating a SubCA signed by an external CA

Some CA hierarchies have the requirement of being signed by an external Certificate Authorities and sometimes other external CA:s need to be signed by your CA.

When creating a CA that is signed by an external CA, you actually create a PKCS10 certificate request that is sent to the external CA. When the external CA returns your CAs certificate, this is processed and the CA becomes activated.

In order to have your CA signed by an external CA you have to go through the following steps.

1. Go the the 'Edit Certificate Authorities' page in the Administration GUI.
2. Create a new CA in the same way as internal CA:s. But when selecting signing CA, select 'External CA' instead. Now will the 'Certificate Profile', 'Validity', 'Subject Alternative Name' and 'Policy Id' fields become gray and not editable. Fill in the Description and CRL Specific data and click on the 'Make Certificate Request' button in the bottom of the page.
3. At the next page called 'Make Certificate Request' you can upload the external CA certificate chain that you want to sign your CA certificate with, or you can wait until later by checking 'No CA chain file available'. This file should be in PEM encoding. If there is more than one top CA certificate then should all their certificates be appended into one single file. It should be in plain PEM format without blank lines before or after. An example is below.
4. Next, after clicking 'Make Certificate Request' and if everything went successful, should the generated PKCS10 certificate request be displayed that you can copy and paste to the signing CA. There is also the option to download the PEM file if that approach is preferred.
5. Now should the signing external CA sign the certificate request and return a certificate. Meanwhile will the newly created CA have a status of 'Waiting for Certificate Response' and will not appear anywhere in the system except in the 'Edit CA' page until it's activated.
6. When the Certificate Response has arrived, it is time to activate the new CA. You mark the waiting CA and click on 'Edit' button in the 'Edit CA' page. Go to the bottom of the page and click on 'Receive Certificate Response'. Then upload the received certificate and click again on 'Receive Certificate Response'.
7. Now if the received certificate creates a valid certificate chain with the previously uploaded top CA certificates will the status of the CA be set to 'Active'.
8. If you did no upload a certificate chain when the request was created, you can do so now by uploading the complete PEM formatted chain now. The CAs own certificate should be first in the file, followed by the issuing CAs certificate(s). When uploading a chain, the certificates must be converted to PEM format if it isn't already so. This can be accomplished with OpenSSL among other tools with the following command if you have received a file in DER encoding (.cer ending):
   >openssl x509 -inform DER -in filename.cer -outform PEM -out filename.pem
9. Observe if you want to activate OCSP functionality for this new CA you have to edit it once again and mark the OCSP functionality as active.
10. The new externally signed CA is ready to use.

Example of a plain PEM file for uploading as a certificate chain:

-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIIEvabM2CgLZcwDQYJKoZIhvcNAQEFBQAwMzETMBEGA1UE
AxMKV2FsdGVyIENBMTEPMA0GA1UEChMGV2FsdGVyMQswCQYDVQQGEwJTRTAeFw0w
MzA5MjkwOTI2MzRaFw0wNDA5MjgwOTM2MzRaMDMxEzARBgNVBAMTCldhbHRlciBD
QTExDzANBgNVBAoTBldhbHRlcjELMAkGA1UEBhMCU0UwggEgMA0GCSqGSIb3DQEB
AQUAA4IBDQAwggEIAoIBAQC3hXksEud68WwPWWHLJQQkTCuX/K32KHPPn/uPUzab
Cpc/FnaTmF9yEHmpFdAUr0v5ZPnxVQpcuwrDZc4YfaTLfyUHicQbkftsPAj/2hE4
UukS2j+nQQcJEnIY0vSZOAOLU3j4bf/RlS6Jl7TPFFfWTxuQF8AruQ+YhaE52JFi
SapGGXKQJxhsvKT91rLaWSFWNMTTLSDPaBXYEYFuFhLNclDJWf4whfxHSHHkARB/
3Z0XlT4sFj0fmqEQ6yQb6/WqMFK+1XAIBXZO2MXe26IigWkXw1GfkIx1+fbUPrzu
8EI2jb0TWl21j1+Mvh3APZtVj5FJNuZN9bgdbrq88hLXAgERo2QwYjAPBgNVHRMB
Af8EBTADAQH/MA8GA1UdDwEB/wQFAwMHBgAwHQYDVR0OBBYEFNhHOtAwo8MOE/nI
zzg9KFxCYs8YMB8GA1UdIwQYMBaAFNhHOtAwo8MOE/nIzzg9KFxCYs8YMA0GCSqG
Sib3DQEBBQUAA4IBAQBHpvicbuJTACtpdwe6cF1nQ57FHnnYr+aAe+ZpH43R6R9d
eMps02nFAMSs5o8sbPokrpwAtk2yYwCohEFDkZ5JPzIBkgNlNnVHNNRHQTRJ6v6Q
F2MWUEPc1u5kxSjXEVMmZerG9oknMwpYFmkOnKF46vP3Njt/ExOeRAvCEQq2b8pz
2QGg8/IK6Omfi7IwxtVYUpgvhdcWekbFIlxkXZiEdlHNBIV1GzzPK1VEzg5kugD/
h6jeykrsKASx+55AkkBPt2kI+ZikVtp3SVhfZQMGY86c5QMQGlPWYNsr4ociyhfX
I52Qby+/HNG1ijpx66Z30lUMmXTtWtL4Cu8s7UvC
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICxzCCAa+gAwIBAgIIBfqGjbQu14swDQYJKoZIhvcNAQEFBQAwMzETMBEGA1UE
AxMKV2FsdGVyIENBMTEPMA0GA1UEChMGV2FsdGVyMQswCQYDVQQGEwJTRTAeFw0w
MzA5MjkwOTMzMDFaFw0wNDAxMDcwOTQzMDFaMDQxETAPBgNVBAMTCER1ZGUgQ0Ex
MRIwEAYDVQQKEwlEdWRlIEluYy4xCzAJBgNVBAYTAlNFMIGdMA0GCSqGSIb3DQEB
AQUAA4GLADCBhwKBgQCM1hR/DYPXfKDa3oVJbppV4OcYtn2XP9W5Kc1d0+U4qLOm
JsqIFHDWR07o1QFiPhc9z0UGtwYeE3CpQ8fG8zeur5e286PYptZIST77B9vOdQdl
PA+dFKFIaEwdzcS7H3Lf38WTE4D1OnyRX5jsiUe+YIQRtjv/Bmem+kSR84G9TwIB
EaNkMGIwDwYDVR0TAQH/BAUwAwEB/zAPBgNVHQ8BAf8EBQMDBwYAMB0GA1UdDgQW
BBTDrXZGYXS9GyIUBOZrglhwNjjcnTAfBgNVHSMEGDAWgBTYRzrQMKPDDhP5yM84
PshcQmLPGDANBgkqhkiG9w0BAQUFAAOCAQEAdmTP1qVUcAKOf+/zvb2lcLKvFwKT
6KqDlO5NofjqCIfNgCjO2mO176cslnFIbEZQqgGIUnJ3AwfHKHj+U3kM3n5T29kF
xiLKxIDfjsY6qC03KHeGAgxI92XZyPsO1is6Y6qUnAmiwhIp5HS6E0+xIP1shmtJ
ZvqU8bueKUWSjx3JDzq+UNLX5pFkK0P0R90TCUEkBx1FNWqoWwb8zfAuO5zcNTEj
5E9esLjwxJQnIVPiA2l3FfZN9yomK+q7kTZJkX2kMx7G850lPR8CneXZT6bIOfck
Dw3PqQiroMNx2+gzC/f/wTXsF92aujyG+IZx1FIcNg/MoHXBWG7T8YrjnQ==
-----END CERTIFICATE-----

You can treat an internal CA, i.e. a CA residing on the same EJBCA instance as another CA, as an external CA. From the SubCA this works just like the normal case, but on the RootCA you must choose the exact same CA Name as the already existing internal CA when you choose to "Process Certificate Request".
This can be useful if you have an HSM setup where only one set of keys can be active at one time, for example using nCipher with two different, non-persistence, operator cards sets for the RootCA and the SubCA. Using the SubCA as an external CA you can still create the PKI but with only one CA active at a time.

Signing an External CA

In some cases you might want to have one of your CA:s signing another external CA. This is done in the following way:

1. In the 'Edit CA' page, choose a CA name of the external CA you are about to sign and click on 'Process Certificate Request'.
2. Then you are requested to upload the certificate request sent from the external CA. This should be a file in PEM-encoding.
3. The next step is to fill in the data about the CA certificate you are about to create. This is very similar to when you are creating an internal CA but with a fewer fields. The Subject DN is taken from the request. But the signing CA, certificate profile, validity, subject alt name and policy id have to filled in manually.
4. After clicking 'Process Certificate Request' the certificate is created and displayed in PEM format. You can also download it as a regular PEM file or as a PKCS7 PEM file.
5. Send the processed certificate back to the external CA for activation.
6. In the 'Edit CA' page will the newly processed CA be displayed with the status 'External'. This processed CA will only be shown in the 'Edit CA' pages and nowhere else since the system cannot use it. If you want to view the processed certificate, go to the edit page and click on the 'View CA Certificate' link in the bottom of the page.

Requesting a cross or bridge certificate

If you have set up your own CA you can request another CA to cross certify your CA, or you can get certified by Bridge CA such as the Federal Bridge. This is done in the following way:

1. In the 'Edit CA' page, choose a CA name of the external CA you are about to sign and click on 'Edit'.
2. In the lower part of the screen, click on 'Make Certificate Request'.
3. Now check 'No CA chain file available' and click 'Make Certificate Request'.
4. Save the created PKCS#10 certificate request to disc and send to the other CA.

Now you have a certificate request to send to the other CA or bridge CA. When the other CA have issued a certificate for you, everything is completed. You don't need to (and you can't) import the cross-certificate or bridge-certificate in EJBCA. What you need to do is make sure the clients using the certificates issued by your CA have access to the correct certificate chain. If you are cross-certified with several other CA, multiple possible certificate chains exist.
Handling the certificate chains on clients is out of the scope for EJBCA.

Converting an OpenSSL CA

You can convert a PEM-style Root CA key to a PKCS12 file that can be imported in EJBCA.

openssl pkcs12 -export -out server1.p12 -inkey cakey.pem -in ca.pem -name privateKey

You can import the CA with the Admin GUI or the cli. See the section 'Export and import CAs'.
After importing CAs you can also import users and certificates. See the section 'Import users'.

Creating Users

Users are added in the admin-GUI, 'Add End Entity' or with the cli 'bin/ejbca.sh ra adduser'. The users DN is normally entered in the cli as "C=SE,O=MyOrg,OU=MyOrgUnit,CN=MyName". If a ',' is needed in the DN the comma must be escaped using '\,'.

Create User certificates

To enroll for a certificate using a browser, go to http://your_server_name:servlet_container_port/ejbca/ (e.g. http://127.0.0.1:8080/ejbca/) and select "Create Browser Certificate". Enter username and password, click the "OK"-button and follow the instructions.

To enroll for certificates manually (e.g. for server certificates), go to http://your_server_name:servlet_container_port/ejbca/, select "Create Server Certificate" and fill out the form.

Note that application for certificates only work when the status of a user is NEW, FAILED or INPROCESS (one time password thing). The status is set to GENERATED after a certificate has been issued. To issue a new certificate, the status must be reset to NEW, which can be done through the admin-GUI or the cli.

During batch generation of certificates, users with status NEW or FAILED are generated. This is due to the possibility that a batch generation for some reason failed. If it fails status is set to FAILED and you can try again after fixing the error.

Create server certificates

The best way to create server certificates is to generate a PKCS12, JKS or PEM file for the server, depending on what server it is. To do this:

1. Create desired profiles (the default entity and certificate profiles work fine, but are perhaps too generic). You certificate profile should have:
   - KeyUsage: Digital signature, Key encipherment
   - Extended key usage: Server Authentication
   
2. Create a user with the admin-GUI or 'bin/ejbca.sh ra'.
   The Distinguished name (DN) of the server should have the the servers full hostname (host.domain.com) in the CommonName (CN) field.
   Example DN for webserver: "C=SE,O=AnaTom,CN= www.anatom.se", or for mailserver "C=SE,O=AnaTom,OU=Engineering,CN=mail.anatom.se".
   You can also put the same name (or several names) as a DNSName in SubjectAlternativeNames.
   For so-called wildcard certificates, use *.anatom.se.
   Set the token type to match the kind of token that should be generated for your server.
3. To be able to batch-generate certificates, the batch generation program must have access to the users (servers) password in order to request a certificate on behalf of the user. Normally the password is stored in hashed form, so the password must be stored in clear text form by running 'bin/ejbca.sh ra setclearpwd username password'
4. Generate private keys and certificates by running 'bin/ejbca.sh batch'

Many servers (ex Apache, Tomcat) wants keys and certificates in PEM-format (Apache) or SUN JKS (Tomcat). To generate PEM-files use token type PEM. The PEM-files will be stored in a separate subdirectory, 'pem'. The generated PEM-files can be used with Apache etc, and are NOT protected by any password. To generate JKS-files use token type JKS. The JKS-files will be stored in the subdirectory, 'p12' instead of PKCS12-files. The generated JKS- files can be used with Tomcat etc, and are protected (both private key password and keystore password) by the users password.

If the server generates the keys and a certificate request (CSR) for you, select token type "User generated". You can use the public enrollment web pages (http://127.0.0.1:8080/ejbca/) to paste the request and receive the certificate. This function is under "Certificate Enrollment->manually for a server".

It is also possible to use openssl to transform a PKCS12 file to PEM- format.

openssl pkcs12 -in pkcs12-file -nodes

copy and paste the private key to key file, the first certificate to server cert file and last certificate to CA cert file (If your CA is a subordinate CA to another Root CA, the CA cert file may need to contain the whole cert chain). Exactly how your server wants the files is server dependent.

For your convenience, here is the standard text (RFC2818) how browsers validate the name(s) in the certificate.

If a subjectAltName extension of type dNSName is present, that MUST
be used as the identity. Otherwise, the (most specific) Common Name
field in the Subject field of the certificate MUST be used. Although
the use of the Common Name is existing practice, it is deprecated and
Certification Authorities are encouraged to use the dNSName instead.

Matching is performed using the matching rules specified by
[RFC2459].  If more than one identity of a given type is present in
the certificate (e.g., more than one dNSName name, a match in any one
of the set is considered acceptable.) Names may contain the wildcard
character * which is considered to match any single domain name
component or component fragment. E.g., *.a.com matches foo.a.com but
not bar.foo.a.com. f*.com matches foo.com but not bar.com.

In some cases, the URI is specified as an IP address rather than a
hostname. In this case, the iPAddress subjectAltName must be present
in the certificate and must exactly match the IP in the URI.

Administrators

An EJBCA Administrator is identified by information in the client SSL certificate. The information is validated in the following steps:

1. During the SSL handshake with the application server, the issuer of the client certificate is verified with a list of trusted CA certificates known as the 'truststore'.
2. EJBCA verfies that the client certificate exists in the database and that it's not revoked. (Configurable in web.properties.)
3. EJBCA tries to match the information in the certificate with any of the matching criterias found in the different administrator groups. Matching rules are evaluated separately so matching with both CN and OU would match all CN matched certificates and also all OU matched certificates.
4. If a match is found, the access rules for this group is given to the administrator.

Administrator privileges is configured through "Edit Administrator Privileges" in the Admin GUI or by using the CLI. If you have locked yourself out of the GUI, the CLI can add another admin certificate to allow continued operations.

To use a certificate issued by an external CA as Administrator:

1. Add the CA-certificate to p12/truststore.jks with "keytool -import -trustcacerts -file externalca.pem -keystore p12/truststore.jks -storepass changeit -alias externalca"
2. Redeploy EJBCA (ant deploy) and restart the application server to make sure the new truststore is in use
3. Import the CA-certificate under "Admin GUI - Edit Certificate Authorities - Import CA Certificate.." or use the CLI
4. Add the Administrator to the desired Administrator group under "Admin GUI - Edit Administrator Privileges"

Publish queue status

The publish queue status shows the current number of publish events that is stored in the publisher queue. Events can be stored in the publisher queue either because publishing failed, or because publishing goes to the queue directly.
See also Publisher Queue and failures.

CA Status

The CA status overview shows ok or error if CAs are off line and if CRLs are not valid.
CA Status shows a red error if the CA is not on-line or the CA token is not in line. External CAs are always show as ok.
CRL status show a red error is a CRL or delta CRL has expired without a new one being created. Delta CRLs are only monitored if used.

Validity

The validity determines the validity in days of certificates, from the time the certificate is issued. The field 'notAfter' in the issued certificate will have the value 'now + validity days'.

Allow validity override
The check box 'Allow Validity Override' will make it possible to request a specific notAfter date. This is currently possible when using CMP (the CRMF request format), or when using the API to issue certificates.

The validity of a certificate is determined as follows:

• The Validity field in the profile specifies the maximum allowed validity, which will be the validity if nothing else is specified.
• If 'Allow validity override' is enabled in the profile the profile value can be overridden with:
  • Start and end time specified when adding the end entity, of allowed in the End Entity Profile.
  • Requested validity from the certificate request (CMP for example).

There are some constraints for the validity of a certificate issued by the CA:

• The notAfter time of issued certificates can never be longer than the validity time specified in the certificate profile used.
• The notAfter time of issued certificate can never be longer than the CAs own validity.
• notAfter can never be before nofBefore and vice versa.
• notBefore is normally 10 minutes before the current time, to avoid problems with clocks that are a few minutes out of sync.
• notBefore can be set to any desired value if allow validity override is enabled, except for the limitation with regard to notAfter.
• notAfter can be set to any desired value if allow validity override is enabled, except for the limitation of max and min value specified above.

If the validity is for a CA the certificate profile specifies the maximum validity, but it can be shorter if specified when adding the CA. The validity of the CA can never be longer than the value specified in the profile.

Allow extension override

If extension override is allowed, the X509 certificate extension created in a certificate can come from the request sent by the user. If the request contains an extension than that will be used instead of the one defined in the profile. If the request does not contain an extension, the one defined in the profile will be used.

This option should only be used when you know that the request comes from a very trusted source. Such a trusted source is normally an RA through CMP or webservice.

Currently (EJBCA 3.9) this only works for extensions in CRMF (CMP) requests.

Allow subject DN override

If subject DN override is allowed, the X509 subject DN extension created in a certificate can come directly from the request sent by the user. This is instead of the normal way where the user's registered DN is used.
Using this option certificates with very strange DNs, or with DNs in very specific orders can be created.

This option should only be used when you know that the request comes from a very trusted source. Such a trusted source is normally an RA through CMP or webservice.

Path Length Constraints

Note: this extension is only applicable for immediate CA certificates and it sets how deep the succeeding certificate hierarchy may be. If it is set to 0 this CA certificate is the last CA in a chain and only end entity certificates may follow.
From RFC5280 (4.2.1.9):

The pathLenConstraint field is meaningful only if the cA boolean is asserted and the key usage extension, if present, asserts the
keyCertSign bit (Section 4.2.1.3). In this case, it gives the maximum number of non-self-issued intermediate certificates that may
follow this certificate in a valid certification path. (Note: The last certificate in the certification path is not an intermediate
certificate, and is not included in this limit. Usually, the last certificate is an end entity certificate, but it can be a CA
certificate.) A pathLenConstraint of zero indicates that no non self-issued intermediate CA certificates may follow in a valid
certification path. Where it appears, the pathLenConstraint field MUST be greater than or equal to zero. Where pathLenConstraint does
not appear, no limit is imposed.   

Use LDAP DN order

In a certificate the order of the CN components can be put in different order depending on wich standard you abide to.

• Ldap DN order: CN=Common Name, O=Organization, C=Country
• X.500 DN order: C=Country, O=Organization, CN=Common name

For historical reasons EJBCA uses Ldap DN order. Some applications do require X.500 DN order however and therefore EJBCA gives you the choice. There are two places in EJBCA where this can be configured:

• In the Certificate profile (Edit certificate profiles)
• In the CA configuration (Edit Certificate Authorities)

Extended Key Usage

The meaning of Extended key usage is defined in RFC5280. Normally the values specified in the fixed certificate profiles are good for the usage the fixed profile is for.

You can define your own extended key usages very simple. Edit the file EJBCA_HOME/conf/extendedkeyusage.properties and add your custom extended key usages in the end. Be sure to follow the numbering. After editing the file, simply build and re-deploy EJBCA (ant clean; ant bootstrap).

Cardnumber

Select this if you want to use the SEIS Cardnumber Extension. The card number is a unique identifier stored in the certificate and should also be printed on top of the card on which the certificate is stored. When used, the card number needs to be set for the end entity before creating a certificate. The extension is specified in the the Seis document SS 614331 chapter 4.3 and has OID 1.2.752.34.2.1.

Subject Alternative Names

Subject alternative names (altNames) are extra naming items that are not fit to have in the Distinguished Name, such as email, dns, ip address etc. There are a number of standard ones, and the possibility to define special ones, which many companies have done for altNames such as MS UPN, GUID, Krb5PrincipalName.

Subject alternative names can be: rfc822Name=<email>, dNSName=<host name>, uri=<http://host.com/>, ipaddress=<address>, upn=<MS UPN>, guid=<MS globally unique id>, directoryName=<LDAP escaped DN>, krb5principal=<Krb5 principal name>

192.168.2.54

2001:DB8:85A3:0:0:8A2E:370:7334

user@PRIMEKEY.SE

krbtgt/PRIMEKEY.SE@PRIMEKEY.SE

Certificate Validity

By setting the Certificate Validity Start Time and End Time you can precisely specify, for a specific end entity, when the certificate will start being valid and when the certificate will cease being valid.
When selecting to use Certificate Validity Start or End time you will get the possibility to enter these fields when a new end entity is added. You can also specify a default value for the end entity profile. Different formats of specifying the validity time is provided as examples in the end entity profile page.

Revocation reason to set after certificate issuance

Using this option you can define that when adding a new user, the revocation state of an issued certificate can be set immediately to something else than 'Active'.
Useful if you want to issue certificate that are 'On hold' for users. After the user receives the certificate they might be required to perform some action in order to have their certificate activated.
Most useful when used in combination with OCSP since it will require, in practice, instant revocation checking.

When enabling this option in the profile, a corresponding selection will be available when adding new users. The user data corresponding to this option is an ExtendedInformation attribute, ExtendedInformation.CUSTOM_REVOCATIONREASON.

Reverse Subject DN Alt Name Checks

This checkbox is not recommended to be used in normal operations. When using the External RA and more than one DN field type is set in the profile, for example one optional OU and one required OU, it might be needed to check this checkbox for the profile validation to work.
Only use it in such a special case, if nothing else work. This option may be removed in the future.

Maximum number of failed login attempts

By choosing a maximum number of failed login attempts the status of a user will change to GENERATED in case a wrong password is entered more than the specified number of times. The checkbox "Use" must be checked for the end entities to use this feature. If the checkbox "Modifiable" is checked the specified number can be changed for a particular end entity at the creation time of the end entity or later by editing it.

Creating CAs

Creating CAs can be made using the Admin-GUI or the command line interface. The recommended way is using the Admin-GUI, since it gives more control of all parameters.

You can create CAs using the cli command:

ejbca.sh ca init

Issuing the command will give usage instructions.

Creating CAs in the Admin-GUI is done by selecting 'Edit Certificate Authorities' in the menu, entering a new CA name in the text field and clicking 'Create'.

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.

[user@host ejbca]$ bin/ejbca.sh ca exportca TestCA ./TestCA.p12
Using JBoss JNDI provider...
Enter keystore password: foo123
[user@host ejbca]$ 

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

[user@host ejbca]$ bin/ejbca.sh ca importca

CRL Distribution Points

The CRL Distribution Point (CDP) extension is provided as info for clients verifying a certificate. The value is a URI that points to a CRL that can be used to check if the certificate is revoked. The CRL is issued by the CA. There are different kinds of CRL Distribution Points and currently EJBCA supports a URI.

Note that you are responsible for the order and encoding of your CRLIssuer, if this is important check it!

A CRLDistributionPoint for a CA in EJBCA could look like:

http://host:port/ejbca/publicweb/webdist/certdist?cmd=crl&issuer=url-encoded-issuerDN

(such as the link from the web distribution pages)

• host is the DNS name by which the CA is accessible. Port 8080 is the default port that JBoss listens to, but if you changed the JBoss port, this value should also change.
• url-encoded-issuerDN is the CAs common name as configured when the CA was created. This is the same DN as occurs as Issuer in certificates issued by this CA.

When configuring this extension you should take the URI entered and test it in a normal browser, from another machine than the CA, to see that it works before issuing any certificates.

It should also be possible to use an LDAP distribution point, if you have configued a publisher to publish CRLs to LDAP.

ldap://yourLdapServer:port_number/cn=CA-test,ou=CRLPUB,dc=mycompany,dc=com?certificateRevocationList

When defining CRL distribution point and CRL issuer in a certificate profile, you can choose to set the values in either the certificate profile, or in the CA configuration (edit CAs). By having the setting in the CA configuration it is possible to use the same certificate profile for several CAs, otherwise you would have to create a new certificate profile for all CRL distribution points.
By checking 'Use CA defined CRL Distribution Point' you can configure the CRL distribution point in the edit CA page instead, and use this value in every certificate profile that uses that CA. It is a convenience function, so you don't have to enter the same CDP in all certificate profiles.

It is possible to configure multiple URLs for CDPs if they are separated by ';'. For example:
http://cdpurl-1/mycrl.der;http://cdpurl-2/crl.crl

The same applies to CRLIssuer, for example:
CN=Foo,C=SE;CN=Bar,C=US

CRL Issuer

According to RFC3280 a CRL issuer is:

An optional system to which a CA delegates the publication of certificate revocation lists;

The contents of the field in the profile is a DN, like "CN=CRLIssuerForAdminCA1,O=foo,C=SE". You have to build the actual CRL Issuer software yourself.

CRL Update service worker

From EJBCA 3.4 there is a timed service framework in EJBCA. 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'.
Now this service will run with the interval you have configured and generate CRLs according to the settings for each CA.

JBoss service

DEPRECATED! The JBoss Mbean CRL Service generator has been deprecated.

This service has been removed as of EJBCA 3.6. If you are still using this service, you must create a CRL Update service as described above. It is very simple.

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_01/bin
@daily cd /home/ejbca;/home/ejbca/bin/ejbca.sh ca createcrl;

where '/usr/java/jdk1.4.2_01/bin' is the path to where 'java' can be found. '/home/ejbca' is where ejbca is installed and 'ca.sh' located.

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

a.k.a. Freshest CRL Extension

EJBCA can issue deltaCRLs as well. In the CA configuration, set 'Delta CRL Period' to the number of hours your delta CRLs should be valid if delta CRLs should be issued. Command line interface and CRL Update service will generate delta CRLs if 'Delta CRL Period' is larger than 0.

Level of SCEP support

EJBCA implements features from (at least) draft 11 of the SCEP spec. This means that we implement the following SCEP messages:

• PKCSReq
• GetCRL
• GetCACert
• GetCACertChain
• GetCACaps

• GetCertInitial

• POSTPKIOperation
• SHA-1

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.

Tested devices

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

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

Verbose = "yes"
Debug = "no"

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

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

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

# 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=AdminCA1"
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.se
    UNSTRUCTURED NAME = pix.primekey.se
    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

Configuration

Copy conf/cmp.properties.sample to conf/cmp.properties and configure. The options in the configuration file should be documented there.

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

CMP over TCP

You can enable a CMP TCP service by changing the option 'cmp.tcp.enabled' in conf/cmp.properties. The service MBean is so far JBoss specific (at least the deployment of it).
When re-deploying EJBCA this will start a TCP listener on the default port for CMP over TCP. You must run JBoss 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.

User authentication

Initialization and certification requests uses the CRMF request message (RFC4211). There messages are interesting as there are a zillion options how to authenticate them. EJBCA currently does authentication through the means of a regToken control (id-regCtrl-regToken) in the CRMF message. The regToken is a UTF8String which is the users password as registered in EJBCA.

Users can be looked up from the request in different ways, as configured in conf/cmp.properties. By default the subject DN from the certTemplate in the request is used to look up the used in EJBCA. You can also configure EJBCA to use the CN or the UID from the subject DN as the username in EJBCA.

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 configured so in conf/ejbca.properties 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).

Normal or RA mode for CMP

CMP in EJBCA can work in two modes:

cmp.operationmode=ra
cmp.allowraverifypopo=true
cmp.responseprotection=pbe
cmp.ra.authenticationsecret=password
cmp.ra.namegenerationscheme=DN
cmp.ra.namegenerationparameters=UID
cmp.ra.namegenerationprefix=cmp
#cmp.ra.namegenerationpostfix=
cmp.ra.endentityprofile=CMP_ENTITY
cmp.ra.certificateprofile=CMP_CERT
cmp.ra.caname=AdminCA1

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

CMP has been tested using RSA jCert toolkit for initialization requests. To run this as an RA you should configure CMP with:

• cmp.operationmode=ra
• cmp.allowraverifypopo=true
• cmp.responseprotection=pbe
• cmp.ra.authenticationsecret=your shared password
• and other configurations you want for your RA.

CMP has been tested with BlueX from AET Europe (http://www.aeteurope.nl/). From EJBCA's point of view BlueX functions as an RA with the same configuration options as for jCert.

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 should be a usual 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.

Simple OCSP client

You can build a simple OCSP client with 'ant ocspclient.jar'. This will place ocspclient.zip in the directory EJBCA_HOME/ocsp-dist. You can unzip this file and use the 'ocsp.sh' shell script on Linux/Unix. You can also use the API directly from your java program.

See the OCSP User Guide for information how to use the simple OCSP client.

Adobe Acrobat 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.

Configuring Web Services CLI

There exists one propertyfile in conf/jaxws.properties.sample that is used to configure the behaviour of the WS service. To configure it copy it and name it jaxws.properties.

See the sample file for details of how to configure the Web Service interface.

Configuring Web Services behavior

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 begin, 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, ...

Using the Web Services CLI

When building EJBCA, a Web Service CLI tool is also generated. The tool is placed in the directory dist/ejbcacli and consists of the all the necessary files needed to run the cli.

To use the client do the following, copy the directory with all included files to the computer you want to remote administrate from. Then create a JKS 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 JKS keystore and the password to unlock it.

Use 'ejbcaraws.sh/cmd' for a list of each subcommand and 'ejbcaraws.sh/cmd "subcommand"' for detailed help how to use the cli.

Example usage: ejbcawsracli.cmd pkcs12req testuser2 foo123 2048 NONE tmp

ejbcawsracli.cmd revokeuser testuser2 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

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:

  CertTools.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 'Vendil' in their subject dn:

  UserMatch usermatch = new UserMatch();
  usermatch.setMatchwith(org.ejbca.util.query.UserMatch.MATCH_WITH_DN);
  usermatch.setMatchtype(org.ejbca.util.query.UserMatch.MATCH_TYPE_CONTAINS);
  usermatch.setMatchvalue("Vendil");
  List(UserDataVOWS) result= ejbcaraws.findUser(usermatch);

Example to generate a certificate form a PKCS10 request:

  UserDataVOWS user1 = new UserDataVOWS();
  user1.setUsername("WSTESTUSER1");
  user1.setPassword("foo123");
  user1.setClearPwd(true);
  user1.setSubjectDN("CN=WSTESTUSER1");
  user1.setCaName("AdminCA1");
  user1.setEmail(null);
  user1.setSubjectAltName(null);
  user1.setStatus(10);
  user1.setTokenType("USERGENERATED");
  user1.setEndEntityProfileName("EMPTY");
  user1.setCertificateProfileName("ENDUSER");
			
  ejbcaraws.editUser(user1);	
  KeyPair keys = KeyTools.genKeys("1024", CATokenConstants.KEYALGORITHM_RSA);
  PKCS10CertificationRequest  pkcs10 = new PKCS10CertificationRequest("SHA1WithRSA",
  CertTools.stringToBcX509Name("CN=NOUSED"), keys.getPublic(), null, keys.getPrivate());
  CertificateResponse certenv =  ejbcaraws.pkcs10Request("WSTESTUSER1","foo123",new String(Base64.encode(pkcs10.getEncoded())),null,CertificateHelper.RESPONSETYPE_CERTIFICATE);
		
  X509Certificate cert = (X509Certificate) CertificateHelper.getCertificate(certenv.getData()); 		

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() != RevokeCertInfo.NOT_REVOKED)){
      // Certificate is revoked
    }else{
	  // Certificate isn't revoked
    }
  }else{
	// Certificate doesn't exist
  }	  

Sample code

See the file src/java/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: src/test/java/org/ejbca/core/protocol/ws/TestEjbcaWS
• The WS-API CLI: src/java/org/ejbca/core/protocol/ws/client/*.java

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

pkcs10req, pkcs10Request, pkcs12req:

• /ra_functionality/view_end_entity
• /ra_functionality/'end entity profile of the user'/view_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.

• /log_functionality/log_custom_events

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

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.ejbca.core.ErrorCode.CERT_PROFILE_NOT_EXISTS.getInternalErrorCode().equals(e.getFaultInfo().getErrorCode().getInternalErrorCode())) {
        log.error("No such certifcate profile.");
    }
}
    

All error codes are described in org.ejbca.core.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.

Introduction

From EJBCA 3.4 the XKMS protocol is supported as a service as a complement to the EJBCA Web Service interface.

It's included (but can be disabled) in the standard installation. And have the Web Service URL http://"hostname":8080/ejbca/xkms/xkms

NOTE: XKMS only works well with JDK 1.5, it does not work with JDK 6.

How to configure the XKMS Service

The XKMS service is configured in the file conf/xkms.properties, just edit the file before building the application.

The following settings exists:

• xkms.enabled: Enables the XKMS Service (default: true)
• xkms.request.requiresignature: id signed XKMS request should be required (default: false)
• xkms.request.acceptedcas: List of CA names that are accepted for XKMS signed requests. Use ';' as a separate for multiple. (default 'AdminCA1')
• xkms.response.acceptsignrequest: Accept signed responses on request (default: true)
• xkms.response.alwayssign: Always sign responses (default: false)
• xkms.response.causedforsigning: Specify which CA that should be used with the signed responses. Only one can be specified. (default 'AdminCA1')
• xkms.keyusage.signatureisnonrep: Setting specifying the keyusage in a X509 certificate that is mapped to XKMS KeyUsage Signature, Default is non-repudiation but if set to false will XKMS KeyUsage Signature be mapped against digital signature X509 key usage.
• xkms.serviceport=This is a development setting that is set in the WSDL to instruct the client use a non default port. This is only needed if a WS tap listener is used to review the messages. (default: 8080)
• xkms.krss.poprequired=Defines if proof of possession of the private key is required (default: true)
• xkms.krss.servergenkeylength=Defines the key length of server generated keys (default: 1024)
• xkms.krss.allowrevokation=Defines it should be possible for users to revoke their certificate with a revocation code (default: true)
• xkms.krss.allowautomaticreissue=Setting to allow the user to renew automatically as long as the current key isn't revoked (default: false)

Important, if signing of responses is needed, must the XKMS CA service for the configured CA be activated in the 'Edit CA' page. The XKMS Signer have it's own certificate for each CA just as the OCSP service and is created during the installation or upgrade of a CA.

Implementation Specific Notes

Using the XKMS client

When building EJBCA, a XKMS CLI tool is also generated. The tool is placed in the directory dist/xkmscli and consists of the all the necessary files needed to run the cli.

To use the client do the following, copy the directory with all included files to the computer you want to remote administrate from. (Optionally create a JKS keystore from one XKMS Service trusted CAs) and configure the file xkmscli.properties. In this file you should specify the hostname of the CA server, the name of the JKS keystore, the alias and the password to unlock it.

Use 'xkmscli.sh/cmd' for a list of each subcommand and 'xkms.sh/cmd "subcommand"' for detailed help how to use the cli.

Running the XKMS test script

To automatic test the XKMS Service do the following:

1. Start with a fresh installation with all the default values. Then activate the XKMS CA service in the Edit CA page for AdminCA1.

2. Run 'ant test:xkms' and a report will be generated in tmp/bin/junit/xkms/reports/html/index.html

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

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 users username
• ${PASSWORD} or ${user.PASSWORD} = The users password
• ${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 organization unit
• ${C} or ${user.C} = The user's country
• ${user.E} = The user's email address from Subject DN
• ${user.TIMECREATED} = The time the user was created
• ${user.TIMEMODIFIED} = The time the user was modified
• ${approvalAdmin.XX} variables from below can be used to get the administrator who adds an end entity.

Variables used with approvals:

• ${approvalRequest.DATE} = The time the approval request was created
• ${approvalRequest.ID} = The id of the approval request
• ${approvalRequest.ABS.ID} = The id of the approval request with out any '-' sign, used for presentation purposes.
• ${approvalRequest.TYPE} = The type of approval request
• ${approvalRequest.APROVEURL} = A URL to the review approval page with the current request.
• ${approvalRequest.APPROVALSLEFT} = The number of approvals remaining.
• ${approvalRequest.APPROVALCOMMENT} = The comment made by the approving/rejecting administrator
• ${requestAdmin.USERNAME} = The requesting administrator's username
• ${requestAdmin.CN} = The common name of the requesting administrator.
• ${requestAdmin.SN} = The common name of the requesting administrator.
• ${requestAdmin.O} = The requesting administrator's organization
• ${requestAdmin.OU} = The requesting administrator's organization unit
• ${requestAdmin.C} = The requesting administrator's country
• ${requestAdmin.E} = The requesting administrator's email address from Subject DN
• ${approvalAdmin.USERNAME} = The approving administrator's username
• ${approvalAdmin.CN} = The common name of the approving administrator.
• ${approvalAdmin.SN} = The common name of the approving administrator.
• ${approvalAdmin.O} = The approving administrator's organization
• ${approvalAdmin.OU} = The approving administrator's organization unit
• ${approvalAdmin.C} = The approving administrator's country
• ${approvalAdmin.E} = The approving administrator's email address from Subject DN

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

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.

Configuration

Currently Available Workers

CRL Update Worker

The CRL Updater have the same functionality as the current JBoss Service and will in the future replace the old variant. I checks if any of the CA:s need a new CRL and updates it if necessary. The worker have no settings and only supports the periodical interval and no action.

The CRL update 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.

Certificate Expiration Check Worker

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.
• 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. Here can the substitution variables be used 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. Here can the substitution variables be used defined in the 'Email Notifications' section.

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 Worker', 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.

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 jar containing the necessary plug-in classes 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 component by specifying the class path and optionally the custom properties used by the component. The properties field have the same syntax as a regular Java property file.

Auto-activation of CA 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.
(encrypted is only available in EJBCA >= 3.5):

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:
foo123
Encrypting pwd 'foo123'
6bc841b2745e2c95e042a68b4777b34c

NOTE: This encryption is not high security encryption, it is only meant to protect the password for accidental viewing. The encryption uses a build in encryption key in EJBCA. With an encrypted pin you can for example bring up the 'Edit CAs' page in the admin-GUI without everyone around immediately seeing your password.
If an attacker gets hold of the encrypted value it is easy to decrypt 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 manufacturers JCE provider. You have to check if that support is available.

Generic PKCS#11 provider (EJBCA 3.5)

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 property field of the administration GUI should contain the following properties:

• slot - the slot of the CA.
• slotListIndex - the index number in the slot list for the slot of the CA
• sharedLibrary - the shared PKCS#11 library to be used.
• attributesFile - a file specifying PKCS#11 attributes (used mainly for key generation).

But only one of 'slot' or 'slotListIndex' should exist.

Attributes file is in the format specified in the "JavaTM PKCS#11 Reference Guide". See http://java.sun.com/javase/6/docs/technotes/guides/security/p11guide.html and the examples further down in this file. An attributes file for nCipher typically looks like this:

attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_PRIVATE = true
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_TOKEN = true
}

The tool "$EJBCA/clientToolBox-dist/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:

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

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

The first example uses the default attributes of the HSM and are then using specified slot and PKCS#11 library. The second uses a configuration file. The contents of the file is specified in the PKCS#11 wrapper documentation from Sun. 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.

Utimaco PKCS#11

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/clientToolBox-dist/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/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 4096 signKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry signKey.
$EJBCA/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./libcs2_pkcs11.so 2048 defaultKey 1
PKCS11 Token [SunPKCS11-libcs2_pkcs11.so-slot1] Password:
Creating certificate with entry defaultKey.
$EJBCA/clientToolBox-dist/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:

slot 1
defaultKey defaultKey
certSignKey signKey
crlSignKey signKey
testKey testKey
pin user1
sharedLibrary /opt/utimaco/p11/libcs2_pkcs11.so

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
nfast@donny:/home/lars/work$

Create the security world with the command :

nfast@donny:/home/lars/work$ /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
nfast@donny:/home/lars/work$

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:

nfast@donny:/home/lars/work$ /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
nfast@donny:/home/lars/work$

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:

jboss@donny:~$ /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.5.0_11 or similar)
• APPSRV_HOME (/home/jboss/jboss-4.2.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). Create a file (ocs-sunpkcs11.cfg) with the following contents:

name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex=1
attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_PRIVATE = true
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_TOKEN = true
}

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

jboss@donny:~/work/test/keygen$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 4096 defaultRoot
Executing /home/lars/work/java/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 4096 defaultRoot
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry default.
jboss@donny:~/work/test/keygen$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 2048 cryptRoot
Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key (RSAPrivate) on modules 1
Executing /home/lars/work/java/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 2048 cryptRoot
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry crypt.
jboss@donny:~/work/test/keygen$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 1024 test
Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-27cfdae84bf4298f2dde83cd00980a81bcf095bf key (RSAPrivate) on modules 1
Executing /home/lars/work/java/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./ocs-sunpkcs11.cfg 1024 test
PKCS11 Token [SunPKCS11-NFastJava] Password: 
Creating certificate with entry test.
jboss@donny:~/work/test/keygen$ 

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:

jboss@donny:~/work/test/ca$ ~nfast/bin/preload -c ejbca $JBOSS_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
slotListIndex 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 slightly different configuration file when creating the key. The file could look like this:

name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex=0
attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_TOKEN = true
}

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:

lars@milton:~/work/test/nCipher$ 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:

lars@milton:~/work/test/nCipher$ ~nfast/bin/preload -c 2of3_0 pause
-- follow instruction to insert cards and enter pins. --
-- then press ctr-z --
lars@milton:~/work/test/nCipher$ bg 
lars@milton:~/work/test/nCipher$ ~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@subcallb:/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 PKCS#11 configuration file for generating the CA keys.

name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex=1
attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_PRIVATE = true
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_TOKEN = true
}

Sample catoken.properties for generating the initial AdminCA on the netHSM, or entering in the admin-GUI when creating a new CA.

defaultKey defaultKey
certSignKey defaultSign
crlSignKey defaultSign
testKey testKey
sharedLibrary /opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex 1

AEP Keyper

The documement xxxxxxKeyperP11.pdf (xxxxxx is six digits) describes how the HSM is installed. As default there is only one slot - 0.

The HSM needs a configuration file when generating the keys. It could look like this:

name=Keyper
library=/Users/flourish/Keyper/PKCS11Provider/pkcs11.GCC4.0.1_i386.so.4.04
slot=0
attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_TOKEN = true
}

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

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.

The configuration file used when generating a key with 'pkcs11HSM.sh' must look like this:

name=TrustWay
library=../../bullInstall/linux/libgpkcs11cc2000.so
slotListIndex=0
attributes(generate,CKO_PRIVATE_KEY,*) = {
  CKA_TOKEN = true
}

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

lars@maud:~/work/test/keygen$ LD_LIBRARY_PATH=~/work/bullInstall/linux ../../PWE/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate trustWay.cfg 2048 defaultkey

SafeNet Luna

lars@milton:~/work/test/luna$ /usr/lunasa/bin/ctp admin@lunasa.int.primekey.se:server.pem .

lars@milton:~/work/test/luna$ sudo /usr/lunasa/bin/vtl addServer -n lunasa.int.primekey.se -c server.pem
lars@milton:~/work/test/luna$ sudo /usr/lunasa/bin/vtl createCert -n milton

lars@milton:~/work/test/luna$ /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

lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./sunpkcs11.cfg 2048 rsa2048_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.
lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./sunpkcs11.cfg secp160r1 secp160r1_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.

name=Luna
library=/usr/lunasa/lib/libCryptoki2_64.so
#library=/usr/lib/pkcs11-spy.so
slot = 1

attributes(generate,*,*) = {  
  CKA_TOKEN = true
}
attributes(generate,CKO_PUBLIC_KEY,*) = {
  CKA_ENCRYPT = true
  CKA_VERIFY = true
  CKA_WRAP = true
}
attributes(generate, CKO_PRIVATE_KEY,*) = {
  CKA_EXTRACTABLE = false
  CKA_DECRYPT = true
  CKA_SIGN = true
  CKA_UNWRAP = true
}

lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/clientToolBox-dist/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.

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/ETcpsdk/lib/linux-x86_64 /opt/ETcpsdk/bin/linux-x86_64/ctconf

LD_LIBRARY_PATH=/opt/ETcpsdk/lib/linux-x86_64 /opt/ETcpsdk/bin/linux-x86_64/ctconf -c10

LD_LIBRARY_PATH=/opt/ETcpsdk/lib/linux-x86_64 /opt/ETcpsdk/bin/linux-x86_64/ctconf -fc

LD_LIBRARY_PATH=/opt/ETcpsdk/lib/linux-x86_64 /opt/ETcpsdk/bin/linux-x86_64/ctkmu t -s5 -lroot

$EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate ./slot5.cfg 2048 default

name=SafeNet
library=/opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so
#library=/usr/lib/pkcs11-spy.so
slot=5
attributes(*,*,*) = {
  CKA_TOKEN = true
}
attributes(*,CKO_PRIVATE_KEY,*) = {
  CKA_PRIVATE = true
  CKA_SIGN = true
  CKA_DECRYPT = true
  CKA_EXTRACTABLE = true
  CKA_SENSITIVE = true
}

$EJBCA_HOME/clientToolBox-dist/ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/ETcpsdk/lib/linux-x86_64/libcryptoki.so 5

Writing support for new HSMs

EJBCA have a modular API for HSMs, HardCAToken. For every CA that is created a HardCAToken object is also created. This object contains among other things references to keys (or the keys themselves of a soft token is used). For each HSM hardware that should be supported you need one HardCAToken class that implementes support for this particular HSM. A hard ca token plug-in must:

1. implement ICAToken
2. it is recommended to extend BaseCAToken, since BaseCAToken implements handling of all properties, autoactivation and such
3. be loaded at the static initialization if CATokenManager where it is registered with the CATokenManager using the method addAvailableCAToken()
4. Provide a JCE Security Provider that is installed by the module and can be fetched by the EJBCA crypto module (BouncyCastle) through the name returned in ICAToken.getProvider().

See HardCATokenSample and/or DummyHardCAToken for samples. Unlike the sample addAvailableCAToken() must be called with use=true, or the token will not be usable in EJBCA (as the flag suggests).

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 adduser ldap password "C=SE,O=Foo,CN=ldap.foo.se" null MyCA null 1 PEM SERVER

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::

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

include         /usr/local/etc/openldap/schema/cosine.schema
include         /usr/local/etc/openldap/schema/inetorgperson.schema

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

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

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

/usr/local/bin/ldapsearch -x -b 'o=AnaTom,c=SE' '(objectclass=*)'

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

bin/ejbca.sh batch

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

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

OPENLDAP_START_LDAPS="yes"

SuSEconfig

rcldap start

bin/ejbca.sh ca getrootcert 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.se 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

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

Extra device schema

To store certificates for devices (e.g. routers, toasters etc) in LDAP it is no really suitable standard object class. inetOrgPerson requires surnames etc, and the device objectclass does not include a certificate attribute.

Mike Jackson has kindly contributed additional objects that extend the standard device class with a certificate attribute. The ejbcaDevice uses object ids from PrimeKey Solutions AB.

Custom publishers

	crl.application /fullpathname/exportscript.sh
	crl.failOnStandardError <true | false>
	crl.failOnErrorCode <true | false>
	cert.application /fullpathname/exportscript.sh
	cert.failOnStandardError <true | false>
	cert.failOnErrorCode <true | false>
	revoke.application /fullpathname/exportscript.sh
	revoke.failOnStandardError <true | false>
	revoke.failOnErrorCode <true | false>

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 PublishQueue. This queue can then be processed by a service (see Services Framework).

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.

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

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/ejbca.properties.

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

• ant clean
• ant deploy

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/ejbca.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("BC");
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 bin/batchtool.properties. The possible parameters are explained there. If using the implicitlyCA facility the same parameters as configured for the ca in conf/ejbca.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.

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 ca.sh and ra.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 src/adminweb/languages. In order to add a language you should do the following:

1. Rename the languagefile you have created to language.languagecode.properties. In case of chinese it should be 'zh', and place it in the src/adminweb/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: <env-entry-value>EN,FR,IT</env-entry-value>
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 EN, FR and IT in the system configuration as default language and in the administrator preferences page. The language will be changed next time the administrator logs in.

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/web.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 is configured in the file 'src/java/certextensions.properties' All extensions should have a id ranging from 1 up to 255, the number order is important.

• oid : The unique OID of the extension (Required)
• classpath : Classpath to the CertificateExtention implementing class. (Required)
• displayname : Display name of the extension in the 'Edit Certificate Profile' page (Required)
• used : Defines if the extensions should be used or be disabled. (Required)
• translatable : If the display name should be translated in the language resources. (Required)
• critical : Defines if the extension should be marked as critical in the certificate. (Required)
• property.'property' : It is possible to define properties to the actual implementation of the CertificateExtention, for example does the BasicCerticateExtension require the properties 'encoding' and 'value' to be set.

After the file is configured rebuild and deploy EJBCA.

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

Basic Certificate Extension

In order to create a Basic Certificate Extension you use the classpath org.ejbca.core.model.ca.certextensions.BasicCertificateExtension and specify the properties idX.property.encoding and idX.property.value. 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.

Implementing an Advanced Certificate Extension

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

Here is an example of a simple advanced extension. To add this extension to EJBCA add it to to the classpath in certextensions.properties, make sure the class is accessible in the classpath and redeploy.

public class SomeAdvancedCertificateExtension extends CertificateExtension {

    private static String PROPERTY_SOMEPROPERTY = "someproperty";

	/**
	 * The main method that should return a DEREncodable
	 * using the input data (optional) or defined properties (optional)
	 * 
	 * @see org.ejbca.core.model.ca.certextensions.CertificateExtension#getValue(org.ejbca.core.model.ra.UserDataVO, org.ejbca.core.model.ca.caadmin.CA, org.ejbca.core.model.ca.certificateprofiles.CertificateProfile)
	 */	
	public DEREncodable getValue(UserDataVO userData, CA ca,
			CertificateProfile certProfile) {
		
		String value = getProperties().getProperty(PROPERTY_SOMEPROPERTY);
		
		return new DERPrintableString(value);
	}

}

Log4JLogDevice

Appends the information from the offical event to the console or file. This is the same target where all the other info/debug output is sent to. There are no protection from alteration and events sent to this device cannot be fetched back to EJBCA for display in the Admin GUI.

OldLogDevice

OldLogDevice stores log-events in the database. By using the addon HMAC-protection, alterations in a log event can be detected. Viewed events can be exported from the Admin GUI.

ProtectedLogDevice

The ProtectedLogDevice stores log-events in the database and has the ability to detect changed or missing log-events. In an environment where at least one node (EJBCA-instance) is constantly running, the log cannot even be rolled back to a an earlier state without detection.

Features:

• No event can be removed or changed without detection (as long as one node is still runnning)
• Can perform regular signed export of log for backup (mitigates damage of offline rollback)
• Can send emails, run a script and/or kill the JVM if alterations are detected
• Can use a CA-token (hard or soft) or a soft JKS keystore (stored encrypted with CA-key in database)
• Can set a signature intensity to allow slower HSMs to use the feature
• Nodes can be added or removed dynamically

Drawbacks:

• Very database intensive.
• Cannot yet export viewed part of log from Admin GUI

It is good practise to

• use secure communication with the database.
• use asymmetric log-signing key and a HSM.
• use a database/database engine that supports transaction (e.g. InnoDB and not MyIsam for MySQL).

The log can be verified manually using "ejbca.sh/cmd log" CLI.

See conf/logdevices/propectedlog.properties.sample for more information on how to configure and use the device.

Command line interface

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

Other Configuration

To setup an initial hard token issuer with alias 'local' and queue a superadmin user for card issuing. Card issuing using the hard token issuers is normally done using PrimeCard.

bin/ejbca.sh setup initializehardtokenissuing <caname>
Ex: bin/ejbca.sh setup initializehardtokenissuing AdminCA1

This is a utility function to quickly and easily issue an initial administration smart card using PrimeCard.

If you want to change the baseurl of the admin-web after installation use the command:

bin/ejbca.sh setup setbaseurl computername applicationpath
Ex: bin/ejbca.sh setup setbaseurl localhost ejbca

You should never have to do this in version >= 3.2.

To change ports (default public http=8080, public https=8442, private https=8443) you must edit conf/ejbca.properties. Change the properties httpserver.pubhttp, httpserver.pubhttps and httpserver.privhttps. After changing, run 'ant deploy' 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 adminca1.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 setuserstatus 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 adduser' 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 J2EE 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 to $EJBCA_HOME/../ejbca-custom/src/java/*.properties

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.
• committing 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 src/publicweb/publicweb. Modify the pages (directly or by using a separate tree), rebuild and redeploy. The changes should show on http://ejbcahost:8080/ejbca.

Character limitations

Since the Admin GUI still uses some JSP and EJBCA at some occasions uses string concatenation to build SQL querys, we have to ban some characters to avoid XSS-attacks and SQL-injections:

(\n is newline, \r is carriage return, \\ is backslash, \0 is null)

These characters will be replaced by /. ',' can be escaped ,'\,'.