You can administrate 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

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/**

To restore:

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:

Go to 'List/Edit End Entities' and search for user 'tomcat'.
'Edit_End_Entity' and set the 'Password' to the same as httpsserver.password in your conf/ejbca.properties and 'Status' to 'New'.
Open up a command line in EJBCA_HOME and run 'bin/ejbca.sh batch'.
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.
Restart JBoss.

You can also do everything using the CLI:

bin/ejbca.sh ra setuserstatus tomcat 10
bin/ejbca.sh ra setclearpwd tomcat <password from httpsserver.password>
bin/ejbca.sh batch
cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
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.

Go the the 'Edit Certificate Authorities' page in the Administration GUI.
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.
At the next page called 'Make Certificate Request' you have to upload the external CA certificate chain that you want to sign your CA certificate with. 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.
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.
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.
When the Certificate Response has arrived, it 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
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 PEM certificate and click again on 'Receive Certificate Response'.
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'. 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.
The new externally signed CA is ready to use.

Exmaple of a plain PEM file for uploading as a certificate chain when creating the request from a CA:

You can treat an internal CA, i.e. a CA risiding 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-persistens, 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 activa 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:

In the 'Edit CA' page, choose a CA name of the external CA you are about to sign and click on 'Process Certificate Request'.
Then you are requested to upload the certificate request sent from the external CA. This should be a file in PEM-encoding.
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.
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.
Send the processed certificate back to the external CA for activation.
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.

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

Using EJBCA

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:

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

CRL generation

A new CA should always issue an (empty) CRL. This is done when the ca is created and can also be done by running 'ca.sh/cmd createcrl caname'.

There are three settings in CA configuration dictating the times when CRL generation is done:

CRL Expire Period (Hours): Mandatory. The validity period for generated CRLs. If set to for example 24, the nextUpdate for a generated CRL will be the issue time + 24 hours.
CRL Issue Interval (Hours): Optional. A fixed interval when CRLs will be issued. If set to for example 1 hour a new CRL will be issued every hour, even though the old one is still valid for another 23 hours. The default value here is 0, which means that a new CRL will be issued when the old one is about to expire (see also overlap time). Keeping the default value 0 has the same as effect as setting this value to the same value as CRL Expire Period.
CRL Overlap Time (Minutes): Optional. When checking if a CRL should be generated (if the old one is about to expire), the new CRL is generated this amount of minutes before the old CRL expires. The default value is 10 minutes, meaning that if CRL Expire period is 24 hours, a new CRL will be issued after 23h50m. This ensures that there is no time period (even a few seconds) when there is no valid CRL issued. It also gives clients a time-slot to download a new CRL before the old one expires.

There are at least two ways to have EJBCA to periodically create updated CRLs.

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.

Scep

Since SCEP uses encryption, you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found at the same place as the JDK download. Further information on this can be found in the Sun documentation on the JCE.

There are some compatibility issues with SCEP, one being if the CA certificate should be returned in a SCEP enrollment response or not. The CA certificate is optional but some, Cisco VPN client, seems to require it while others, Juniper, seems to dislike it. Therefore EJBCA has two SCEP URLs.

The default including the CA certificate (use if nothing else specified):

http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe

Not including the CA certificate (try if the default doesn't work):

http://localhost:8080/ejbca/publicweb/apply/scep/noca/pkiclient.exe

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

Using the External RA API the following SCEP message is also supported for polling mode:

GetCertInitial

The following CA capabilities are supported:

POSTPKIOperation
SHA-1

* CA mode *

EJBCA does successfully receive SCEP 'PKCSReq' requests and send back the certifificate/CRL immediately in a proper SCEP reply message. EJBCA (standard) does not support the 'polling' model, EJBCA uses the direct CA method, where a request is granted or denied immediately. The SCEP client will send messages directly to the CA, encrypted with the CAs certificate.

The CN part of the DN in the PKCS#10 request, which is part of the Scep request, will be used as the 'username' when authenticating the request in EJBCA. Create the Scep request with a CN mathing the username registered in EJBCA. The challengePassword in the PKCS#10 request, which is part of the Scep request, will be used as the 'password' when authenticating the request in EJBCA. Create the Scep request with a challengePassword mathing the password registered in EJBCA.

The most common errors should be wrong username/password or wrong status (not NEW) on the user in EJBCA.

* RA mode (ExtRA API 3.4.2) *

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

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

* OpenScep *

OpenScep has does not work with modern OpenSSL implementation (only works with OpenSSL 0.9.6) and also has a bug that causes it to crash when receiving SCEP responses. There are patches that address these issues though so it can be used.

To use the OpenScep client to request a certificate from this servlet, use the command:

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

Where test.key is generated with:

openssl genrsa -out test.key

test.req is generated with:

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

and test.pemreq is generated with:

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

* Simple Scep Client (sscep) *

Simple Scep Client. You should only use CN in the users DN (same as for PIX below).

* Juniper Networks NetScreen-25/NetScreen-50 *

Works nice using the URL not including the CA certificate.

To enroll using the Juniper box go to the Web GUI at https://<juniper-ip>/, then click your way to Objects->Certificates. To create a new certificate request:

New - enter the DN that your box will receive:
- Name=netscreen.foo.se
- Organization=PrimeKey
- Country=SE
- IP Address=192.168.1.1
- FQSN=netscreen.foo.se
Click generate.
Automatically enroll to -> New CA Server settings. The CGI URL differs if you are using the direct CA mode or the RA polling mode:
- RA CGI: http://<ra-ip>:8080/scepraserver/scep/noca/pkiclient.exe or http://<ca-ip>:8080/ejbca/publicweb/apply/scep/noca/pkiclient.exe.
- CA CGI: http://<ra-ip>:8080/scepraserver/scep/noca/pkiclient.exe or http://<ca-ip>:8080/ejbca/publicweb/apply/scep/noca/pkiclient.exe.
- CA IDENT: The CA Name in EJBCA, for example ScepCA.
- Challenge: A password for a pre-registered user in CA mode, or a random password used for polling RA mode.
Click OK.
You can now see the request in Objects->Certificates. If you are using polling RA mode, you can click 'Retrieve' after the request has been approved in the CA and the certificate has been generated.

* Cryptlib *

Cryptlib is working as of EJBCA 3.1.3.

When using Cryptlib, the CA certificate must have KeyUsage 'Key Encipherment' in addition to the usual key usage flags. This is reasonable, since SCEP requires the CA to actually encrypt data (which generally is a bad thing, since a special encryption certificate should be used for that).
Key usage for a ScepCA should be: Certificate Sign, CRL Sign, Digital Signature, Key Encipherment

Use the complete path as for the Cisco VPN client below as server name.

* Cisco VPN client *

Tested with version 4.0.2 and 5.0.

To enroll using the Cisco VPN client use:

CA URL='http://127.0.0.1:8080/ejbca/publicweb/apply/scep/pkiclient.exe'
CA Domain=you CAs name in EJBCA
In the DN screen simply enter the username (as added in EJBCA) as 'Name [CN]'

When using an External RA to enroll with the Cisco VPN client, the RA certificate must have KeyUsage SigitalSignature and KeyEncipherment for the client to accept the CA certificates. However, to locate the RA encryption certificate, only KeyEncipherment can be set, which makes things quite complicated.

The conclusion is that RA enrollment does not work with Cisco VPN client.

* AutoSscep *

EJBCA has been tested successfully with AutoSscep for enrollment against the CA and the External RA SCEP service.

Instructions:

Download and build AutoSscep (make).
Create a configuration file, ejbca.conf, as the example below.
Create a user in EJBCA with username (common name) and DN exactly as entered in the configuration file.
run 'autosscep ejbca.conf'.

Sample configuration file, ejbca.conf:

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]

AutoSscep also handles enrolling against an RA, where the RA first sends a PENDING response which the request is beeing processed. After processing (by the CA) you simply run the AutoSscep client again to pick up the generated certificate.
In order to enroll against the External RA SCEP Server in EJBCA i only had to change the CA part of the configuration file to use the SCEP RA servers certificate for signing and encrypting the messages instead of the CAs, and to use the URL to the RA. The SCEP RA certificate is the end entity certificate issued to the External RA SCEP server (the keystore is usually called scepraserver.p12).

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

* Cisco PIX/3000 *

Cisco PIX is working as of EJBCA 3.1.3.
Also Cisco 3000 is reported working well. The description below is for PIX, 3000 probably have less constraints than the PIX.

You must configure JBoss to use port 80 to enroll with PIX, this is done in APPSRV_HOME/server/default/deploy/jbossweb-tomcat50.sar/service.xml (or similar depending on version). You must run as root to use port 80.
EJBCA supports the 'ca' mode of enrollment for pix, not 'ra'. For 'ra' and polling enrollment you can use the External RA module (extra).
The certificate profile used by the SCEP CA must include the key usages KeyEncipherment and DataEncipherment, otherwise PIX will not be able to verify/decrypt encrypted SCEP messages. This is not in the default certificate profile for CAs. Create a new certificate profile before creating the Scep CA, you can use ROOTCA as template for the new certificate profile.
When enrolling for certificate using SCEP with for example a Cisco PIX it is a 'ca_nickname'. This nickname should be the CA-name as defined when creating the CA in EJBCA. For example 'vpnca'.
Only use lower-case names when creating the CA in EJBCA, since PIX will change the CA name VpnCA to vpnca when enrolling.
The username in EJBCA must be the name the PIX identifies itself with name.domain, example pix.primekey.se.
The end-entity DN must include the DN components CN and unstructuredName, ex "CN=pix.primekey.se, unstructuredName=pix.primekey.se". You can also include O, C etc in the certificate. A normal DN for a PIX is "CN=pix.primekey.se,unstructuredName=pix.primekey.se,O=PrimeKey,C=SE".
Certificates used for PIX MUST include the DN component unstructuredName (fqdn) and could also include unstructuredAddress (ip) being the IP-address of the PIX.
The certificate used on the Cisco PIX MUST have a SubjectAltName field dNSName, matching the DN component unstructuredName. This is needed in order for Cisco VPN clients to connect to the PIX. The DNS Name field is not necessary for the PIX to enroll perfectly with EJBCA, only for the client to be able to connect.
Certificates used for PIX may also use the SubjectAltName iPAddress matching the DN component unstructuredAddress, but it's not necessary.
Cisco does not support use of the 'Domain Component', DC, attribute in DNs, don't use it.
KeyUsage should include Digital Signature and Key Encipherment, the EJBCA defaults work fine.
When the Cisco VPN-client (above) connects to the PIX, the 'ou' part of the clients DN must match a Vpngroup you have specified, otherwise the connection will fail.
Cisco PIX needs the SCEP response messages to use MD5 as hash algorithm, not SHA1, this is handled by EJBCA automatically.

Please notice this Cisco note:

Be sure that the PIX Firewall clock is set to GMT, month, day, and year before configuring CA. Otherwise, the CA may reject or allow certificates based on an incorrect timestamp. Cisco's PKI protocol uses the clock to make sure that a CRL is not expired. Set timezone first, then set time, then check time with 'show clock'.

The enrollment steps should be something like:

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

CMP (EJBCA >=3.4)

CMP (RFC4210) is a very complex protocol, which EJBCA does implement some parts of.
The following CMP messages are supported:

Initialization request (ir)
Certification request (cr)
Certification Confirm (certConf)

Certificate requests use the CRMF (RFC4211).

From EJBCA 3.5, CMP support in RA mode (see below) can support several CAs and profiles based on the keyId of the password used to protect the CMP messages (PBE protection).
In EJBCA 3.4 CMP support in RA mode is currently limited to one keyId, making RA requests for one CA.

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

Currently these are the only POPs supported by EJBCA, so if you don't use raVerify or signature your request will fail because POP is not verified.

Normal or RA mode for CMP

CMP in EJBCA can work in two modes:

* Normal *

Normal mode works like any other enrollment in EJBCA. When a request comes in EJBCA verifies the request (see User authentication above) and issues a certificate to a user that has been previously registered in EJBCA.
This is the default mode of operation.

* RA *

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

The users DN is taken from the CertTemplate in the request message send from the RA (i.e. the DN requested by the RA).
The username in EJBCA is generated according to the options set in conf/cmp.properties.
The password for the user in EJBCA is random.
If the Certificate Profile allows it, keyUsage and validity is also taken from the CertTemplate in the request message.

After the user has been created in EJBCA, a certificate is generated as usual and sent back to the RA, who will distribute it to the end-user.

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

To allow requests with different KeyId to be mapped to different CAs and profiles in EJBCA, so the documentation for the options in conf/cmp.properties.sample.

* Sample config *

A sample config of EJBCA to allow an RA to request certificates for users. The RA uses password based mac (pbe) protection of CMP messages with password 'password'. Users will be created using UID from the request DN and with a prefix, so the resulting username will be: cmp<UsersUID>. End entity profiles names CMP_ENTITY and CMP_CERT is created in EJBCA allowing the request DN.

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.

Ocsp

Note! Some OCSP clients does not handle external OCSP responders very well unfortunately. You should be aware of this.

OCSP is used by PKI-clients to verify the validity of certificates in real-time. This is done by sending a request for the status of a specific certificate to an OCSP responder. The responder may or may not be the same as the CA. The OCSP responder sends a signed reply, containing the requested status information back to the client. The client uses this status information to determine whether the certificate is valid for use or revoked.

It is an OCSP servlet receiving requests on http://localhost:8080/ejbca/publicweb/status/ocsp. The servlet can process requests for certificates signed by a CA running in EJBCA, as long as the CAs OCSP service has not been deactivated.

The OCSP servlet receives OCSP request by http(s) and send back a status response signed by the CA, or with a dedicated responder certificate.

For a CA to be valid as an OCSP-responder it must have the KeyUsage 'Digital Signature' in the certificate profile used to create the CA. This KeyUsage must be included if the CA is to sign OCSP-responses. The default certificate profiles for CAs includes the key usage 'Digital Signature'.

There are a two parameters affecting the OCSP service that can be configured in conf/ejbca.properties:

'useCASigningCert' - If set to true (default) the OCSP responses will be signed directly by the CAs certificate instead of the CAs OCSP responder. If set to false, the CAs special OCSP responder certificate is used to sign the OCSP responses. The OCSP responder certificate is signed directly by the CA.
'defaultResponderID' - Specifies the subject of a CA which will generate responses when no real CA can be found from the request. This is used to generate 'unknown' responses when a request is received for a certificate that is not signed by any CA on this server. Set this to the same DN as your initial Admin CA for example.

These values should be set during deployment of EJBCA. After the values have been edited, they are installed with the 'ant deploy' command.

Example to generate an OCSP request using OpenSSL (works with both internal and external OCSP responders):

openssl ocsp -issuer Test-CA.pem -CAfile Test-CA.pem -cert Test.pem -req_text -url http://localhost:8080/ejbca/publicweb/status/ocsp

If Mozilla is to request and accept OCSP-responses from a CA it must be configured:

'Use OCSP to validate all certificates using this URL and signer' in 'Privacy & Security->Validation'. Choose the CA from EJBCA (which you should have made Trusted by right clicking in 'Privacy & Security->Certificates->Manage Certificates->Authorities' and checking the appropriate checkboxes).
If using a Certificate Profile that includes a OCSP Service URL for client certificates, the Validation option in Mozilla 'Use OCSP to validate only certificates that specify an OCSP service URL' also works fine. When this option is checked you may need to restart Mozilla.

When the validation settings are set, Mozilla will query the OCSP server when for example double-clicking on a certificate in the certificate manager. An appropriate URL for validation is: http://hostname:8080/ejbca/publicweb/status/ocsp

If using a dedicated OCSP responder certificate, this certificate must probably not be imported in Mozilla as a Trusted CA certificate. But if you want to, you can do this through 'View Certificates' in EJBCA (http://hostname:8080/ejbca/retrieve/ca_certs.jsp).

In doc/samples it is a sample how to check revocation with OCSP using the new APIs in JDK 1.5.

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 document doc/howto/HOWTO-OCSP-RESPONDER.txt for information how to set up stand-alone, separated OCSP responders.
See the image HOWTO-OCSP-RESPONDER.jpg for an overview of a sample setup.

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 document doc/howto/HOWTO-OCSP-Unid-client.txt 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.

EJBCA Web Service Interface

New to EJBCA 3.4 is a JAX-WS 2.0 Web Service Interface used to access the basic functions remotely over client authentication HTTPS.

The JAX-WS interface depends on java 1.5 or later and will otherwise not be included in the EJBCA installation.

The functionality currently available through the Web Service Interface are:

getEjbcaVersion : Returns the version of the EJBCA server.
editUser : Edits/adds userdata
findUser : Retrieves the userdata for a given user
findCerts : Retrieves the certificates generated for a user
pkcs10Req : Deprecated method previously used to generate a certificate using the given userdata and the public key from the PKCS10
pkcs10Request : Newer method that generates a certificate or PKCS7 using the given userdata and the public key from the PKCS10
pkcs12Req : Generates a PKCS12 keystore (with the private key) using the given userdata
cvcRequest : Generate a CV certificate for the specified user using the public key from the CVC request. See the CVC documentation for more details.
revokeCert : Revokes the given certificate
revokeUser : Revokes all certificates for a given user, it's also possible to delete the user
revokeToken : Revokes all certificates placed on a given hard token
checkRevokationStatus : Checks the revokation status of a certificate
isAuthorized : Checks if an admin is authorized to an resource
fetchUserData : Method used to fetch userdata from an existing UserDataSource
genTokenCertificates : Method used to add information about a generated hardtoken
existsHardToken : Looks up if a serial number already have been generated
getHardTokenData : Method fetching information about a hard token given it's hard token serial number.
getHardTokenDatas: Method fetching all hard token informations for a given user.
republishCertificate : Method performing a republication of a selected certificate
isApproved : Looks up if a requested action have been approved by an authorized administrator or not
customLog : Logs a CUSTOM_LOG event to the logging system
deleteUserDataFromSource : Method used to remove user data from a user data source
getCertificate : Returns a certificate given its issuer and serial number
keyRecoverNewest : Marks the users latest certificate for key recovery. Note, to key recover the user the status must also be set to KEYRECOVERY (70), and the user must have been generated for key recovery from the start. If all prerequisites are fulfilled, the next pkcs12Req call (for example) will return the recovered key and certificate.
getAvailableCAs : Fetch a list of the ids and names of available CAs, i.e. not having status "external" or "waiting for certificate response".
getAuthorizedEndEntityProfiles : Fetch a list of end entity profiles that the administrator is authorized to use.
getAvailableCertificateProfiles : Fetch a list of available certificate profiles in an end entity profile.
getAvailableCAsInProfile : Fetch a list of the ids and names of available CAs in an end entity profile.
createCRL : Generates a CRL for the given CA.

There is also a cli tool that can be used for remote scripting. See following section for more information. Note: All these calls are not available through the CLI.

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.

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 with the administrator flag set and access rules according to the following:

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

Administrator flag set
/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.

XKMS Service

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

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

* What is implemented *

Currently are the methods locate, validate, register, reissue, revoke and recover). The Compond request isn't implemented.

The XKMS Service only supports synchronized calls, not asynchronized or two-phase requests.

The TimeInstant attribute of QueryKeyBinding is not supported

In the NotBoundAuthentication isn't the 'Protocol' attribute used.

The register listener expects a UseKeyWith=urn:ietf:rfc:2459 (PKIX) with the subjectDN as identifier and is mapped to the user. The password of the user Must be marked as cleartext in order for KRSS to work. In KeyInfo is one RSAKeyInfo required if the user have the type 'USERGENERATED'. All other UseKeyWith or KeyUsage is ignored. since it is the register userdata that is used when issuing the certificate. If the user have the type "P12" in it's userdata then will a server generated key be inserted in a PrivateKey in the response. It is the same password to encrypt the key as for the enrollment. RespondWith RSAPublicKey, X509Certificate, X509CertificateChain and PrivateKey is supported.

The reissue listener expects one X509Certificate KeyInfo in the request and the subjectDN and public is extracted and used for the new certificate. Revoked certificates cannot be renewed. The generated key will be inserted in a PrivateKey in the response. It is the same password to encrypt the key as for the enrollment. RespondWith RSAPublicKey, X509Certificate and X509CertificateChain.

The recover listener expects one X509Certificate KeyInfo in the request and is used to select the user in the database. Before a key can be recovered the key have to be marked for recovery and a password set for the user in the usual way. RespondWith RSAPublicKey, X509Certificate, X509CertificateChain and PrivateKey is supported.

The revoke listener expects one X509Certificate KeyInfo in the request and is used to select the certificate that should be revoked. A revokation code is required, authentication tag is not supported. RespondWith RSAPublicKey, X509Certificate and X509CertificateChain is supported.

* XKMS Mappings *

The RespondWith tag supports X509Certificate, X509CertificateChain, X509CRL, KeyName, KeyValue (and PrivateKey for register and recover).

The QueryKeyBinding The query of a QueryKeyBinding is performed in the following way: If KeyInfo is included, the certificate is extracted and the is used for checking the key usage and validity of the certificate If UseKeyWith is included (and no KeyInfo) is the user database queried using the UseKeyWith mappings (if several UseKeyWith are the queried with an 'AND' operator. Then are all certificates that fulfills all the KeyUsage mappings returned.

In KeyInfo is only X509Certificate and X509CertificateChain supported

KeyUsage Mappings, The key usage constants is mapped against the following X509 key usages

SIGNATURE : either non-repudiation or digital signature depending on configuration
ENCRYPTION: data encipherment
EXHANGE: digital signature and key encipherment

UseKeyWith Mappings, All queries find their data using beginwith (except PKIX) of the identifier.

XKMS: Subject Altname, UNIFORMRESOURCEIDENTIFIER
XKMS/profile: Subject Altname, UNIFORMRESOURCEIDENTIFIER
S/MIME: Subject Altname, RFC822 addr-spec
PGP: Subject Altname, RFC822 addr-spec
TLS: Subject Altname, UNIFORMRESOURCEIDENTIFIER
TLS/HTTPS: SubjectDN, Common Name
TLS/SMTP:Subject Altname, DNS Name
IPSEC:Subject Altname, IP Address
PKIX: Entire SubjectDN

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

External RA API

In some cases, for security reasons, is it preferable to deny all inbound traffic to the CA and instead let the CA periodically fetch and process information from external trusted data sources.

The ExtRA API contains the most basic functions like:

Generate Certificate from PKCS10
Generate PKCS12 for the end user
KeyRecovery of the users key (if requested using PKCS12)
Edit users
Revoke Certificates

The external API, named extra, is downloaded separately, or checked out separately from the CVS using the module name 'extra'.

Documentation about the ExtRA API is in the doc subdirectory of the extra subproject.

Key recovery

Key Recovery can be used to re-use or restore a users private key. To enable key recovery use the admin-GUI:

Set 'Enable Key Recovery' in 'System Configuration'.
Create a new End Entity Profile and set to use 'Key Recoverable'.
Add users with this End Entity Profile.

The following is an example of a sequence of commands that can be used to generate a new certificate for a user using the same key pair:

# First revoke username, with revocation reason reason,

bin/ejbca.sh ra revokeuser $username $reason

# then mark the certificate for keyrecovery,

bin/ejbca.sh ra keyrecovernewest $username

# then set clear text password for Batch session to use

bin/ejbca.sh ra setclearpwd $username $userpass

# and finally reissue the certificate.

bin/ejbca.sh batch

The same can be accomplished using a browser:

Admin GUI - List/Edit End Entities - View_Certificates for user - Revoke the certificate with revocation reason
Admin GUI - List/Edit End Entities - View_Certificates for user - Recover Key, Close
Admin GUI - List/Edit End Entities - Edit_End_Entity for user - Enter new password for user, Save
Public Web - Create Keystore - Enter username and password - Fetch the keystore

Email notifications

Mail settings in JBoss is created when running the 'ant deploy' using the values specified in conf/mail.properties (or default).
It is (automatically) configured in $APPSRV_HOME/server/default/deploy/ejbca-mail-service.xml for JBoss. For other containers you must create a mail service with the same JNDI name as specified in conf/mail.properties.

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:

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

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}
${approvalRequest.ID}
${approvalRequest.ABS.ID}
${approvalRequest.TYPE}
${approvalRequest.APROVEURL}
${approvalRequest.
${approvalRequest.
${requestAdmin.USERNAME}
${requestAdmin.CN}
${requestAdmin.SN}
${requestAdmin.O}
${requestAdmin.OU}
${requestAdmin.C}
${requestAdmin.E}
${approvalAdmin.USERNAME}
${approvalAdmin.CN}
${approvalAdmin.SN}
${approvalAdmin.O}
${approvalAdmin.OU}
${approvalAdmin.C}
${approvalAdmin.E}

= The time the approval request was created = The id of the approval request = The id of the approval request with out any '-' sign, used for presentation purposes. = The type of approval request = A URL to the review approval page with the current request. APPROVALSLEFT} = The number of approvals remaining. APPROVALCOMMENT} = The comment made by the approving/rejecting administrator = The requesting administrator's username = The common name of the requesting administrator. = The common name of the requesting administrator. = The requesting administrator's organization = The requesting administrator's organization unit = The requesting administrator's country = The requesting administrator's email address from Subject DN = The approving administrator's username = The common name of the approving administrator. = The common name of the approving administrator. = The approving administrator's organization = The approving administrator's organization unit = The approving administrator's country = 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

Printing of User Data

From EJBCA 3.4 it is possible to have userdata printed on a printer whenever an end entity is added or edited. The functionality is practically the same as for notifications.

This is configured in the end entity profiles by selecting a printer, the number of copies and uploading a SVG formatted template. There exists a template in 'src/cli/svgTemplate/Batch PIN envelope print.svg' that can be used for testing.

For more information how to write EJBCA SVG templates see: http://docs.primekey.se/documentation/en/appendixes/hardtokenprofiles.html

One good SVG client can be downloaded from inkscape.org

In order to renew the list of available printers you must restart the http session since the list is cached for performance reasons.

Approving Actions

It is possible to have other administrators (1-5) to approve an action in order to make sure the correct data is entered.

Currently are the following actions are enabled for approvals :

Add End Entity
Edit End Entity
Change User Status
Revoke End Entity
Revoke Token (approval for each certificate)
Revoke Certificate
Reactivate Certificate On Hold

In the main menu there is a new option 'Approve Actions' that lets the administrator to search for waiting requests and review its data and finally gives his approval or reject the action.

Configuring Approvals

Approvals are configured for each CA, in the 'edit CA' page. Just select the actions that needs approval and the number of approvers required and save. The actions 'Add End Entity', 'Change End Entity' and 'Change User Status' are all covered by the setting 'Add/Edit End Entity'. 'Revoke End Entity', 'Revoke Certificate', 'Revoke Token' and 'Reactivate Certificate' are covered by setting 'Revocation'.

Authorizing Approving Administrators

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

Using Basic Rule Sets:

Give an admin group the role of SuperAdmin, CAAdmin or RAAdmin with Approve End Entities selected.

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

Using Advanced Rule Sets:

There are three new access rules:

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

Two Different Approval Requests

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

Explanation of approval status

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

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

Approval Notification

EJBCA approval functionality have been enhanced to sent notifications about approval requests.

To enable approval notification go to the system configuration page and check the 'Use Approval Notification' checkbox. You are also required to set the email-address to the approving administrators. This should be a mail-alias to all administrators that should be able to review approval requests and the from address that should be used when EJBCA sends emails.

Then whenever an approval request is created an e-mail is sent both to the requesting admin (if he has an e-mail configured in his user data) and to the approval administrators.

When the approving administrators have recieved the mail, there is a link directly to the approve request page where he can review the requests. When he has approved and rejected the requested all the other administrators in notified about this.

The text of notifications is configured in src/intresources.xx.properties. See the ' Dynamic Substitution Variables' section in this manual for a list of available variables.

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

Framework for External User Data Sources

In EJBCA 3.3 there exists a basic framework of custom user data sources for importing user data from existing databases.

These instructions is intended for EJBCA developers.

Currently there exists a standalone framework for implementing custom user data sources in the same way as for custom publishers. Later on will ready made LDAP and AD userdatasources be implemented to be used out of the box.

A custom userdatasource have two extra fields of data

The first one is a set of CA ids that the userdatasource is applicable to. It can have a constant BaseUserDataSource.ANY_CA.

The second is a set of fields instructing the RA interface GUI which fields that should be modifyable by the RA and which that should be fixed. Important, there is not connection between the user data source, isModifyable data and the end entity profile isModifyable data. The userdata source is only an instruction to the RA gui then when the userdata is added will it be matched against the end entity profile, and it's the data in the end entity profile that really counts.

Tip. The RA gui should read non-modifyable data twice since the RA could change the postdata even if the form have a field as disabled.

To implement a custom user data source do the following:

Create a class implementing the interface org.ejbca.core.model.ra.userdatasource.ICustomUserDataSource containing the methods: init(), fetch() and testConnection(), see org.ejbca.core.model.ra.userdatasource.DummyCustomUserDataSource for an simple example implementation.
Create a jar file containing the class and deploy it to the application server.
Make the user data source available to EJBCA by adding a userdata source, choose 'Custom user data source' as type and enter it's classpath and properties (using the same semantics as a regular java property file).
Now it is possible to fetch userdata from the userdata source from custom implemented webpages using the UserDataSourceSession session bean calling the method java.util.Collection IUserDataSourceSessionLocal.fetch(Admin admin, Collection userdatasourceids, String searchstring) method.

Framework for Reports

Jasper Reports and JFreeChart. The reports function can be accessed from the Admin-GUI under 'Supervisor Functions->Reports'.
JasperReports files can be created using the free tool iReport (http://jasperforge.org/sf/projects/ireport). The report definition file is under src/adminweb/WEB-INF/reports/reports.jrxml. There are a few pre-defined reports, and suggestions for more real-usage reports are welcome.

To create a new report:

Create a report definition file and put in src/adminweb/WEB-INF/reports/*.jrxml
Add a new method generating the report in src/java/org/ejbca/ui/web/admin/reports/ReportsManagedBean.java
Add potential new methods to src/java/org/ejbca/ui/web/admin/reports/ReportsDataSource.java
Edit src/adminweb/reports/resportslist.jsp and add a call to the new method in ReportsManagedBean

Monitoring Services Framework

New to EJBCA 3.4 is a framework for monitoring services, i.e. procedures that should be run on a timely basis. Currently there exists three types of services:

a 'CRL Updater' that automatically updates the CRL.
a 'Certificate Expiration Checker' that checks if a CA have certificates about to expire and sends an email notification to the end user and/or the administrator.
a 'User Password Expire Service' that checks if a user have not enrolled for a new certificate within a certain amount of time after been registered, and expires the users possibility to enroll.

It is also possible to easily write plug-ins for customized services.

A service consists of the components, a worker doing the actual work, an interval determining the time to the next time the service should run and an action (optional) of what should be done if a certain condition occurs.

Currently Available Services

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

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.

For CAs not using soft keystores using the default password, auto-activation is required.

* Intervals *

Periodical Interval

Defines in days/hours/minutes/seconds of how often the worker will be run.

* Actions *

Mail Action

Action that's sends an email notification and have the following settings:

Sender Address - The from-address used in the email.
Receiver Address - The to-address of the email of it isn't specified by the worker.

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.

CustomWorker

A Custom worker must implement the org.ejbca.core.model.services.IWorker interface. But a simpler way is to inherit the BaseWorker class. Then you have to implement one method 'void work()' doing the actual work every time the service framework decides it is time. The work method can make a call to the action (optional) component by 'getAction().performAction(someActionInfo);' The action info can vary depending on the action component but it must implement the ActionInfo interface.

If something goes wrong during the work should a ServiceExecutionFailedException be thrown with a good error message.

See org.ejbca.core.model.services.workers.DummyWorker for an example implementation.

CustomInterval

A Custom Interval must implement the org.ejbca.core.model.services.IInterval interface. But a simpler way is to inherit the BaseInterval class. You then have to implement one method 'public long getTimeToExecution();' which should return the time in seconds until the next time the service is run. Or it should return DONT_EXECUTE it the service should stop running.

See org.ejbca.core.model.services.intervals.DummyInterval for an example implementation.

CustomAction

A Custom Interval must implement the org.ejbca.core.model.services.IAction interface. But a simpler way is to inherit the BaseAction class. Then should only one method be implemented 'performAction(ActionInfo actionInfo)' that should perform the action according to the defined properties and the ActionInfo (all optional). If something goes wrong during the processing of the action should a ActionException be thrown.

See org.ejbca.core.model.services.actions.DummyAction for an example implementation.

Hardware Security Modules (HSM)

EJBCA have support for several HSMs. Each HSM has it's own interface for key generation and maintenance, specific to the HSM and independent of EJBCA. You should make sure you are familiar with how your HSM works.

When configuring a CA to use a HSM in the administration GUI it is a property field where properties unique to this very HSM is specified. All implemented HSM modules are using the same property keywords to define the identity and the purpose of the keys to be used. These keywords are:

certSignKey - the key to be used when signing certificates, can be RSA or ECDSA.
crlSignKey - the key to be used when signing CLSs, can be RSA or ECDSA.
keyEncryptKey - the key to be used for key encryption and decryption, this must be an RSA key.
testKey - the key to be used by HSM status checks, can be RSA or ECDSA.
hardTokenEncrypt - the key to be us

User Guide

About and Installation

Misc information

Administrative tutorials

Administrating EJBCA