Information how to install EJBCA can be found in the Installation guide.
This Administrator Guide is a reference guide to the concepts, configurations and options available in EJBCA.
The guide is targeted for administrators who are responsible for installing, configuring and maintaining EJBCA installations.
More detailed hands on instructions for various day to day administrative tasks can be found in the User Guide.
This guide covers detailed information about using various protocols, hardware security modules etc of EJBCA. These details covers both configuration and usage.
Concepts
Before using this guide you should be familiar with the various concepts, such as certificate and end entity profiles, used in EJBCA.
There is a separate document explaining the different concepts.
Export and import profiles
Certificate and End Entity profiles can be exported as XML files and imported in another instance of EJBCA,
or in the same instance after removal of the old ones.
When exporting profiles (bin/ejbca.sh ca exportprofiles), all profiles will be exported to the specified directory. The
exported files will be given unique names containing profile name and profile id.
When importing profiles the profile name and id will be read from the filename. All profiles present in the specified
directory will be imported.
Fixed profiles will not be exported or imported. If a profiles with the same name as the one being imported already
exist, the profiles will not be imported. References to publishers with unknown id will be dropped.
Import of profiles try to keep the same profile id. If it already exist a profile with the same id in the database,
it will try to choose another and change any (end entity profile to certificate profile) reference during later imports.
The reason the id is kept is that there are references to the profile id from users belonging to the profile.
During import on a new EJBCA instance where CAs that are referenced from the profiles don't exist, a default CA has to be
specified on command line. Two CAs are concidered identical in this context if they have the same subject DN.
Managing CAs
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.
*** Using command line interface ***
To export a CA named "TestCA" to the PKCS#12-file "/path/TestCA.p12" with password "foo123" enter the following
from the $EJBCA_HOME directory:
[user@host ejbca]$ bin/ejbca.sh ca exportca TestCA ./TestCA.p12
Using JBoss JNDI provider...
Enter keystore password: foo123
[user@host ejbca]$
To import the backup keys for "TestCA" later, enter the following from the $EJBCA_HOME directory:
[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]$
Enter the command:
[user@host ejbca]$ bin/ejbca.sh ca importca
to get usage instructions how to import HSM CAs.
*** Using admin-GUI ***
To be able to export and import the CA's keys using the Admin GUI, you have to have superadministrator access.
Make sure that .p12 files are not automatically saved to an unsuitable place by your browser.
before you do an export.
To export a the CA's keys, do the following:
Select "Edit Certificate Authorities" from the administrator menu.
Select the CA you want to export and press the "Edit"-button.
Go to the line where the help-text say "CA export requires the keystore password".
Enter the keystore password in the box to the right of the help-text.
Press the "Export CA keystore.."-button.
The PKCS#12-file will be downloaded by your browser to the location you select.
To import a CA's keys, do the following:
Select "Edit Certificate Authorities" from the administrator menu.
Press the "Import CA keystore.."-button.
Fill out the form with the CA's name, full pathname to the PKCS#12-file and keystore password.
Keep the two "Alias.."-fields to the default value, if you used EJBCA to export the CA's keys.
Press the "Import CA keystore"-button.
Remove and restore CA soft keystore
Soft token CAs can have their keystore removed from the database. When the keystore is removed the
CA can not issue certificates and its CA token status is set to 'offline'.
Warning: Before removing the keystore make sure you have exported it if you would like to be able to
restore it later. See the section 'Export and import CAs'
To remove the catoken keys for "TestCA", enter the following from the $EJBCA_HOME directory:
[user@host ejbca]$ bin/ejbca.sh ca removekeystore TestCA
Using JBoss JNDI provider...
[user@host ejbca]$
To restore the catoken keys again for "TestCA" with the keystore exported as "TestCA-exported.p12", enter
the following from the $EJBCA_HOME directory:
[user@host ejbca]$ bin/ejbca.sh ca restorekeystore TestCA /path/TestCA-exported.p12 SignatureKeyAlias EncryptionKeyAlias
Using JBoss JNDI provider...
Enter keystore password: foo123
[user@host ejbca]$
Renew CAs
You can renew CAs in different ways:
Renew only CA certificate, using the same keys.
Renew CA keys and certificate.
To renew only the CA certificate using the same keys you simply press the button "Renew CA". Your CA have to be on-line for this to work, so it can sign the new certificate if it's a self signed CA or the certificate request if it is a sub CA.
Also if it is a subCA with the rootCA in the same EJBCA instance the root CA must also be on-line.
To renew the CA keys you check the box "Renew keys" and give the CA token authentication code. After this you simply press "Renew CA".
Renewing the keys will not always work if you are using an HSM. It may work with some HSMs and not work with others.
You can report success and failures to us.
When using an HSM you can also make the renewal of keys manually. Simply generate new keys on the HSM with whatever tools you used the first time (preferably the EJBCA cli tools), and then edit the CA token properties
to use the new key. After the new key has been configured you can simply press "Renew CA" (without the renew keys checkbox), to generate your new CA certificate.
Revoke CAs
If you want to revoke a CA you can do so by going to "Edit Certificate Authorities" in the admin GUI. There is a button "Revoke CA".
If you revoke a Root CA it will revoke all certificates in the database issued by the root CA, and create a CRL.
If you revoke a Sub CA it will revoke all certificates in the database issued by the sub CA, and to the sub CA, and create a CRL.
This works automatically if the sub CA and root CA is handled by the same EJBCA instance. If the Sub CA is signed by an external CA, the sub CA's certificate must be revoked by the external CA.
If you revoke an external CA /sub CA to a CA in EJBCA) the external CAs certificate will be revoked and put on the CRL of the issuing CA in EJBCA.
Import users
Users from another CA can be imported with the CLI command:
bin/ejbca.sh ca importcert
You have to give several parameters to the command. Running the command without parameters will print instructions.
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:
bin/ejbca.sh ca createcrl <CA name>
See also the User Guide for details how to configure CRL periods, CRL Distribution Points and CRL Issuers.
There are at least two ways to have EJBCA to periodically create updated CRLs.
CRL Update service worker
In the Admin GUI you can go to 'Edit Services' and add a new service. Edit the service and select the 'CRL Updater'
worker and the interval you want to use. Don't forget to set the service to 'Active'.
Now this service will run with the interval you have configured and generate CRLs according to the settings for each CA.
Cron job
Yet another way to generate CRLs way is to have a cron job or equivalent call 'bin/ejbca.sh ca createcrl'.
The 'createcrl' command will then check all active CAs if it is a need to update their CRLs,
otherwise nothing is done.
If you want to force CRL generation for a CA, use 'bin/ejbca.sh ca createcrl caname'
Example crontab entry:
PATH=$PATH:/usr/java/jdk1.6.0_24/bin
@daily cd /home/ejbca;/home/ejbca/bin/ejbca.sh ca createcrl;
where '/usr/java/jdk1.6.0_24/bin' is the path to where 'java' can be found.
'/home/ejbca' is where ejbca is installed.
Sample crontab to be installed with 'crontab -e':
SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
CLASSPATH=$CLASSPATH:/root/ejbca
APPSRV_HOME=/usr/local/jboss
# m h dom mon dow command
00 0 * * * cd /root/ejbca;./bin/ejbca.sh ca createcrl
Delta CRLs
EJBCA can issue delta CRLs.
In the CA configuration, set 'Delta CRL Period' to the amount of time your delta CRLs will be valid if delta CRLs are issued.
Command line interface and CRL Update service will generate delta CRLs if 'Delta CRL Period' is larger than 0.
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 Oracle 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):
EJBCA implements features from (at least) draft 11 of the SCEP specification. 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.
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.
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
*** iPhone/iOS ***
You can enroll certificates for the iOS directly with EJBCA using SCEP. There is a SCEP profile in the iPhone that you can use for this.
PrimeKey has created a detailed howto that you can purchase easily.
*** 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:
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 ***
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).
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 API SCEP module.
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
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)
Revocation request (rr)
NestedMessageContent (nested)
Key Update Request (kur)
Certificate requests use the CRMF (RFC4211).
EJBCA can work in two modes with CMP:
Client mode - This is the default mode. Client mode works like any other enrollment in EJBCA. When a request comes in EJBCA verifies the request (see User authentication below)
and issues a certificate to a user that has been previously registered in EJBCA.
RA mode - 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,
but when authenticated RA CMP messages arrive a user is created in EJBCA and a certificate is issued.
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).
CMP and 3GPP/4G/LTE configuration guide
PrimeKey has created a detailed CMP configuration guide, with details how to
configure EJBCA for 3GPP/4G/LTE networks using CMP. You can purchase it easily in the PKI Shop.
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.
When re-deploying EJBCA this will start a TCP listener on the default port for CMP over TCP. You must run the application server as root to use the default port, since it is a low port (<1024).
See the documentation in conf/cmp.properties for information about configuration options for TCP. We recommend using a non standard port > 1024.
CMP Message Authentication
EJBCA supports 4 modules for message authentication. Which modules to use can be set in the properties file in the option "cmp.authenticationmodule" and the parameters required by each module are
set in the option "cmp.authenticationparameters".
The four supported modules are either password extractors or PKIMessage verifyers:
The password extractors are:
RegTokenPwd: Extracts the password from the CMP request.
DnPartPwd: Extracts the password from the subjectDN of the user the request concerns.
The PKIMessage verifyers are:
HMAC: To authenticate the message, this module uses:
A global shared secret specified in properties file under cmp.ra.authenticationsecret
If there was no global shared secret, it will extract the CMP authentication secret specified in the CA
In client mode, in case there was no CMP secret specified in the CA, the pre-registered end entity, that sent the request, will be looked up in the database, and if there was a clear text password there,
this password will be used to authenticate the message
EndEntityCertificate: When this module is used, the request sender should attach his certificate to the extraCert parameter in the PKIMessage and then sign the message with his private key. EJBCA will
then check if the certificate in extraCert does exist in its database and verifies the message signature. In order for this CMP request to be processed, the request sender should be a registerd
administrator in EJBCA with the right authorizations to perform the operations required in the request
For details about how to set which modules to use and their parameters, see the documentation in the properties file.
Client mode for CMP
Client mode is used when the CMP client will act as an End Entity to EJBCA. this means that the End Entity must be pre-registered in EJBCA and that the client request is authenticated
with this pre-registered end entity before a certificate is issued. This is the same authentication model as for regular enrollment, i.e. browser enrollment, using a username/password combination.
The users DN is deducted from the request according to rules configured.
The username in EJBCA must be pre-registered.
The password for the user in EJBCA must be passed in the request (one-time password).
If the Certificate Profile allows it, keyUsage, validity and extensions are also taken from the CertTemplate in the request message.
Signature POPO is used.
After the user has been authenticated in EJBCA, a certificate is generated as usual and sent back to the client.
To use client mode, no particular configuration is needed, since this is the default mode.
*** 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.
RA mode for CMP
RA mode is used when the CMP client will act as an RA to EJBCA. When the RA sends a certificate request to EJBCA, no user 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, validity and extensions are also taken from the CertTemplate in the request message.
raVerify POPO is used.
Messages are authenticated using PasswordBasedMac, using a shared secret between the CA and the RA.
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, see the documentation for the options in conf/cmp.properties.sample.
*** Multiprotection support ***
In RA mode, it is also possible to send a CMP request with multiple signatures. Ejbca implements this feature following the specifications
in RFC4210. In cases where an end entity sends a protected PKI message to an RA, the RA forwards that message to a CA, attaching its own signature for protection.
This is accomplished by nesting the entire message sent by the end entity within a new PKI message.
Sample code for a signature protected NestedMessageContent message:
String subjectDN = "CN=bogusSubjectNested";
final byte[] nonce = "sendernonce".getBytes();
final byte[] transid = "trandis".getBytes();
PKIMessage crmfMsg = createCrmfReq();
//Signing crmfMsg
KeyPair eeKeys = getAdminKeys();
Certificate adminCert = getAdminCertificate();
ByteArrayInputStream bIn = new ByteArrayInputStream(adminCert.getEncoded());
ASN1InputStream dIn = new ASN1InputStream(bIn);
ASN1Sequence extraAdminCertSeq = (ASN1Sequence)dIn.readObject();
X509CertificateStructure extraCert = new X509CertificateStructure(ASN1Sequence.getInstance(extraAdminCertSeq));
crmfMsg.addExtraCert(extraCert);
final Signature sig = Signature.getInstance(PKCSObjectIdentifiers.sha1WithRSAEncryption.getId(), "BC");
sig.initSign(eekeys.getPrivate());
sig.update(crmfMsg.getProtectedBytes());
byte[] eeSignature = sig.sign();
crmfMsg.setProtection(new DERBitString(eeSignature));
PKIHeader myPKIHeader = new PKIHeader(new DERInteger(2), new GeneralName(new X509Name(subjectDN)), new GeneralName(new X509Name(((X509Certificate)cacert).getSubjectDN().getName())));
myPKIHeader.setMessageTime(new DERGeneralizedTime(new Date()));
// senderNonce
myPKIHeader.setSenderNonce(new DEROctetString(nonce));
// TransactionId
myPKIHeader.setTransactionID(new DEROctetString(transid));
PKIBody myPKIBody = new PKIBody(crmfMsg, 20); // NestedMessageContent
PKIMessage myPKIMessage = new PKIMessage(myPKIHeader, myPKIBody);
//Signing myPKIMessage
KeyPair raKeys = getRAKeys();
final Signature sig = Signature.getInstance(PKCSObjectIdentifiers.sha1WithRSAEncryption.getId(), "BC");
sig.initSign(rakeys.getPrivate());
sig.update(myPKIMessage.getProtectedBytes());
byte[] eeSignature = sig.sign();
myPKIMessage.setProtection(new DERBitString(eeSignature));
final ByteArrayOutputStream bao = new ByteArrayOutputStream();
final DEROutputStream out = new DEROutputStream(bao);
out.writeObject(myPKIMessage);
final byte[] ba = bao.toByteArray();
// Send request and receive response
final byte[] resp = sendCmpHttp(ba, 200);
*** 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.
Edit each CAs that should be used for CMP certificate issuance and enter new CMP RA Authentication Secret.
The global secret in cmp.properties has to be commented out (and applied to EJBCA by rebuilding and redploying).
#cmp.ra.authenticationsecret=
This property will otherwise override the CA specific configuration.
Key Update Request (kur)
Also known as the Certificate Update request. When a key pair is due to expire, the relevant end entity may request a key update. The CMP request is signed
and the sender attaches their certificate in the extraCert field in the CMP message.
*** In Client Mode ***
In client mode, the only end entity that is allowed to send a KeyUpdate request is the end entity that owns the certificate to be renewed. This end entity
should be the one signing the request and attaching its "old" certificate (that has not been expired yet) to the CMP message. The CA will only look into the
certificate in extraCert to find which certificate is to be updated.
*** In RA Mode ***
In RA mode, an administrator is allowed to send a KeyUpdate request on behalf of an end entity. The adminstrator should be the one signing the request and
attaching his own certificate to the CMP message. Either only the subjectDN or both the subjectDN and the issuerDN of the certificate to be updated
are specified in the CertificateTemplate field in the CMP message.
In order for this request to succeed, the administrator sending the update request has to be authorized to perform this operation.
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/cmp.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).
signature with POPOSigningKeyInput - where the PublicKey and subject DN is in POPOSigningKeyInput, possibly just copied from the CertTemplate. The signature is calculated over the POPOSigningKeyInput (if the values are also in the CertTemplate they must be identical).
Currently these are the POPOs supported by EJBCA, so if you don't use raVerify or signature your request will fail because POPO is not verified.
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
*** RSA jCert ***
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.
*** AET BlueX ***
CMP has been tested with BlueX from AET Europe. From EJBCA's point of view BlueX functions as an RA with the same configuration
options as for jCert.
*** Aventra ***
CMP has been tested with Aventra card management system. Same configuration as above.
*** Novosec BC extension ***
For internal testing a modified version of the Novosec extension to BouncyCastle is used.
An old test program for running CryptLib against EJBCA can be downloaded here.
*** BouncyCastle ***
CMP has been tested with BouncyCastle CMP classes, available in BC 1.46 or later. Both client and RA mode should work.
Sample code for a HMAC protected (RA mode) message:
CertificateRequestMessageBuilder msgbuilder = new CertificateRequestMessageBuilder(BigInteger.valueOf(certReqId));
X509NameEntryConverter dnconverter = new X509DefaultEntryConverter();
X500Name issuerDN = X500Name.getInstance(new X509Name("CN=AdminCA1").toASN1Object());
X500Name subjectDN = X500Name.getInstance(new X509Name("CN=user", dnconverter).toASN1Object());
msgbuilder.setIssuer(issuerDN);
msgbuilder.setSubject(subjectDN);
final byte[] bytes = keyPair.getPublic().getEncoded();
final ByteArrayInputStream bIn = new ByteArrayInputStream(bytes);
final ASN1InputStream dIn = new ASN1InputStream(bIn);
final SubjectPublicKeyInfo keyInfo = new SubjectPublicKeyInfo((ASN1Sequence)dIn.readObject());
msgbuilder.setPublicKey(keyInfo);
GeneralName sender = new GeneralName(subjectDN);
msgbuilder.setAuthInfoSender(sender);
// RAVerified POP
msgbuilder.setProofOfPossessionRaVerified();
CertificateRequestMessage msg = msgbuilder.build();
GeneralName recipient = new GeneralName(issuerDN);
ProtectedPKIMessageBuilder pbuilder = new ProtectedPKIMessageBuilder(sender, recipient);
pbuilder.setMessageTime(new Date());
// senderNonce
pbuilder.setSenderNonce(senderNonce);
// TransactionId
pbuilder.setTransactionID(transactionId);
// Key Id used (required) by the recipient to do a lot of stuff
pbuilder.setSenderKID("KeyId".getBytes());
org.bouncycastle.asn1.crmf.CertReqMessages msgs = new org.bouncycastle.asn1.crmf.CertReqMessages(msg.toASN1Structure());
org.bouncycastle.asn1.cmp.PKIBody pkibody = new org.bouncycastle.asn1.cmp.PKIBody(org.bouncycastle.asn1.cmp.PKIBody.TYPE_INIT_REQ, msgs);
pbuilder.setBody(pkibody);
JcePKMACValuesCalculator jcePkmacCalc = new JcePKMACValuesCalculator();
final AlgorithmIdentifier digAlg = new AlgorithmIdentifier("1.3.14.3.2.26"); // SHA1
final AlgorithmIdentifier macAlg = new AlgorithmIdentifier("1.2.840.113549.2.7"); // HMAC/SHA1
jcePkmacCalc.setup(digAlg, macAlg);
PKMACBuilder macbuilder = new PKMACBuilder(jcePkmacCalc);
MacCalculator macCalculator = macbuilder.build("password".toCharArray());
ProtectedPKIMessage message = pbuilder.build(macCalculator);
Sample code for a signature protected (Client mode) message:
CertificateRequestMessageBuilder msgbuilder = new CertificateRequestMessageBuilder(BigInteger.valueOf(certReqId));
X509NameEntryConverter dnconverter = new X509DefaultEntryConverter();
X500Name issuerDN = X500Name.getInstance(new X509Name("CN=AdminCA1").toASN1Object());
X500Name subjectDN = X500Name.getInstance(new X509Name("CN=user", dnconverter).toASN1Object());
msgbuilder.setIssuer(issuerDN);
msgbuilder.setSubject(subjectDN);
final byte[] bytes = keyPair.getPublic().getEncoded();
final ByteArrayInputStream bIn = new ByteArrayInputStream(bytes);
final ASN1InputStream dIn = new ASN1InputStream(bIn);
final SubjectPublicKeyInfo keyInfo = new SubjectPublicKeyInfo((ASN1Sequence)dIn.readObject());
msgbuilder.setPublicKey(keyInfo);
GeneralName sender = new GeneralName(subjectDN);
msgbuilder.setAuthInfoSender(sender);
Control control = new RegTokenControl("foo123");
msgbuilder.addControl(control);
Provider prov = Security.getProvider("BC");
ContentSigner popsigner = new JcaContentSignerBuilder("SHA1withRSA").setProvider(prov).build(keyPair.getPrivate());
msgbuilder.setProofOfPossessionSigningKeySigner(popsigner);
CertificateRequestMessage msg = msgbuilder.build();
GeneralName recipient = new GeneralName(issuerDN);
ProtectedPKIMessageBuilder pbuilder = new ProtectedPKIMessageBuilder(sender, recipient);
pbuilder.setMessageTime(new Date());
// senderNonce
pbuilder.setSenderNonce(senderNonce);
// TransactionId
pbuilder.setTransactionID(transactionId);
org.bouncycastle.asn1.crmf.CertReqMessages msgs = new org.bouncycastle.asn1.crmf.CertReqMessages(msg.toASN1Structure());
org.bouncycastle.asn1.cmp.PKIBody pkibody = new org.bouncycastle.asn1.cmp.PKIBody(org.bouncycastle.asn1.cmp.PKIBody.TYPE_INIT_REQ, msgs);
pbuilder.setBody(pkibody);
ContentSigner msgsigner = new JcaContentSignerBuilder("SHA1withRSA").setProvider(prov).build(keyPair.getPrivate());
ProtectedPKIMessage message = pbuilder.build(msgsigner);
This requests a certificate, defining the subject DN that will be used. The CA used to sign the certificate is specified in the EJBCA cmp configuration, and can be taken from the keyid.
EJBCA authenticated the request using the HMAC protection with the password, and accepts any request upon correct authentication. See the CMP documentation above for more advanced configuration.
Client mode
Cmpforopenssl works with with EJBCA in client mode with the following EJBCA configuration (cmp.properties, unset properties = default):
This requests a certificate, and the requested subject DN must match the registered subject DN.
EJBCA authenticates the request using the HMAC protection with the password of the registered user. See the CMP documentation above for more advanced configuration.
Custom handling of certificate request
It is possible to add a custom plug-in class to handle a certificate request.
The class implementing this plug-in must implement the org.ejbca.core.protocol.ExtendedUserDataHandler interface.
The idea is that the implementation uses information from the certificate profile or name and the request itself to manipulate the request before it is processed the normal way. This is done when 'processRequestMessage' (see source code of the interface) is called. The used certificate profile name is passed as 'otherData'.
Set the property cmp.certreqhandler.class in $EJBCA_HOME/conf/cmp.properties to the name of the plug-in class to enable it. You may then add additional properties that you can use in your implementation.
In EJBCA there is already an implementation included. This implementation writes to the unid-fnr DB (see separate unid document). To activate this plug-in just uncomment the cmp.unidclass property line and also set the data source on the following line.
CMP Proxy
In some installations it may be desirable to terminate the client connection in a DMZ before connecting further to the CA. In this case the client never has a direct
network connection to the CA machine. In such a scenario you can use the CMP proxy module. Clients use the CMP proxy, as it would otherwise use EJBCA.
The proxy in turn connects to EJBCA gets the answer and forwards it back to the client.
The proxy is a stand alone module that runs on another mahing than the CA itself.
See EJBCA_HOME/modules/cmpProxy/resources/README for information how to build and use the proxy.
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.
The OCSP servlet receives OCSP request by http(s) and send back a status response signed by the CA.
The OCSP service receives 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.
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'.
You can configure the CA which will generate responses when no real CA can be found from the request by setting
'ocsp.defaultresponder' in conf/ocsp.properties. 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. This value 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):
If Firefox 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 Firefox
'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, Firefox 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 Firefox 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 is a common setup, if the CA only issues certificates once every year
for one million users, this does not put much pressure on the CA, but the OCSP responders can be put under high load continuously.
See the OCSP Installation document for information how to set up stand-alone, separated OCSP responders.
Simple OCSP client
To try out and test your OCSP installation you can use the EJBCA client toolbox, (see below). You can also use the API directly from your
java program.
Adobe Reader
A good example of using OCSP is to check digitally signed PDF documents using Adobe Reader.
To be able to verify certificates in Adobe Reader, you must first add the CA certificate as trusted in Adobe Reader.
You can do that in the menu Document->Trusted Identities. Choose Certificates in the drop-down list and click 'Add contacts',
now you can browse to the CA-certificate that you have downloaded in DER format (for example by choosing download to IE on the public EJBCA pages).
The CA certificate must have been saved with a name ending with '.cer'.
After adding the new contact, you have to click 'Edit trust' and check at least 'Signatures and as trusted root' and 'Certified documents'.
This works the same using both internal and external OCSP responders.
Certificates that have an 'OCSP service locator' will be verified against the OCSP responder.
You can configure this in the certificate profile used to issue certificates.
If you sign PDF documents with embedded OCSP responses those responses must include a nextUpdate field, and the timestamp must be within the thisUpdate and nextUpdate
period of the OCSP response.
EJBCA Web Service Interface
EJBCA 3.4 introduced the JAX-WS 2.0 Web Service Interface used to access the basic functions remotely over client
authenticated HTTPS. The functionality currently available through the Web Service Interface are documented in the
EJBCA Web Service API Reference.
There is also a CLI that can be used for scripting WS calls remotely. See following section for more information.
Note: All web service calls are not available through the CLI.
If you are running on JBoss 5.x, make sure that you configured JBoss WS correctly as described in the installation document.
Web Services authentication
The Web Services interface requries client certificate authentication from administrators, in the same way as the admin GUI does.
If you have a client certificate the works on the admin GUI you should also be able to use it for the web service interface.
Configuring Web Services behavior
The sample property file conf/jaxws.properties.sample contains more information on how to configure the behaviour of
the EJBCA WS. Copy this to conf/jaxws.properties, edit and redeploy.
If the end entity profile informations must be used to define default values when you create a user, the flag "Allow
merge DN Webservices" must be checked in the end entity profile.
If multiple instances of a component exist, the merge is done from end to begining, and the remaining values of this component type will be placed at the end.
For example, if you want to merge:
Edit dist/ejbca-ws-cli/ejbcawsracli.properties before running the EJBCA WS CLI. This files contains descriptions of
what can be configured. Please note that this directory is recreated each time you build EJBCA, so copy it to a
separate location if you intend to rebuild or redeploy EJBCA and keep the configuration.
Configuration for the Web Services CLI requires a P12 or JKS keystore. You can easily try the WS CLI using the
superadmin.p12 keystore generated during the installation or generate a new JKS using the Admin GUI.
Below is a short description how to create a JKS for a user on the command line, and adding the new user to the superadministrator admin group.
bin/ejbca.sh ra adduser <1> <2> "C=..,O=..,CN=<1>" null AdminCA null 1 JKS
bin/ejbca.sh ra setclearpwd <1> <2>
bin/ejbca.sh batch <1>
bin/ejbca.sh admins addadmin "Temporary Super Administrator Group" AdminCA WITHCOMMONNAME EQUALCASEINS <1>
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 or P12 file with
the appropriate access rights (See the Using API section for details) and
finally configure the file ejbcawsracli.properties. In this file you should specify
the hostname of the CA server, the name of the keystore and the password to unlock it.
Documentation for each setting is in the file ejbcacsracli.properties.
Use 'ejbcaClientToolBox.sh EjbcaWsRaCli' for a list of each subcommand and 'ejbcaClientToolBox.sh EjbcaWsRaCli "subcommand"'
for detailed help how to use the cli.
Example usage:
ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req testuser2 foo123 2048 NONE tmp
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):
/ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity
/ca_functionality/create_certificate
revokeCert, revokeToken: These calls support approvals.
/ra_functionality/revoke_end_entity
/ra_functionality/'end entity profile of the user owning the cert'/revoke_end_entity
revokeUser: This call support approvals.
/ra_functionality/revoke_end_entity
/ra_functionality/'end entity profile of the user'/revoke_end_entity
/ra_functionality/delete_end_entity (only if users should be deleted)
/ra_functionality/'end entity profile of the user'/delete_end_entity (only if users should be deleted)
fetchUserData:
It is possible to turn of authorization of this call in the jaxws.properties
/userdatasourcesrules/'user data source'/fetch_userdata
genTokenCertificate:
Important this call also supports approvals, and the default behaviour is when
someone without the '/administrator' access is creating a call then will a GenerateTokenApprovalRequest
be created. This behaviour can be turned off in the jaxws.properties file.
/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 (must be configured in advanced mode when editing access rules)
deleteUserDataFromSource:
/userdatasourcesrules/'user data source'/remove_userdata (for all the given user data sources)
getCertificate:
no requirement of the '/administrator' flag
/ca_functionality/view_certificate
caCertResponse, caRenewCertRequest:
/ca_functionality/renew_ca
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 :
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 that 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 implemented. 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.
When building EJBCA with XKMS enabled, a XKMS CLI tool is also generated. The tool is placed
in the directory dist/ejbca-xkms-cli 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 link to the report will be shown.
External RA API
Information on how to use the External RA API is available here.
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. Use a keystore type other than 'User Generated', for example P12.
Enroll the user with 'Create keystore' in Public Web.
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:
# Mark the generated 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 $username
The same can be accomplished using a browser:
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 (user status should now be 'Key Recovery')
Public Web - Create Keystore - Enter username and password - Fetch the keystore.
Technical details
What the operation "bin/ejbca.sh ra keyrecovernewest", or "recover key" in the Admin GUI, or keyRecoverNewest in the WS API actually does is
that it marks the user/certificate for key recovery. This means that the next time you make a call to generate a keystore (p12/jks/pem)
for the user the CA will get the private key, held encrypted in the recovery database, and the existing user certificate or a new certificate, and
create a keystore for the user with this old key pair.
The actual recovery would then happen when you make a call to i.e. pkcs12Req in the WS API, or if keystore type is P12, JKS or PEM in the Admin GUI.
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.
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 user's username
${PASSWORD} or ${user.PASSWORD} = The user's password
${UID} or ${user.UID} = The user's unique identifier
${CN} or ${user.CN} = The common name of the user.
${SN} or ${user.SN} = The serial number (in DN) of the user.
${O} or ${user.O} = The user's organization
${OU} or ${user.OU} = The user's organizational unit
${C} or ${user.C} = The user's country
${user.E} = The user's email address from Subject DN
${user.EE.EMAIL} = Ther user's email address from the End Entity data
${user.SAN.EMAIL} = The user's email address from Subject Alternative Name, RFC822Name field
${user.TIMECREATED} = The time the user was created
${user.TIMEMODIFIED} = The time the user was modified
${requestAdmin.CN} = The common name of the requesting administrator
${requestAdmin.EE.EMAIL} = The email address of the administrator adding the end entity according to the administrator's End Entity data
${requestAdmin.SAN.EMAIL} = The email address of the administrator adding the end entity according to the administrator's Subject Alternative Name, RFC822Name field
${approvalAdmin.XX} variables from below can be used to get the administrator who adds an end entity.
Variables used with approvals:
${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:
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.
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).
To: ca-team@foo... **
Email notification of the issuing to the auditor
mailing lists - without above username/password.
Printing of User Data
User data can be sent to 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://wiki.ejbca.org/ (Administration->hardtokenprofiles).
A 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 Certificate Authorities' page and for each certificate profile in
the 'Edit Certificate Profiles' 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'.
Approvals will be required if the CA or the certificate profile enforces it and in case the number of approvers differs
between the CA and the certificate profile the largest number of approvers will be used.
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.
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 the requesting administrator is supposed to poll the
approval request if it has been approved or not. These requests are called 'Non-Executable Action Requests'.
Explanation of approval status
Here follows an explanation of what the different approval requests statuses.
Waiting: Means that the action request is waiting to be processed by authorized administrators, request are
valid for the time specified 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 do not have any expire time. This means that the requesting
administrator can apply again directly after the rejection.
Approval Notification
EJBCA approval functionality have been enhanced to 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/intresources.xx.properties. The relevant properties starts with "notification". See the ' Dynamic Substitution Variables' section in this manual for a list of available variables.
Remember to configure mail-server settings in the mail.properties file.
Self Registration
It is possible to allow users of the public web to create approval requests for new end-entities (under 'Request Registration'). The users' choice of end-entity type and DN fields is confined, for instance it could be limited to end-user certificates with only the name and e-mail fields being available. The DN fields can then be verified by an administrator.
Note the following properties of the basic solution:
The approval process verifies end entity account creation.
The approval process does not verify CSR public key binding to a specific end entity.
Possible usages of self registration includes an almost unlimited set of use cases. The default solution is suitable and configurable for a large set of these use cases, and can function as a platform to customize other
more specialized use cases. Customization of self registration work flows is a pretty straight forward process.
Configuration
Setting up self registration consists of three steps: creating end-endity and certificate profiles that should be available, configuring email notifications, and configuring self registration in web.properties.
First, at least one end-entity profile should be created as follows:
The SubjectDN and SubjectAltName fields that should be available must be added. Fields that are marked as modifiable can be modified freely, otherwise only pre-defined values can be selected by the user. See the user guide for further information.
The user's e-mail can be verified by sending an auto-generated password to it (but this is not the only way to verify the user). The email domain field must be enabled with the Use checkbox, and auto-generated passwords must be enabled. Optionally the domain field may be constrained to particular choices, see the user guide section on end-entity profiles.
E-mail validation works by sending the password in a notification message. For this reason, Send Notification must be enabled (check Use and Default), and the other notification fields below it should be filled in. See the section on email notifications.
By the default the user will be prompted to fill in the username, but the username can also be generated from a field in the end-entity profile such as CN (common name), see below.
Note that sending of a password in an email is not the only way to do things. You can for example use multiple notifications where an enrollment link is sent to the user, but the password is sent to an administrator, or an out-of-band delivery service (through local email), or printed on paper. The solutions are highly configurable and adaptable.
E-mail sending must be configured in mail.properties to work. You may also want to enable notifications to the administrators when there are new approval requests, under System Functions / System Configuration.
To make the end-entity profiles available in the user interface, certificate types must be added in web.properties using the web.selfreg.certtypes.<identifier>.* properties (the identifier can be chosen arbitrarily). Each certificate type defines an end-entity profile and a certificate profile, and what name should be displayed in the user interface. If the username should be generated from a field, then this can be configured using the usernamemapping sub-property. Finally, to enable self registration, the property web.selfreg.enabled must be set to true.
Note that the approval requests will be shown in the administration GUI as coming from a Command Line Tool. This is normal, since all actions that aren't initiated by an administrator are shown as coming from the command line.
Framework for External User Data Sources
A basic framework for importing user data from existing databases exists. The intention of this
framework is to be able to import user the user data from an LDAP and AD, but currently no such
implementations exist or any way to use such implementation from the Admin GUI. The rest of this
section is intended for EJBCA developers.
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.
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
UserDataSourceSessionBean.fetch(Admin admin, Collection<Integer> userdatasourceids, String searchstring) method.
Services Framework
EJBCA has a framework for timer services, i.e. procedures
that should be run on a timely basis. Currently there exists five 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.
a 'Renew CA Service' that checks if CA certificates are about to expire and renews them.
a 'Publisher queue process service' that retries failed publishing.
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.
Configuration
*** Workers ***
The worker is the class that will be executed when the service runs. Each worker can have different worker specific configuration.
*** Intervals ***
Periodical Interval
Defines in days/hours/minutes/seconds of how often the worker will be run. A worker should never be configured to run more often than the time a single invocation takes.
*** Actions ***
Mail Action
Action that sends an email notification when the service is executed 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.
*** Pin to Specific Node(s) ***
With this option, it is possible to choose on which nodes the service is allowed to execute. By not choosing any nodes in the list the service can be executed on any of the nodes.
On startup of EJBCA each node adds its hostname to the list of nodes. The list can also be manually edited on the System Configuration page.
Implementation details
A service worker should never run simultaneously on two nodes, or simultaneously on one node.
To avoid running more than one instance on a single node there is a semaphore that inhibits more than one
instance of the worker to run in a single JVM. If a worker starts and another worker is already running
the worker is rescheduled to run on the next planned interval, and immediately terminated.
To avoid running any two services on two nodes simultaneously, the service have a time stamp that is set when it runs, and
schedules the next run before the actual work is started. This time stamp makes it possible for another node to determine of
the service is already running on another node and not start running.
In practice what this leads to is that a service will always run on a single node, the same node every time.
Currently Available Services
CRL Update Service
The CRL Updater checks if any of the configured CAs need a new CRL and updates it if necessary. The worker have no
additional settings and only supports the periodical interval and no action.
Certificate Expiration Check Service
A worker that checks if a CA have certificates about to expire and sends an email
notification the the end user and/or administrator.
The worker have the following settings:
CAs to Check - Select here which CAs that should be searched for expiring certificates.
Certificate Profiles to Check - If any certificate profile is selected from this list, the notification service will require that
certificates are issued by the selected CAs AND that they are issued using one of the selected certificate profiles. Leaving this list empty will
cause the service to search for certificates just based on the CA selection.
Time before notification is sent - The number of Days/Hours/Minutes/Seconds that should
remain of the certificates validity before the notification is sent.
Send notification to end user - Check this if a notification should be sent to
the owner of the certificate. Observe that the end user must have an email set in
the user database (not necessarily in the certificate) in order for the service to
send the notification.
Notification Subject to End User - The e-mail subject.
End User Message - Message body of the notification. Substitution
variables can be used here as defined in the 'Email Notifications' section.
Send notification to Administrator - Check this if a notification should be sent
to some defined administrator-mail address. The address of the administrator is
configured in the Mail Action component.
Notification Subject to Administrator - The e-mail subject.
Administrator Message - Message body of the notification. Substitution
variables can be used here as defined in the 'Email Notifications' section.
Note: you may configure multiple certificate expiration services set with different
Time before notification is sent values in order to further alert the user or administrator
that a certificate is about to expire.
User Password Expire Service
A worker that checks if a user has not enrolled for a new certificate within a specified amount of time
after the user was last edited. If the user has not enrolled within this time, the user's status is set to
Generated and the user will not be able to enroll.
The worker have the same basic setting as the 'Certificate Expiration Check Service', except for
'Time before notification is sent' which is replaced by:
Time until user password expire - The number of Days/Hours/Minutes/Seconds that a user should be able to
enroll for a certificate, i.e. the time before the user's password expire.
Renew CA Service
The renew CA service can be used to automatically renew CAs that are about to expire. This might be used for SubCAs that
are valid only short periods of time. The specific settings are:
CAs to Check - which CAs should be checked, and renewed if they are about to expire.
Time before CA expires to renew - the amount of time before the CA actually expires that the service should renew the CA.
For CAs using soft keystores and not using the default password, auto-activation is required.
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.
Note
If you run one service for each publisher you should onle configure one publisher in every service. Do not let two services handle the same publisher.
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.
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 if the service should stop running.
See org.ejbca.core.model.services.intervals.DummyInterval for an example implementation.
CustomAction
A Custom Action must implement the org.ejbca.core.model.services.IAction interface.
A simpler way is to inherit the BaseAction class. Then only the method 'performAction(ActionInfo actionInfo)' needs to
be implemented. The methods 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 used for hardtoken encryption and decryption. PUK will be decrypted by this key.
defaultKey - the key to be used when no other key is defined for a purpose. If this is the only definition then this key will be used for all purposes.
pin - optional pin code used for auto-activation of CA token, see below. Not recommended for high security set-ups, but very useful in some cases.
You may omit defaultKey if you want to be sure that the right key is used, but then all the other keys must be specified. It's recommended that the certificate and CRL signing keys are linked to the same key since different keys are rarely supported by verifying applications.
When implementing support for a new HSM the 'KeyStrings' class could be used to manage the key properties described above. When it is an JCA/JCE API for the HSM it could also be wise to extend the BaseCAToken class.
The same activation code must be used for all keys used by a CA.
There are four additional key properties that can (optionally) be used when renewing CA keys and to produce roll-over certificates..
previousCertSignKey - this is the alias of the previous signature key, as opposed to 'certSignKey' which is the current signature key.
previousSequence - this is the sequence identifying the previous signature key, as opposed to the current sequence that is held in the CA token.
This sequence will replace the current sequence in the caRef field when signing a request with the CAs previous key.
nextCertSigningKey - this is the alias of a new generated key on the HSM. When updating a CA signed by an external CA this is used to send a request,
but the CA is still active using the old key. When the certificate response is received this key is activate and moved to certSignKey/crlSignKey.
nextSequence - this is the sequence identifying the next signature key.
Supported and tested HSMs are described below, with sample configurations and HSM specific documentation.
Since EJBCA 3.6 the recommended HSM connector is to use the PKCS#11 interface. Older JCE implementations will gradually be deprecated and removed.
PrimeKey Solutions is selling a module called PrimeCardHSM that implements a flexible HSM using low cost smart cards.
ant clientToolBox
cd dist/clientToolBox
./ejbcaClientToolBox.sh PKCS11HSMKeyTool test
The command will give further instructions about the parameters requires, PKCS#11 library and slot.
Auto-activation of 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 (obfuscated) one.
pin foo123
pin 6bc841b2745e2c95e042a68b4777b34c
These two properties contains the same password. The obfuscated pin value can be obtained with the command 'bin/ejbca.sh encryptpwd':
$ bin/ejbca.sh encryptpwd foo123
Using JBoss JNDI provider...
Please note that this encryption does not provide absolute security, ....
Enter word to encrypt:
hidden
Encrypting pwd...
6bc841b2745e2c95e042a68b4777b34c
NOTE: This obfuscated is not high security encryption, it is only meant to protect the password for accidental viewing.
The obfuscated algortihm uses a built 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 obfuscated 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. You have to check if that support is available.
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.
But only one of 'slot' or 'slotListIndex' should exist.
Optionally a few extra properties fields can be used:
attributesFile - a file specifying PKCS#11 attributes (used mainly for key generation).
keyspec - key specification used when generating new HSM keys from within the admin GUI. Keyspec that is used as first choice when generating new keys in the GUI of form "1024" for RSA keys, "DSA1024" for DSA keys and secp256r1 for EC keys.
If keyspec is not given EJBCA tries to generate a key with the same specification as the current cert signing key.
Attributes file is in the format specified in the JavaTM PKCS#11 Reference Guide and the examples further down in this file.
Before there was no default used when no 'attributesFile' existed and HSM specific defaults was used instead. For most HSM these defaults was not usable and the file was needed. Often only the values needed to be changed from the HSM default was specified. But now there is a built in defaults used when the file is missing. These defaults works for most HSM and looks like this:
Only occasion we know that the default is not working is when the module protected slot of an nCpher HSM is used; then the file must exist and have 'CKA_PRIVATE = false' (see below).
Note
If you are using an attributesFile and have more than one CA using the same slot it is very important that BOTH CA token properties configurations contains the attributesFile.
This is because the attributes are applied when the provider is installed during startup. If one configuration does not have the attributesFile it can not be applied later on by the other configuration.
The tool "EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool" is used administrate and generate keys. Use it without parameters to get all valid options.
Keys may be generated in two ways. Examples:
The first example is using built in default and are then using specified slot and PKCS#11 library.
The second is using a configuration file.
The contents of the file is specified in the PKCS#11 wrapper documentation from Oracle.
Often it is enough to use the default but with some HSM it necessary to define some PKCS#11
attributes for the generated key.
Below is an example how the hsmp11.conf could look like. Before this was a recommendation for SafeNet ProtectServer,
but now the code has good built in defaults so no configuration file is needed.
All keys to be used has to be generated before the application server is started.
*** Generated HSM objects ***
EJBCA needs (via the Java PKCS#11 provider) three object on the HSM, which are all generated by the generate commands above:
A private key
A public key
A certificate - this is simply a holder of the public key used by java, and not the real certificate of a CA
Note
Normally when generating keys on the PKCS#11 HSM there will be a label on the certificate but not on the private and public key.
You can add a CKA_LABEL attribute to the attributes file to get a label on the private and public keys as well.
The value of the attribute is a hexadecimal string starting with "0h". These labels are normally seen only when you use the native HSM tools to list and manipulate objects.
The example above gives the label 'key1' to the private key. You can give any label by simply looking up the hex codes of characters in the ascii table.
*** SUN or IAIK PKCS#11 Provider ***
The IAIK PKCS#11 provider have support for more algorithms than the SUN provider, and therefore you can choose which provider to use.
EJBCA first tries to load the IAIK provider, and if that is not available it uses the SUN provider. The SUN provider is always available in
JDK 5 and later. To enable the IAIK provider you must do the following:
Purchase server licenses for the IAIK PKCS#11 provider and obtain the files. Visit their website for more information.
Copy three jar files to the application servers class path, for JBoss this is usually APPSRV_HOME/server/default/lib. The jar files needed are:
iaikPkcs11Provider.jar, iaikPkcs11Wrapper.jar and iaik_jce.jar.
Copy the PKCS#11 provider shared library to the library search path for your platform. On linux this might be done by copying libpkcs11wrapper.so to /usr/lib.
Start JBoss, EJBCA should now use the IAIK PKCS#11 provider instead of the SUN provider.
Utimaco CryptoServer
The Utimaco PKCS11 module have a configurable timeout (AppTimeout) that clears all session information if you do not use the keys for some time.
The default time-out is 30 minutes, which may be way too short if your CA is not very very active.
We recommend that you set this timeout to a longer value, several days.
Put a configuration file in /etc/utimaco/cs2_pkcs11.ini:
The timeout in this example of 172800 seconds will allow your CA to idle for a long time.
When using a PKCS#11 token you should first create keys with the command: $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate
Each CA should have its own slot.
Each slot must have been initialized before keys could be generated on the them. This includes setting a user PIN for it. The slot must also require login. Tools for doing this is not provided from EJBCA. The HSM vendor should provide this tool.
Here follows an example on how to initialize a slot and generate keys to be used by EJBCA. The password is user1:
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
*** Import a PKCS#12 file in Utimaco CryptoServer ***
Although not recommended it is possible to import keys from a p12 file to CryptoServer. These steps were contributed by Philipp Vogt and Helmut Edlhaimb-Rexeis.
The tools used are a combination of p11tool that ships with Utimaco HSMs and "ejbcaClientToolBox.sh PKCS11HSMKeyTool".
Import the .p12 file with p11Tool from Utimaco (into slot 20 in this example).
p11tool Slot=22 AuthRSASign=GenPKIAd,:cs2:cyb:/dev/ttyS0 Login=123456 ID=TestCA2XYID ImportP12=mycert.p12,1234
It is absolutely necessary to set an unique id (ID=...) at import time.
The key alias for the imported key is set to "X509 Certificate" (taken from the imported certificate) and cannot be change at import time.
Rename the key alias to an unique key alias with "PKCS11HSMKeyTool rename" from ejbcaClientToolbox.
ejbcaClientToolBox.sh PKCS11HSMKeyTool rename /etc/utimaco/libcs2_pkcs11.so 20 "X509 Certificate" "TestCA2Key"
The new key alias is set to the label and the id of the CKO_CERTIFICATE and the id of the CKO_PRIVATE_KEY.
Optional: Delete the public key with p11Tool using Label="RSA Public Key".
p11tool Slot=20 Login=123456 Label="RSA Public Key" DeleteObject
Test the keys, to make sure they are usable from EJBCA.
ejbcaClientToolBox.sh PKCS11HSMKeyTool test ./libcs2_pkcs11.so 20 1
Make sure no other public keys using this label are present in the HSM.
Even if more than one .p12 file needs to be imported only one at a time can be imported and renamed.
The import and the rename process are tied together and cannot be separated.
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.
1. Install the nShield card
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'
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.
Note
The preload command (see below) must always be called as the same user unless the directory /opt/nfast/kmdata/preload is removed.
If you get a "HostDataAccessDenied" error when running preload or starting JBoss, it is because the
file permissions on the directory /opt/nfast/kmdata/preload is wrong. It's probably because you (sometime) ran
preload as another user, such as root or nfast.
Load the card set so that keys protected by the card set could be generated:
Login as the user that is running the application server. This user must be a member of the nfast group.
The following environment variables should be set for this user:
JAVA_HOME (/usr/local/jdk1.6.0_16 or similar)
APPSRV_HOME (/home/jboss/jboss-4.2.3.GA or similar)
EJBCA_HOME (/home/jboss/ejbca or similar)
NFAST_HOME (/opt/nfast)
Step 3. Create PKCS#11 keys that should be used on the nShield card
Start a new window and login as the same user (jboss user).
Note
An ECC key could not be used with preload (at least not the curve secp160r1). Such a key is generated OK and could be used as long as the current preload is running. But if all preload processes are stopped and then if then preload is restarted the key could not be used. This means that ECC could only be used with a 1/n OCS.
Now 3 keys protected by the key set 'ejbca' are created like this:
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:
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.
Module protected keys do not need an operator card set. Hence no PIN code is needed to active such a key. A CA could be configured to use a keystore with module protected keys.
When using PKCS#11 slot 0 is used to indicate module protection. The only other thing except using slot 0 you have to do is to use a configuration file when creating the key. The file could look like this:
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.
Using more than one OCS.
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.
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.
Note
If preload is used fail-over to the other HSM if one of the HSMs is broken is not working.
When activating a CA you need a smart card from the OCS of the corresponding slot inserted in both HSMs. The OCS got to be 1/n since preload can not be used.
Sample catoken.properties for generating the initial AdminCA on the netHSM, or entering in the admin-GUI when creating a new CA.
The document xxxxxxKeyperInstallation.pdf (xxxxxx is six digits) in the KeyPer UserGuides describes how the HSM is installed, the details start in section 3.5 (Configuring the Keyper HSM for the first time).
As default there is only one slot - 0. The document xxxxxxKeyperP11.pdf describes the PKCS#11 interface in details.
ARX CoSign
This HSM only works on Windows. The installation is done with an installer and the setup with a GUI.
All generated keys will be on slot 1. The PIN code used when activating the keys could be anything since the authentication is made when login on to the user that runs EJBCA.
The shared library is called C:\windows\system32\sadaptor.dll
Bull Trustway
Do the installation of the card according to Install_and_Use_cc2000.pdf. When the card is "installed" it is ready to use with EJBCA. Only one slot (slot index 0) is available. The slot is not protected by any PIN so an undefined 'pin' (empty) property may be used in the configuration.
When using PKCS11HSMKeyTool and starting EJBCA, libcc2000_tok.so and libgpkcs11cc2000.so must be in the library path. Examples:
lars@maud:~/work/test/ca$ ls -al ../../bullInstall/linux
total 412
dr-xr-xr-x 4 lars lars 4096 28 nov 14.28 .
drwxr-xr-x 4 lars lars 4096 20 apr 21.05 ..
dr-xr-xr-x 6 lars lars 4096 20 apr 21.38 CardAdmin_java
-r-xr-xr-x 1 lars lars 35804 28 nov 14.15 cc2000_lx24.tgz
-r-xr-xr-x 1 lars lars 74955 28 nov 14.15 cc2000_src.tgz
-r-xr-xr-x 1 lars lars 14 28 nov 14.15 cc2000S_release
-r-xr-xr-x 1 lars lars 633 28 nov 14.15 desinstall
-r-xr-xr-x 1 lars lars 171 28 nov 14.15 gpkcs11cc2000.rc
dr-xr-xr-x 2 lars lars 4096 28 nov 14.28 include
-r-xr-xr-x 1 lars lars 7209 28 nov 14.15 install
-r-xr-xr-x 1 lars lars 101788 28 nov 14.15 libcc2000_tok.so
-r-xr-xr-x 1 lars lars 146820 28 nov 14.15 libgpkcs11cc2000.so
-r-xr-xr-x 1 lars lars 3843 28 nov 14.15 LisezMoi.txt
-r-xr-xr-x 1 lars lars 3410 28 nov 14.15 ReadMe.txt
lars@maud:~/work/test/ca$ LD_LIBRARY_PATH=../../bullInstall/linux ../../java/jboss/bin/run.sh
Please consult the SafeNet documentation regarding the installation of HW and SW.
*** Configuration ***
Do all steps (1-7 in the section) in "A - Configuration (Setup Appliance after Installing)" of in the html document "Luna SA Online Help -- Document # 800274-xxx" that should be found on your installation CD.
Some notes about our test setup:
Step 3: You may do nothing here. But note that changing many of the policies will reset the HSM. This means that you can't change any of these policies later on.
Step 4: Note that a new partition could be added at any time. Each partition will be represented as a PKCS#11 slot. Make sure to write the Record Partition Client Password (TP) in a text file. In the example the password is btqx-EFGH-3456-7/K9 for the first created partition (slot 1). The TP will later be used as PIN for the slot.
Step 5: A good idea is to allow partitions (p11 slots) to be "activated". If a partition is not activated you got to insert the black key in the PED and give PIN each time a resource in the HSM is used by the client. So in most cases you want to be able to activate a partition:
lunash:>partition changePolicy -partition partition1 -policy 22 -value 1
Step 6:
You don't have to be in the '/usr/LunaSA/bin' directory as the documentation says. We think it is preferable to be in a directory owned by yourself so you don't have to use sudo.
Example of running in your own directory:
Example of occasions when sudo must be used is registration of server and adding client certificates (root owned files and directories are used and updated):
Step 7:
Each partition assigned to a client will be represented by a PKCS#11 slot for this client. It seems that each new added partition will be put last in the slot list and the number of a slot will be slot list index plus 1 (list index starting with 0 and slot number starting with 1).
To get the partition slot mapping on the client do:
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
Now the client may use these slot with EJBCA and it's tools
*** Activating slots ***
Before a partition (slot) could be used by a client it must be activated. This is described in 'B - Administration & Maintenance > Activating and AutoActivating Partitions'. The partition policy required do the activation must have been set (see step5 above). Example to activate a partition:
The password is from the configuration step 4. See above.
*** Generate keys on a slot ***
lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so 2048 rsa2048_1 1
0 [main] INFO org.ejbca.util.keystore.KeyTools - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password:
Created certificate with entry rsa2048_1.
lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so secp160r1 secp160r1_1 1
0 [main] INFO org.ejbca.util.keystore.KeyTools - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password:
Created certificate with entry secp160r1_1.
The password btqx-EFGH-3456-7/K9 (see above) is used.
*** List and test all keys that could be used by EJBCA ***
lars@milton:~/work/test/luna$ ~/work/PWE/ejbca/dist/clientToolBox/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.
*** Sample Hard Token Properties ***
This is a sample configuration of the Hard Token Properties for PKCS#11 token when creating a new CA.
./cmu list -display=index,handle,class,keyType,label
If you have created keys with natvie commands, or imported keys, there is probably no certificate object as required by Java PKCS#11 provider.
Create a self signed certificate referencing the private handle:
Notice that they will have to replace 87 with the handle of the private
key they found when running the list command.
SafeNet ProtectServer
*** install SW ***
Install the software according to the installation instructions for the ProtectServer.
Below are sample commands for installing the SDK rpm on an Ubuntu system, wich means first converting it to a deb.
Using the SDK you can use the SDK as a good emulator for testing and development.
If you are installing with a real ProtectServer you should install the Runtime instead of the SDK. When using the SDK you may use
/opt/ETcpsdk/lib/linux-x86_64 instead of /opt/PTK/lib
If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.
*** Contents of CA Token Properties ***
When you create the CA in EJBCA you can now use the simple CA token properties below.
certSignKey defaultSign
crlSignKey defaultSign
defaultKey default
testKey test
sharedLibrary=/opt/PTK/lib/libcryptoki.so
slot=5
*** Test and list keys on slot 5 ***
$EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/PTK/lib/libcryptoki.so 5
...
Testing of key: test
SunJCE version 1.7SunPKCS11-libcryptoki.so-slot3 version 1.7; modulus length: 2048; byte length 53. The docoded byte string is equal to the original!
SunPKCS11-libcryptoki.so-slot3 RSA private key, 512 bits (id 4, token object, sensitive, extractable)
Signature test of key test1: signature length 64; first byte 3d; verifying true
Signings per second: 257
Decryptions per second: 260
The attributes are listed as "token object, sensitive, extractable", and here is important that is says 'sensitive' (extractable only means that the key can be backed up securely using SafeNet tools).
*** Backup and restore ***
When you have tested that all keys are working you should back them up. Read about how this is done in the ProtectServer documentation.
Then clear the slot that you has just backed up:
ctkmu -s <slot nr> t
Then restore the backup according to the ProtectServer documentation and run the clientToolBox test as above. Now when you now that the keys of the slot could be restored from the backup medium you should set the attributes of them so that they could not be extracted from the HSM by any means. Unfortunate this could not be done with the ctkmu CLI tool since the private key got no label. Use the GUI 'kmu' instead. For each key do:
Select the token and login to it.
Double click on the private key that you want to protect.
Uncheck the 'Exportable' box and press OK
Verify that the 'Exportable' and the 'Extractable' boxes are unchecked and can't be changed
Verify that the 'Private' and the 'Sensitive' boxes are checked and can't be changed
Now it should be impossible to do any backup of the key. If you got a key ceremony protocol it could be a good idea to note that keys was made "unexportable". Also note that the 'Exportable' attribute has to be unchecked each time the backup is restored.
Note
The emulator has an annoying feature (only emulator not real HSM). Each key of same length that are generated is the same, because the seed for the random number generator is static.
This means that a slot may only have one key. If a second key is generated for a slot the certificate object for the first key is deleted before writing the certificate object for the new key. This is done since the Sun p11 wrapper provider does not allow two keys that are equal to be present in a keystore.
To fix this you should set the environment variable ET_PTKC_SW_AUTOSEEDRNG=true.
*** Generating keys using ProtectServer tools ***
You can also generate keys, and the needed self signed certificate, using the SafeNet tools delivered with the HSM. This is for example suitable when you want
to generate ECC keys, since there is a bug in the JDK which prevents this without patching the JDK.
For example, the below commands generates an ECC key with curve P-256 on slot 1, storing it on the HSM with alias 'foo', assigning a selfsigned certificate to it and finally listing the object of slot 1.
cd /opt/ETCprt/bin/linux-x86-64
./ctkmu c -tec -nfoo -aPSVXxTRD -s1 -CP-256
./ctcert c -s1 -lfoo
./ctkmu l -s1
Or you can wrap it all up in a single command...
./ctcert c -k -lfoo -tec -s1 -CP-256 -d30y
If JBoss was started you have to restart JBoss before the keys becomes available in EJBCA.
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:
implement ICAToken
it is recommended to extend BaseCAToken, since BaseCAToken implements handling of all properties, autoactivation and such
be loaded at the static initialization if CATokenManager where it is
registered with the CATokenManager using the method
addAvailableCAToken()
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).
ECDSA keys and signatures
EJBCA support ECDSA signature keys in addition to RSA. You can create a CA using ECDSA keys both using the admin-GUI
and using the cli (bin/ejbca.sh ca init).
Generated keys and certificate
When generating a CA in EJBCA up to three keys and certificates are generated:
A CA signing keypair and certificate
An encryption keypair, used for encrypting keyrecovery information
An OCSP signer keypair and certificate
When using ECDSA keys, the CA signing keypair and the OCSP signer keypair will be the ECDSA keytype you select when creating the CA.
The CA signing and OCSP signing certificate will be signed using your selected signature algorithm.
The encryption keypair will always be RSA, using 1024 or 2048 bit key length. It uses the key length set in the admin-GUI or 2048 bit by default using the cli. A dummy encryption certificate will be created using SHA1WithRSA.
Using ECDSA with an HSM
See the section about HSM property parameters to see which keys can be of different sorts.
Note that the keyEncryptKey can not be ECDSA, but should be an RSA key. Your HSM must support both ECDSA and RSA keys.
You can use PKCS11HSMKeyTool from the clientToolBox to generate keys and certificate requests from an HSM.
PrimeKey has made a patches for the java issues with ECDSA. These patches are waiting for approval in the OpenJDK 7.
You can get a compiled patch together with an installation script for Linux operating systems (can be adapted for Windows as well) from PrimeKey.
*** Sun Java PKCS#11 ECC key issue ***
If you are using the clientToolBox tool in EJBCA to generate ECC keys in an HSM using the PKCS#11 interface you are likely
to stumble on a bug in the JDK which prevents reading of the public key from the HSM. The clientToolBox tool needs to read the public key,
generate a "dummy" certificate and assign that to the key label, so we have a public key certificate in the keystore retrieved from
the Sun PKCS#11 provider.
This bug is present at least up to and including Oracle JDK 1.6u23. A fix has been merged though and should hopefully be available in u24. The fix is already included in OpenJDK 1.6u21.
You can look at this issue in the EJBCA Jira for a solution to the problem: ECA-940
*** Using named Brainpool curves in Java PKCS#11 ***
At the time of writing, Oracle Java does not have named curve definitions for the Brainpool curves.
PrimeKey has made a patch which is waiting for approval in the OpenJDK 7.
You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.
This issue is registered in the EJBCA Jira as ECA-2012.
The patch should work on all HSMs that have named curve support for Brainpool. It has been tested on SafeNet Luna SA and Utimaco CryptoServer. SafeNet ProtectServer supports Brainpool but not using named curves, see below for brainpool support on ProtectServer using custom domain parameters.
With the patch applied you can create and use CAs with brainpool curves in the HSM. Example clientToolBox commands to generate a key:
At the time of writing, Oracle Java does not have support for SHA224WithECDSA in the PKCS#11 provider.
PrimeKey has made a patch which is waiting for approval in the OpenJDK 7.
You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.
This issue is registered in the EJBCA issue tracker as ECA-2013.
The patch should work on all HSMs that have support for SHA224WithECDSA. It has been tested on SafeNet Luna SA and Utimaco CryptoServer.
With the patch applied you can create CAs using HSMs with the SHA224WithECDSA algorithm.
*** Using SHA256WithRSAandMGF1 (RSA-PSS) in Java PKCS#11 ***
At the time of writing, Oracle Java does not have support for SHA256WithRSAandMGF1 (also known as RSASSA-PSS) in the PKCS#11 provider.
PrimeKey has made a patch which is waiting for approval in the OpenJDK 7.
You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.
This issue is registered in the EJBCA issue tracker as ECA-2014.
The patch should work on all HSMs that have support for SHA56WithRSAandMGF1.
With the patch applied you can create CAs using HSMs with the SHA256WithRSAandMGF1 (and SHA384 and SHA512) algorithm.
*** Issue with explicit parameters in Java ***
In order to use elliptic curves with explicit parameters (as opposed to the standard named curves) you need to apply a patch to the file ECParameters.java. It is the same file as patched above for the bug.
Download the JDK source code and locate the file sun/security/ec/ECParameters.java.
Starting at line 210 there is code for handling of non named curve EC parameters. Remove the Exception thrown in line 208 and enable the code that is commented out.
Compile the class by running 'javac *.java' in the directory where the file is located.
Replace the existing sun/security/ec/ECParameters.class file in jre/lib/rt.jar with your patched and compiled version.
*** Using Brainpool ECC with SafeNet ProtectServer Gold HSM ***
Here we provide a guide for using Brainpool curves with the SafeNet ProtectServer Gold HSM. These steps were contributed by DGBK, Netherlands.
ProtectServer needs explicit parameters for the Brainpool curves. Using explicit parameters have one disadvantage, at least when using the Sun PKCS#11 provider, and that is that you can not use the EJBCA tools to generate keys, but have to use the HSM vendors tools.
First you should apply the patch for explicit parameters, above. Then you are ready to start generating domain parameters and keys.
These are the commands for ProtectServer Gold software version 3.33, firmware version 2.07.
1. Create domain parameters file brainpoolP160r1.txt from
ptk_c_administration_manual_rev-c.pdf, Appendix G, Sample EC Domain Parameter Files.
Note that you must add "cofactor=01" last in the parameters file, the cofactor is always one (in the spec document) for brainpool curves (cofactor=1 does not work, it has to be 01).
2. We have to configure the HSM to accept custom domain parameters (E flag):
Normally you want to generate requests and certificates using named curves encoded in certificates and requests, this is what IETF recommends.
In some cases you need to generate the request and certificate with explicit parameters instead, this is for instance mandated by ICAO for usage in CSCA's and DS's for ePassports.
When generating requests with clientToolBox PKCS11HSMKeyTool certreq you can specify a flag to use explicit parameters instead of named curves. Named curves is the default.
When EJBCA issues certificate with public keys from certificate requests (csr's) the key in the certificate will be the same as in the csr. If the csr uses explicit parameters, so will the issued certificate.
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
SEC curves:
sect571r1
sect409r1
sect283r1
sect233r1
sect163r2
secp521r1
secp256r1
secp224r1
secp384r1
Nist curves:
P-224
P-256
P-384
P-521
B-163
B-233
B-283
B-409
B-571
Teletrust curves:
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
After restarting the application server you can now create a new CA using the name 'implicitlyCA' instead of a curve name as keyspec in the admin-GUI or CLI.
The CA certificate will now be created with the NULL encoding of the public key.
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.
LDAP and Publishers
EJBCA has a modular support for something we call Publishers. A publisher
can be any external source where you want to send issued certificates and
CRLs to be stored. The most common cases of Publishers, which are
implemented by default in EJBCA are LDAP directories and Active Directory
(which is a special case of LDAP directory).
The Publisher architecture is modular and it's possible to implement custom
publishers that can also be easily integrated and set up in the Admin GUI.
First we will start with describing the built-in publishers.
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.
*** Using LDAP ***
In Firefox you can for example enter a URL like:
ldap://ip-address-of-ldap-server:389/cn=Tomas Gustavsson,dc=se,dc=bigcorp,dc=com
and it will fetch an address book entry with the information about the user,
including the certificate.
Examples of using LDAP with Firefox can be found in the
howto-section of this web page.
To use LDAP top fetch user certificates and use them for encrypting email
there seems to be a requirement to use SSL connection to the LDAP server
(Account Options->Compositions & Addressing->Edit directories->Edit->Use
Secure Connection), see also below how to configure OpenLDAP for SSL.
Note: When fetching certificates from LDAP with Firefox for example with
URL:
ldap://ldap-server-host/dc=bigcorp,dc=com??sub?(cn=MyName)?(objectclass=*)
To get a checkbox at the fetched certificate, the CA certificate must be
installed in the Windows truststore, not only in Firefox's.
To use SSL against an LDAP server with MS Outlook you must make sure the CN
in the LDAP servers certificate is the same as the hostname.
An example of adding a user for the LDAP server with the CLI interface is:
bin/ejbca.sh ra adduser ldap password "C=SE,O=Foo,CN=ldap.foo.se" null MyCA null 1 PEM SERVER
where ldap.foo.se is the hostname of the LDAP server that Outlook should use.
The CA certificate must also be imported into Windows properly.
*** Configure OpenLDAP ***
The objectclass 'inetOrgPerson' is used by default to store certificates.
Example:
dn: cn=Mike Jackson,ou=people,dc=company,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Mike Jackson
sn: Jackson
userCertificate;binary::
To configure OpenLDAP (version 2.2.5) to include the 'inetOrgPerson' you
must add the following lines to slapd.conf. This is already the default in recent releases:
include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/inetorgperson.schema
Don't forget to add the top object by creating an LDIF file (org.ldif):
Create a user in ejbca (this example is for adding a user with the cli
interface, adding a user with the admin-GUI works just as fine).
In the mail ejbca directory type (use simply 'ra' on windows):
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
Where foo123 is the ldap users password, C=SE... is the users DN and
AdminCA1 is the name you chose for your CA. The user type is end-user (1), keystore type is PEM, and
if using the admin-GUI check 'use batch').
Batch generate the PEM keystore:
bin/ejbca.sh batch
Copy the resulting files p12/pem/ldap.pem, p12/pem/ldap-CA.pem and
p12/pem/ldap-Key.pem to your LDAP server. In this example the slapd.conf is located in
/etc/ldap so we copy the files to that directory.
Protect theses files so they are only readable by the LDAP server.
Add the following to your slapd.conf:
and check that it is running with 'ps -ef|grep slapd'.
On SuSE, if using the builtin OpenLDAP you have to enable ldaps in
/etc/sysconfig/openldap:
OPENLDAP_START_LDAPS="yes"
and then run
SuSEconfig
and then
rcldap start
Configure your LDAP publisher in EJBCA to use SSL by checking the checkbox
'Use SSL', the port should change to port 636.
Note! The CA certificate of the (root)CA used to sign the ldap server
certificate must be present in the java trust cert store
($JAVA_HOME/jre/lib/security/cacerts).
Otherwise you will have to add it using something like:
First get the CA cert:
You have to re-start JBoss after adding anything to the java trust store.
A guide for configuring OpenLDAP on Solaris can be found at
bolthole.com
*** Sample Ubuntu installation ***
- 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
Command to add new LDAP nodes:
- 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.
*** Configuring EJBCA ***
To configure the publisher for LDAP:
Choose 'Edit Publishers' in the Admin GUI.
Add a new publisher with a name you define yourself. Edit the publisher and
fill in all the necessary fields.
Generic parameters to LDAP Publisher:
'Hostnames' is ';'-separated list of the hosts where the LDAP servers are
located. E.g. "ldap.company.com" or "ldap1.company.com;ldap2.company.com".
Only the first available of the listed hosts will be used.
'Port' is the port on which the LDAP server listens, default non-SSL is
389.
'Login DN' is the DN of a user on the LDAP server with permissions to add
and update entities.
'Login Password' is the password for the user above.
'Connection timeout' is number of milliseconds a server has to respond before it is
considered unavailable and the next server in the list of hostnames (if any)
is used instead. This timeout is used to probe LDAP servers, to create connections, to bind and to disconnect.
'Read timeout' is number of milliseconds a server has to complete a LDAP search or read operation before it times out and fails.
'Store timeout' is number of milliseconds a server has to complete a LDAP store operation before it times out and fails. This can take a little longer if you store very large CRLs in LDAP.
'Create Nonexisting Users' defines if an LDAP object should be created by EJBCA if it is no existing object
when EJBCA publishes the certificate.
'Modify Existing Users' defines if attributes (such as email) in existing LDAP objects are replaced with new values and/or added
when an entry is updated with a new certificate. If this option is not activated, existing users will not be touched at all, even not updated with a new certificate.
'Overwrite Existing Attributes' When 'Modify Existing Users' is set to true this value determines whether to change values of attributes when
they already exist.
'Add Nonexisting Attributes' When 'Modify Existing Users' is set to true this value determines whether to add attributes when
they do not already exist.
'Add multiple certificates per user' defines if we should use multiple certificate entries for each user or only one.
Default only one certificate is added to a user entry in LDAP and if the user gets a new certificate the old one is deleted and replaced with the new one.
If this checkbox is checked certificates are instead appended in LDAP so each user can have multiple certificate entries in LDAP.
Make sure your applications can handle this before enabling this option. Revoking a user will remove all certificates entries for the user.
'Remove certificates when revoked' if checked causes the publisher to remove a certificate from LDAP when the certificate is revoked or suspended.
'Remove ldap user when certificate revoked' if checked causes the publisher to remove the whole LDAP user entry when a certificate is revoked or suspended.
'Set userPassword attribute' specifies if the LDAP publisher should set the userPassword attribute in the LDAP object. If a user entry with a non-null password is published,
and this checkbox is checked, the userPassword attribute will be populated with the user's password.
'User Object Class' is the objectclass for the LDAP entries for users,
where user certificates are published. The entry is hierarchical separated by ';' to
build a structure like:
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
This objectclass must allow the attribute 'userCertificate;binary'.
Default 'top;person;organizationalPerson;inetOrgPerson'
'CA Object Class' is the objectclass for the LDAP entries for CAs, where
CA certificates and CRLs are published. The entry is hierarchical separated by
';' to build a structure. This objectclass must allow the attributes
'cACertificate;binary', 'certificateRevocationList;binary' and
'authorityRevocationList;binary'.
Default 'top;applicationProcess;certificationAuthority'
'User Certificate Attribute' is the attribute name, in the
userObjectClass, for the users certificate.
Default 'userCertificate;binary'.
'CA Certificate Attribute' is the attribute name, in the cAObjectClass,
for the CAs certificate.
Default 'cACertificate;binary'.
'CRL Attribute' is the attribute name, in the cAObjectClass, for CRLs
(user CRLs) publisher by the CA.
Default 'certificateRevocationList;binary'.
'ARL Attribute' is the attribute name, in the cAObjectClass, for ARLs (CA
CRLs) publisher by the CA.
Default 'authorityRevocationList;binary'
(note that pure ARLs are not implemented yet in EJBCA).
'LDAP location fields from cert DN'
When configuring the LDAP publisher the BaseDN will be used as the base for
the DN published in LDAP,
and it will be appended to the LDAP location fields selected to be used.
example: If the user DN in EJBCA is "cn=tomas gustavsson, uid=tomasg,
O=PrimeKey Solutions AB, C=SE"
and the BaseDN is "dc=PrimeKey,dc=SE" and the selected LDAP location fields
are "CN".
The LDAP DN used for publishing will be "cn=tomas gustavsson, dc=PrimeKey,
dc=SE", and the "uid=tomasg"
will be added as an attribute in LDAP. The certificate stored under
"cn=tomas gustavsson, dc=PrimeKey, dc=SE"
will have the subjectDN "cn=tomas gustavsson, uid=tomasg, O=PrimeKey
Solutions AB, C=SE".
*** Setting up certificate profiles ***
You MUST make a custom certificate profile to publish to LDAP!
To publish in LDAP you must create a Certificate profile in EJBCA that
publishes to LDAP. If the above is configured, there will be a section for
'Publishers' available when creating/editing a certificate profile (with 'Edit Certificate
Profiles').
Choose this, and then when adding end-entities, make sure they use the new
certificate profile and voila, the certs will be published.
*** Different LDAP publishers ***
LDAP Publisher
The regular LDAP Publisher works by searching the DN in LDAP.
When ejbca creates an object to publish a certificate to LDAP it firsts builds the DN from the
baseDN and 'LDAP location fields for cert DN'. It checks if the entry exists in the
ldap and either creates or modifies the entry.
Example: The certificate DN is "CN=Tomas Gustavsson,O=Foo,C=SE",
the BaseDN in the publisher is "DC=primekey,DC=se" and the CN is selected in "LDAP location fields from cert DN".
The resulting DN that EJBCA will search for in the LDAP and create if it does not already exist is
"CN=Tomas Gustavsson,DC=primekey,DC=se".
Using this publisher, if you have multiple trees in your LDAP (for example "ou=foo,dc=primekey,dc=se" and "ou=bar,dc=primekey,dc=se")
you can either:
Include both CN and OU in 'LDAP location fields from cert DN' and have your cert DNs like "CN=Tomas,OU=foo,O=MyOrg,C=SE.
Use different publishers for ou=foo and ou=bar and issue certificates for the different OUs with different certificate profiles.
LDAP Search Publisher
The LDAP Search Publisher works by searching the LDAP for existing entries using a user defined search filter.
If no entries exist in the LDAP when searching for an entry, one is created just like in the regular LDAP Publisher.
The search filter is defined in the two fields under "LDAP search settings":
Suffix base DN of LDAP Search - the base for your search filter.
LDAP filter of the search - your LDAP filter.
If you build your search filter on DN components, you also have to select thos components as 'LDAP location fields'.
The best example of such a search filter is if base is "dc=primekey,dc=se" and filter is "uid=$USERNAME".
The search done by ejbca will be equal to the search:
ldapsearch -x -b "dc=primekey,dc=se" "(uid=$USERNAME)"
$USERNAME is replaced by the EJBCA username of the user that has had a new certificate just generated.
Other variables apart from $USERNAME is $EMAIL, $UID, $CN, $O, $OU and $C where these values are taken from the certificate DN.
When a certificate is generated for say user "ldap" EJBCA will perform the search:
ldapsearch -x -b "dc=primekey,dc=se" "(uid=ldap)"
The certificate generated for ldap will be published in the object returned by the search.
This is very useful if you want to publish certificates to an LDAP directory where your users already exists, such as an email directory.
The DN in the LDAP does not have to match the DN in the certificates at all.
If more than one entry matches the search, the first returned search result will be used.
*** Publishing to Active Directory ***
When configuring Active Directory LDAP, Bind DN for the users are usually,
cn=user,cn=Users,dc=domain-component1,dc=domain-component2.
For example: cn=Philip Vendil,cn=Users,dc=primekey,dc=se for the domain
primekey.se
If your DN is like "cn=Ejbca1,0=MyOrg,c=SE"
and your base DN is like "DC=Security,DC=Software,DC=MyOrg".
The publisher for AD should have base DN like
"cn=Users,dc=Security,dc=Software,dc=MyOrg"
For Login DN you should use the full ldap name, for example:
"CN=Administrator,CN=Users,dc=primekey,dc=se"
In order to connect to AD though SSL you should issue a LDAP SSL P12
to the domain controller. According to
MS Article ID 321051
The same certificate is used for both the AD and global catalogue (GC).
Remember to add the CA certificate to the machine that stores trusted root
certificates.
To publish a CRL to Active Directory use a Base DN similar to
*** Constructing the DN for an entity to be published ***
The DN to be published is constructed from the certificate DN of the entity to be published.
But if the publisher requires a DN object that is not a part of the certificate DN then the DN defined for entity might be used instead.
The DN of the entity (user or CA) could have more objects than the certificate if "Use a Subset of Subject DN" is defined in the used certificate profile.
The "LDAP Publisher" and the "LDAP Search Publisher" tries the DN of the entity when the certificate DN is missing an object needed in the publishing DN
*** What EJBCA stores/creates/modifies ***
Apart from the DN in the entry a number of attributes are also stored, some
are required by schema, some are optional. EJBCA find attributes in the certificate, if it is an
OU (organizational unit) in the certificate EJBCA uses that to populate the OU attribute in the LDAP
entry.
When updating an entry that already exists EJBCA uses replace on the
existing attributes, so if an email attributes already exists and EJBCA finds an email address in
the certificate, the email attribute in ldap is replaced with the email address from the certificate.
Note that attributes are only replaced/updated if the flag "Modify Existing Users" in the Publisher is active.
The certificate attribute is always updated though.
Attributes that are part of the DN, i.e. that reflects the location of the entry in LDAP is not modified, since this
is usually not allowed.
The attributes that EJBCA creates or replaces are:
cn (common name)
l (locality)
ou (organizational unit)
sn (surname)
gn (givenname)
st (state)
o (organization)
uid (user id)
initials
title
serialnumber - If we have selected to use the SN (serialNUmber DN field) in 'Ldap Location fields', we will also add it as an attribute.
Custom schemas
See doc/ldapschema for files with custom schemas and attribute types to add to your LDAP schema.
*** Certificate serial number ***
This is an attribute and a schema extension to allow storage of certificate serial number in the inetOrgPerson LDAP object, for end user entries.
This is done by adding an extension to inetOrgPerson called inetOrgPersonWithCertSerno with a new optional attribute called certificateSerialNumber.
Once you have installed the new schema in the LDAP server you use it by configuring the LDAP publisher with:
User Object Class: top;person;organizationalPerson;inetOrgPerson;inetOrgPersonWithCertSerno
instead of the befault value:
User Object Class: top;person;organizationalPerson;inetOrgPerson
The certificateSerialNumber attribute will then automatically be added/modified when publishing to LDAP.
*** 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.
*** Installation ***
For the Netscape/SUN servers, on UNIX, copy the 85ejbca.ldif file into:
For OpenLDAP, copy the ejbca.schema file into, e.g.:
/etc/ldap/schema/
and edit slapd.conf to add the following line:
include /etc/ldap/schema/ejbca.schema
then restart the server.
Custom publishers
*** Developing a custom publisher ***
If your setup makes it very complex to configure multiple certificate
profiles and multiple publishers you might consider writing a custom publisher that
handles things directly according to you needs.
Look in the directory src/java/org/ejbca/core/model/ca/publishers for more
information about writing your own solution. There is an empty custom publisher called
DummyCustomPublisher.java that can be extended.
*** Publishing with an external application ***
A lightweight alternative to developing a new custom publisher for exporting CRLs,
certificates and revokations is to use the General Purpose Custom Publisher (GPCP).
This makes it possible to export DER-encoded CRLs, certificates and/or revokations with
a simple script (using scp or similar). The GPCP creates a temporary file and
executes the script with the full pathname to the temporary file as an argument.
It's possible to let the publisher ignore an error in the execution of a script by
altering the publishers properties. By default, the publisher detects both output to
standard error and a non-zero errorlevel set by the script.
To start using the GPCP, select "Edit Publishers" in the Administration GUI. Add a
publisher "GPCP" and then "Edit" the same. Choose
Publisher type: Custom Publisher
Class Path: org.ejbca.core.model.ca.publisher.GeneralPurposeCustomPublisher
and click "Save and Test Connection" to save the entered information and validate
that the specified applications exist. Select "Edit Certificate Authorities" in
the Administration GUI and select "GPCP" as your new CRL publisher. Click "Save".
Test CRL publishing by selecting "Basic Functions" in the Administration GUI and
click "Create CRL".
Test certificate publishing by selecting "Edit Certificate Authorities" in the
Administration GUI, select a CA, click "Edit" and then "Republish CA Certificates".
More advanced scripts or applications have the ability to use the additional argument
Depending on application, the GeneralPurposeCustomPublisher can calculate whether a CRL is a delta CRL.
Set the parameter crl.calclulateDeltaCrlLocally to true in order to do this, or false if you wish to check this in an external script (or not at all).
The result of this check, if run, will be last in the argument list to the script.
An example linux script for certificate publishing could look like:
*** Publisher for sampling of issued certificates ***
One custom publisher called CertificateSamplerCustomerPublisher can be used to
store published certificates to a configured directory. Different sampling methods
can be specified per certificate profile, either storing every certificate, no
certificate or randomly with a configured probability.
To use the CertificateSamplerCustomerPublisher, select "Edit Publishers" in the Administration GUI, create a new publisher and edit it.
Publisher type: Custom Publisher
Class Path: org.ejbca.core.model.ca.publisher.CertificateSamplerCustomPublisher
and click "Save and Test Connection" to save the entered information and validate
that the entered configuration is correct. Select the publisher in the relevant
certificate profiles.
In the example above the certificate profile with id 2234644354 will not have any certificates stored. The profile with id 1645141026 will have about 25% of the certificates stored and for all other profiles all certificates will be sampled.
Publisher Queue and failures
To achieve robust publishing there is a publisher queue. When a publisher fails the published data is stored in a
separate table in the database, the PublisherQueueData. This queue can then be processed by a service (see Publisher Queue Process Service in the Services Framework section).
Publishers can also be configured not to publish directly at all, but to store everything in the queue, which is later processed.
The benefit of this approach is that publishing is instant. When issuing certificates the CA does not have to wait for all publishers to
finish. If there are many publishers this might delay the issuing process slightly.
Publisher Settings:
'Current length' - displays the number of new entries in the queue in the intervals <1 min, 1-10 min, 10-60 min and >60 min.
'No direct publishing, only use queue' - when enabled, the publisher does not try to publish directly but instead pushes the
update to the queue for later processing by a Publish Queue Process Service.
'Keep successfully published items in database' - when enabled items stored in the publisher queue will not be removed when real
publishing has been done, status will merely be changed from PENDING to SUCCESS.
'Use queue for CRLs' - determines if the publisher queue should handle CRLs or not for this publisher.
'Use queue for certificates' - determines if the publisher queue should handle certificates or not for this publisher.
Internationalization
To customize EJBCA admin GUI for your languages special characters you will probably have to
change the default page encoding in 'web.contentencoding' (in conf/web.properties file)
to for example ISO-8859-1 instead of the default UTF-8.
Displaying, receiving, decoding and storing different char sets is rather complicated and the
architecture is multilayered. There are the web browser, application server, database and
operating system, all working together.
If you change to UFT-8 to handle your char set, you must probably also specify that the database
connection should use UTF-8.
For MySQL this can be done in the connection-url in your datasource description
(APPSRV_HOME/server/default/deploy/ejbca-ds.xml):
jdbc:mysql://yourhost/ejbca?characterEncoding=UTF-8
You will also want to configure the database, for example in my.cnf, to use UTF-8.
You also want to configure your machine to use the locale you are using, otherwise some encoding/decoding to the database
may get mixed up and throw a lot of errors (java XML decoding).
For example in SUSE this is done with 'yast' and in Debian it is done with 'dpkg-reconfigure locales'.
For some languages (for example Chinese) the java scripts in the admin GUI will fail to recognize
the characters when doing checks for allowed characters in DN etc.
The easiest way to resolve this is to go into the file:
src/adminweb/ejbcajslib.js
And change all methods 'checkfield*()' to always return true directly.
If you can't get you national characters to work with the Admin GUI, you can try using the CLI instead
(bin/ejbca.sh ra adduser ...). That usually works.
To make everything work perfect you MAY have to also configure the encoding of URIs according to your settings in
the application server. This is done automatically for JBoss using the 'web.contentencoding' in conf/web.properties.
Adding a new language to the admin GUI
Java uses unicode internally, so the things that needs to be taken care of are:
Make sure your system locale is set correctly, so Java will recognize input of your nations language.
If Java does not automatically recognize your locale you might need to specify it as options to Java during
startup (i.e. in JBoss and cmd line commands such as ejbca.sh).
java -Duser.language=2-char-language-code -Duser.region=2-char-country-code
example for Swedish: java -Duser.language=sv -Duser.region=SE
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:
Rename the languagefile you have created to
language.languagecode.properties. In case of chinese it should be 'zh', and place
it in the modules/admin-gui/resources/languages/ directory.
Edit conf/web.properties (create with conf/web.properties.sample as template if you don't have one).
Change 'web.availablelanguages' and add your language code to the value. i.e:
web.availablelanguages=EN,DE,ES,FR,IT,JA,PT,SE,ZH
You may have to change the default page encoding in 'web.contentencoding' to for example ISO-8859-1
instead of the default UTF-8.
Clean and re-deploy ejbca with 'ant clean' followed by 'ant deploy'.
Restart JBoss and your browser after this.
Now it should be possible to select ZH in the system configuration as default language
and in the administrator preferences page.
The language will be changed 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.
Custom DN and altName oids
EJBCA supports custom (your own) OIDs in DN components.
In order to add such a DN you can simply call the DN for example: CN=MyCommonName,1.1.1.1=MyCustomOid,C=SE
Where 1.1.1.1 is your custom OID.
Custom OIDs are always encoded as UTF8String in the DN.
To get support for custom OIDs in the Admin GUI you must edit the file src/java/profilemappings.properties and add your new
OID in the end. Just follow the example in the file, and you will get the possibility to add you oid in the End Entity Profile,
and following that also when adding new users.
If you edit profilemappings.properties, you should also add an entry in src/adminweb/languages/languagefile.XX.properties (where XX is you language).
Otherwise your new field will be displayed as the key that you entered (which is probably ok also) in the admin-GUI. The new field you must add in the language file is
the last field in profilemappings.properties, i.e. the LanguageConstant.
EJBCA will by default put unknown OIDs in the end so the DN will probably be displayed as: CN=MyCommonName,C=SE,1.1.1.1=MyCustomOid
(if looking at the asn1 coding, different application display in a different order regardless of the asn1 coding).
If you need a particular order of DN components, you can add a file 'dncomponents.properties' in the directory ejbca/src/java.
There is a file called dncomponents.properties.sample in the distribution as a starting point (it shows the default ordering in EJBCA).
You custom oid must be placed in the right place in that file, and all components from the sample file should be included, or you will get
strange behaviour.
Using the dncomponents.properties file is only needed if you need to control the ASN.1 ordering of DN elements.
After updating dncomponents.properties you need to run 'ant clean' before re-deploying EJBCA.
A word of caution:
If you use custom OIDs, they better not become standard ones later on, because if the underlying ASN.1 library in EJBCA starts to
know the OIDs as standard ones, things will be renamed in the database and you will have to do a database migration.
Also you must keep track of dncomponents.properties when upgrading EJBCA.
Stick to the standard is my advice!
Having all these customizations off-course requires some maintenance on your part, so don't forget your customizations when upgrading EJBCA to a new version.
Check RELEASE_NOTES for important changes!
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
Custom Certificate Extensions
From EJBCA 3.4 it is possible to add customized certificate extensions to certificates.
Simple extensions only containing a static value can be added by simply editing a property file, these are called
"basic certificate extension". It is also possible to generate advanced certificate extension by
implementing a simple Java interface.
Configuring Custom Certificate Extensions
Certificate extensions are 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 : Full class name of the CertificateExtension implementation 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 CertificateExtension, 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 set the "classpath" property to org.ejbca.core.model.ca.certextensions.BasicCertificateExtension
and specify the properties idX.property.encoding and idX.property.value
(idX.property.value is optionally if idX.property.dynamic=true).
See the following table for the available encodings and how their value is interpreted:
DERBITSTRING : A String containing the characters '0' and '1'.
DERINTEGER : A String containing digits only in decimal digits.
DEROCTETSTRING : A String containing hex data representation.
DEROBJECT : The hex encoded DER value of the extensions. You can use this to create any extension with sequences etc.
RAW : The hex encoded byte array value of the extensions. You can supply any data hex encoded to be used as the extension value bytes.
Examples of certificate extensions that you can configure with the BasicCertificateExtension are given in 'src/java/certextensions.properties'.
MS application policies
NetscapeCertType
NetscapeComment
NetscapeCARevocationURL
NetscapeRevocationURL
...
If the the property idX.property.dynamic is configured to true the extension value may be taken from extension data supplied with the end entity. See Custom certificate extension data for how this can be added from admin web.
Implementing an Advanced Certificate Extension
To create an advanced extension it is required to create a Java class extending
the CertificateExtension abstract class. 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.
If your advanced extension needs to return a byte array that is not necessarly
an ASN.1 structure it is possible to override the getValueEncoded method as this
is the method EJBCA will call when adding the extension to the certificate. See
BasicCertificateExtension.java for an example of this special case.
In addition to static values defined as properties in certextensions.properties
it is also possible to get values from the extension data in the end entity's
extended information store. A good choice is to use the extension oid as a
prefix to the key of the property to associate the value with this extension.
Here is an example of a simple advanced extension. To add this extension to EJBCA
create properties for it in certextensions.properties and make sure the full class
name is set as its "classpath" property, also make sure the class is accessible on
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)
*/
@Override
public DEREncodable getValue(UserDataVO userData, CA ca,
CertificateProfile certProfile) {
// Optionally get dynamic values for this extension
//String dynamicValue = userData.getExtendedinformation().getExtensionData(getOID() + ".someotherproperty");
String value = getProperties().getProperty(PROPERTY_SOMEPROPERTY);
return new DERPrintableString(value);
}
}
Logging
The are three different logging devices available for official events
(creation of certificate etc) from EJBCA 3.6. These devices should not be
confused with the info/debug output that is sent to Log4J directly. You can
find more information on how to configure Log4J in doc/howto/log4j.txt.
What log devices to use, can be configured in conf/log.properties.
It is recommended to only allow new log-posts to the database-tables. More
information on this can be found in doc/howto/HOWTO-database.txt.
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.
You can find information about configuring log4j on JBoss in the EJBCA wiki.
OldLogDevice
OldLogDevice stores log-events in the database. Viewed events can
be exported from the Admin GUI.
Monitoring and healtcheck
In EJBCA there exists a health check service that can be used for health monitoring.
It is also useful for cluster, as it can be checked by load balancers to determine if a node should be active in the cluster (healthy)
or taken out of the cluster (unhealthy).
The servlet is located in the URL: http://localhost:8080/ejbca/publicweb/healthcheck/ejbcahealth
and is configured using conf/ejbca.properties.
The following configuration parameters may be set to configure authorization and what the service checks:
healthcheck.amountfreemem, default: '1' - The number of Mb of memory that must be free.
healthcheck.dbquery, default: 'select 1' - Parameter indicating the string that should be used to do a minimal check that the database is working.
healthcheck.authorizedips, default: '127.0.0.1' - Specifies which remote IPs that may call this healthcheck servlet. Use ';' between multiple IPs.
healthcheck.catokensigntest; default: 'false' - if the check of CA tokens should actually perform a signature test on the CA token, or it should only see if the token status is active.
healthcheck.publisherconnections, default: 'false' - Defines if test connections agains all configured publisers should be performed.
By editing a maintenance file on the server, you can make the service return an error message stating that the server is down for mainenance.
This is very useful in a cluster when you can take cluster nodes in and out of rotation by editing a simple text file.
healthcheck.maintenancefile, default: not set - location of file containing information about maintenance.
healthcheck.maintenancepropertyname, default: DOWN_FOR_MAINTENANCE - the healthcheck.maintenancefile should contain a single line like this 'DOWN_FOR_MAINTENANCE=true'.
The following parameters confiugure what message or HTTP error code the health service returns.
healthcheck.okmessage, default: 'ALLOK' - Text string used to say that every thing is ok with this node.
healthcheck.sendservererror, default: 'true' - if a HTTP errorcode 500 should be sent in case of error.
healthcheck.customerrormessage, default: null - Set this parameter if you want a static error message instead of one generated by the HealthChecker.
If an error is detected one or several of the following error messages is reported.
"MEM: Error Virtual Memory is about to run out, currently free memory : number" - The JVM is about to run out of memory.
"DB: Error creating connection to database" - JDBC Connection to the database failed, this might occur if DB craches or network is down.
"CA: Error CA Token is disconnected: CAName" - This is a sign of hardware problems with one or several of the hard ca tokens in the node.
"MAINT: DOWN_FOR_MAINTENANCE" - This is reported when the healthcheck.maintenancefile is used and the node is set to be off line.
"Error when testing the connection with publisher: PublisherName" - This is reported when a test connection to one of the publishers failed.
Reference manual
All configuration options, JNDI names etc is configured through the use of properties files in conf/*.properties file.
You can copy the .sample files to respective .properties files and configures. Most options are documented in the .samples files.
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.
*** Disable command line interface ***
It is possible to disable the command line interface to prevent someone from running the operations that require authorization.
The setting is located in the admin web under System Functions > System Configuration and the checkbox
"Enable Command Line Interface Access". By unchecking it operations requiring authorization can not be performed from the command
line interface.
Warning: Disabling this makes it impossible to use the CLI for any operation that requires administrator rights including
renewing the Super Administrator certificate! Please, make sure to renew the administrator certificates using the Admin Web
before they expire!
Note: After changing this property you need to click the Clear All Caches button or run the CLI command:
bin/ejbca.sh clearcache -all
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.
This is a utility function to quickly and easily issue an initial administration smart card using PrimeCard.
To change ports (default public http=8080, public https=8442, private https=8443) you must edit
conf/web.properties. Change the properties httpserver.pubhttp, httpserver.pubhttps and httpserver.privhttps.
After 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 JEE application,
this front-end may not be needed.
Customizing EJBCA
You can change any part of EJBCA to better suit your specific needs.
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
You can now remove the entire $EJBCA_HOME-directory and replace it with the a fresh snapshot from
the trunk. Restore the database and all the config and generated keys will be restored to $EJBCA_HOME
next time you run "ant deploy".
Please note that
there is no way to recover overwritten files, so you have to manually restore
files if needed.
ant will not be able to detect if your changes are incompatible with newer
versions of EJBCA. Always use 'diff' on the different versions to see if any file
you override is affected.
contributed new features or improvements that many would benefit from is greatly
appreciated by the community and makes your maintenance easier
Adding your own public web-pages
The public web-pages are written in JSP and can be found under modules/publicweb-gui/resources/.
Modify the pages (directly or by using a separate tree), rebuild and redeploy. The
changes should show on http://ejbcahost:8080/ejbca.
Adding your own rules to regulate the values of End Entity Fields
It is possible to define a set of rules to control the format of the End Entity fields. For example, it is possible to ensure that
the subject DN serial number is always a number of six digits, or should always end with the letter 'N'.
Setting such rules is done by implementing the static function org.ejbca.core.model.ra.FieldValidator.validate(). In this function,
you can define a rule that is applicable to a specific field in a specific End Entity profile. Should the field value not match
the rule, a CustomFieldException should be thrown and the error message you set in the exception will be shown as the error message
in the GUI. This rule will be checked each time an end entity is added or changed, whether is was added or changed by the GUI or otherwise.
To avoid losing these rules when updating the EJBCA version, the new FieldValidator class should be stored in a ejbca-custom catalog.
Please see the "Handling changes in a separate tree" section above.
EJBCA Plugins
In case you (for example) want to extend the RA functionality considerably, possibly including additional
database tables as well, you may consider using the EJBCA plugin scheme which provides custom
applications with the core EJBCA environment data. In the directory src/samples/plugins you will find
a couple of complete demo plugins that can be added to an existing EJBCA installation
without any configuration. See the src/samples/plugins/README file for details.
Plugins are built and packaged together with the rest of the EJBCA components into the "ejbca.ear" file.
Using the demo servlet
It is a demo servlet that will accept any incoming post, create a user with a unique username, and instantly
send back a certificate. The entity- and certificate profiles used are sent as parameters in the post.
To set up the demo servlet:
Find out the CA id of the CA you want to use for signing of the demo certificates. Use the Admin GUI or 'bin/ejbca.sh ca listcas' to find the integer value that is the CA id.
Configure the CA id in src/java/org/ejbca/ui/web/pub/DemoCertReqServlet.java, it's the parameter DEFAULT_DEMOCAID.
Edit src/publicweb/publicweb/WEB-INF/web.xml and uncomment the two sections for the demo servlet.
If using UTF-8 to display the web-page containing the demo form to the users, change ISO-8859-1 to UTF-8 for the env-entry 'contentEncoding'. Otherwise national characters in names will be encoded/displayed incorrectly in the certificates.
Deploy with 'ant deploy'.
Create an end entity profile and a certificate profile that should be used for the demo certificates.
Create a demo apply page containing something similar to the sample form below for Firefox. There are some sample scripts under modules/publicweb-gui/resources/.
<form name="demoreq" action="http://127.0.0.1:8080/ejbca/democertreq" method="post">
Please fill out the form and click <b>Enroll</b> to receive your certificate.
Read our <a href="http://www.primekey.se/primekey/en/Demo.html">privacy policy</a>.<br>
<input name="certificateprofile" value="DemoCertProfile" type="hidden">
<input name="entityprofile" value="DemoEntityProfile" type="hidden"><br>
<br>
Full name:
<input name="user" value="C=SE,O=PrimeKey Solutions AB,OU=Demo,CN=" size="25" maxlength="60" class="input" type="text">
<p align="left"> E-mail:
<input name="email" size="25" maxlength="60" class="input" type="text">
<input name="includeemail" value="true" type="hidden">
</p>
<p align="left"> Choose key length from the list below. The default is recommended in most cases. <br>
<br>
<keygen type="hidden" name="keygen" value="challenge">
</p><p align="left">
<input value="Enroll" name="submit" type="submit">
</form>
You can use some hidden fields and some java script to for example only ask for a name, and concatenate it with a hidden partial DN to produce
a full dn for the 'user' parameter. Use your imagination!
Samples
A collection of samples are available in the directory src/java/org/ejbca/samples/ and doc/samples/. You can also look for classes with "Dummy" in the name.
Troubleshooting
To find cause and description of errors look in the JBoss server log. For JBoss 5 this is located in server/default/log/server.log.
If this does not display enough information, enable DEBUG logging according to the Log4J configuration described above and check the log file.
Don't get intimidated by long stack-traces. Try to look for the message text and additional clues on lines starting with "Casued by:"
Check the documentation. Double-check so everything really is configured the way it should and that you did not skip any step that didn't seem important.
Try to reproduce this in a test environment with full DEBUG logging.
Find out under what circumstances this occurs: seemingly spontanious or as a response to a certain set of actions or input
Search for a solution. Perhaps someone else has had this problem and discussed it somewhere?
Use support forums or mailing list to get help (provide full context, environment, the relevant logs, steps taken and what you are trying to accomplish)
File a bug report in the issue tracker
Also note that you can get professional support from PrimeKey.
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 \r \\ ; ! \0 % ` < > ? $ ~
(\n is newline, \r is carriage return, \\ is backslash, \0 is null)
These characters will be replaced by /. ',' can be escaped ,'\,'.
The current JavaScrips used in Admin GUI might also limit you ability to use any UTF-8 character.
org.ejbca.util.StringTools contains the full list of characters banned for different purposes.
Code signing
Being able to verify the integrity of a release or deployed EAR-archive might be
required for some setups. Currently both ant targets "ziprelease" and "ca.ear"
(invoked from "deploy", "bootstrap" and the default target) supports jar-signing
with the "jarsigner" command included with Java. Note that you still could remove
files from a signed archive without anyone noticing since the files are signed
individually. To create a signed ziprelease of EJBCA:
ant ziprelease -Dejbca.zipversion=x_y_z -Dsignjar.keystore=p12/releasesigner.jks -Dsignjar.keystorealias=releasesigner -Dsignjar.keystorepass=foo123
The certificate used for the signature must have key usage "Digital Signature"
and extended key usage "Code Signing". The signed archive can be verified using
the "jarsigner" command and the CA-certificate. This example will output any
unsigned file or file with a bad signature:
jboss@server:~/ejbca$ jarsigner -verify -keystore p12/truststore.jks -verbose ../ejbca_x_y_z.zip | grep -v "^smk" | grep -v "^ *0"
246809 Tue Oct 21 13:28:48 CEST 2008 META-INF/MANIFEST.MF
246930 Tue Oct 21 13:28:48 CEST 2008 META-INF/RELEASES.SF
1859 Tue Oct 21 13:28:48 CEST 2008 META-INF/RELEASES.RSA
s = signature was verified
m = entry is listed in manifest
k = at least one certificate was found in keystore
i = at least one certificate was found in identity scope
jar verified.
OpenSSL can be used to sign and verify an entire archive, but requires the
public key from the signing certificate:
Normally in a PKI extreme performance is not really an issue. A default installation of EJBCA can easily issue tenths of certificates per second,
which is more than enough even for very large installations.
For OCSP it is more important, but OCSP is also more light weight so the default performance there is hundreds of requests per second.
In more specialized PKI installations there can however be the need to issue hundreds of certificates per second. Therefore we provide a small list of
configuration items that can maximize performance of EJBCA to issue more than 100 certificates per second (depending on hardware etc).
Disable logging to database in log.properties, only use Log4jLogDevice. This removes a database insert and gives a big boost.
Configure Log4j to log only to file, not console, and use only INFO or ERROR logging, not DEBUG. This can give a small improvement.
Disable use of CertReqHistory in CA configuration. This removes a database insert and gives a big boost.
Disable finishUser in CA configuration. Verify that this is ok first by reading the documentation for this feature. This can save a database read and update.
Enable all caches in cache.properties. If you cache indefinately you can use the cli command 'bin/ejbca.sh clearcache' if configuration changes are made. This can give a small improvement. See also info about the clear all caches button.
Do not enforce any uniqueness (keys, DN, Subject DN SerialNumber) in CA configuration. This will ensure no extra selects are made and can give a small improvement.
Minimize the number of indexes in the database, only use the ones that are absolutely needed. This makes inserts in the database a bit faster and can give additonal 10%.
Use the native JBoss connectors for http and https. This can give an additional 10%.
If you have a lot of certificates (>100M) it might be a good idea to use a separate table for the storage of the encoded certificates. See the database.useSeparateCertificateTable property in ./conf/database.properties.sample
Throw away CA
EJBCA have a configurable function going by the name of "throw away CA". This is an option where EJBCA simply functions as a high speed certificate factory, issuing certificates but not storing any trace of them in the local database.
Using the throw away CA option naturally comes with many limitations, unless taken care of in another way external to EJBCA.
You can not search for issued certificates.
You can not revoke certificates, and thus not use CRLs or OCSP.
If these limitations are acceptable you can gain some benefits by using the throw away CA option:
Maximum performance since no database queries are done. Enable to maximum caching and EJBCA will not make a single call to the database.
Minimal storage requirements. Since no issued certificates are stored in the database only EJBCA configuration needs storage.
Clear All Caches
This button is located under System Configuration and is used to clear the global configuration cache, end entity profile cache, certificate profile cache, log configuration cache, authorization cache and CA cache on all the
nodes in this cluster. In order for this to work, the operation system should be configured to map the names of the nodes to their IP addresses (i.e. DNS or hosts file). The configuration should be done on all
the nodes in the cluster. See also maximizing performance for information about caching.
Pressing this button sends a http request to the ClearCacheServlet on all the nodes in the "Nodes in Cluster" list. Only other nodes that are in the "Nodes in Cluster" list are allowed to call the ClearCacheServlet. Authorization is based on caller's IP address.
On startup of EJBCA each node adds its hostname to the "Nodes in Cluster" list. The list can also be manually edited on the System Configuration page.
High Availability (HA), a.k.a Clustering
EJBCA is designed to work well in a clustered, high availability configuration. The key to EJBCA high availability is to have a HA database, since all EJBCA nodes shares the same database.
The process of setting up EJBCA in a HA setup is:
Install a HA database. The process for this differs between databases, consult your database documentation/vendor.
Install EJBCA on one EJBCA application node and perform all needed configuration.
Deploy EJBCA with the exact same configuration on other application nodes.
If you are using HSMs, connect one HSM with the same (duplicated) keys on all EJBCA application nodes. Alternatively set up a HA HSM configuration according to your vendors instructions.
When setup you can connect to any of the EJBCA application nodes, and use load balancers to failover and/or spread the load between the different EJBCA application nodes.
A note of caution. Setting up and managing a fully HA database can be very difficult and/or expensive. You may consider different variants of HA databases, such as replication with manual or automatic failover.
The possibilities are virtually unlimited, only your requirements and imagination can decide what type of configuration works best for you.
The upgrade EJBCA without downtime, you can use the 'app.version.effective' property in conf/ejbca.properties.
