EJBCA - Open Source PKI Certificate Authority

Features

EJBCA Enterprise has full support for Card Verifiable certificates (CVC BSI TR-03110) used by EU EAC ePassports and eIDs.

Using EJBCA you can set up a complete PKI infrastructure for CVC CAs with:

Country CVCCA
Domestic DVs (document verifier)
Foreign DVs
Inspection systems (IS)
Authentication Terminals (AT)
Signature Terminals (ST)

EJBCA supports RSA and ECC keys in CV certificates with the following algorithms:

SHA1WithRSA - id-TA-RSA-v1-5-SHA-1
SHA256WithRSA - id-TA-RSA-v1-5-SHA-256
SHA1WithRSAAndMGF1 - id-TA-RSA-PSS-SHA-1
SHA256WithRSAAndMGF1 - id-TA-RSA-PSS-SHA-256
SHA1WithECDSA - id-TA-ECDSA_SHA_1
SHA224WithECDSA - id-TA-ECDSA_SHA_224
SHA256WithECDSA - id-TA-ECDSA_SHA_256

Using the complementary project SignServer you can set up a clustered Document Signer.

Creating CVCAs and DVs

When creating a CVC CA there are three CA Reference fields in the standard. In EJBCA these are mapped to a DN structure to have common handling in EJBCA. The mapping is:

Country = C
Mnemonic = CN

For example when creating a country CVCA you select type CVC in the create CA page and enter a 'Subject DN' like: C=SE,CN=TESTCVCA. For the CVCA you select 'Signed by=Self Signed' and 'Certificate Profile=ROOTCA'.

Note that EJBCA only validates that country codes consist of two characters with value A-Z to facilitate testing with "fake" countries!

To create a DV you select 'Signed by=Name of CVCCA' and 'Certificate Profile=SUBCA'.

You can import a CVCA certificate from another country as an 'External CA' using 'Edit Certificate Authorities->Import CA certificate'. When a CA has been imported, this CA certificate can authenticate CVC requests from foreign DVs.

CVC Sequence

The sequence in the holder reference of EAC CVC certificates should identify a public key. For CAs created and managed by EJBCA this sequence is normally an automatic property in the CA token. It starts with 00001 and is increased when new keys are generated (renew CA with checkbox to renew keys checked).
You can also set a specific value for the initial sequence, which will then be increased when renewing keys, or you can change the sequence at any time. See section about Key sequence in User guide for more information.

For entity (IS, DV, AT and ST) requests that are received, the sequence in the issued certificates are taken from the request. The entity knows best how to index it's keys.

Terminal Types

EJBCA supports certificate hierarchies for Authentication (AT) and Signature Terminal (ST) end-entities, in addition to those with Inspection Systems (IS). Those roles are new in EAC 2.10. To use AT or ST certificates please create certificate profiles with the "Terminal Type" appropriately configured for your CAs and end-entities. The default mode is IS, so if there are no ATs or STs then you do not need to configure the Terminal Type setting.

EAC roles

When issuing a CV certificate using a Root CA profile the EAC role will be CVCA.
When issuing a CV certificate using a Sub CA profile the EAC role will be DV-D if the country is the same as the country of the CVCA and DV-F if the country is not the same as the CVCA.
When issuing a CV certificate using an End Entity profile the EAC role will be IS (or AT or ST if one of those terminal types is being used).

In a certificate hierarchy with the ST terminal type, the role of the DV is controlled by the "Signature Terminal DV role" setting in the profile. It can be either "Accreditation Body" or "Certification Service Provider".

EAC access rights

You can configure in the certificate profile which EAC access rights will be used for issued certificates. There are two configurable access rights, read access to DG3 and to DG4. Combinations can be selected by holding down Ctrl while clicking the items.

Since EAC 2.10 there are additional access rights which are used by Authentication Terminals and Signature Terminals. These are shown instead when selecting one of those terminal types.

Document verifiers (DV)

You create domestic DVs as simply as creating a SubCA to your CVCA, using a SubCA certificate profile.

You can sign foreign DVs by treating them as regular End Entities. Simply create an end entity and choose a SubCA certificate profiles when adding the end entity. You can then process the certificate requests received by the foreign DV as a regular end entity certificate request:

Using the public web GUI
Using the WS cli, clientToolBox CvcWsRaCli
Using the WS-API cvcRequest method from your own client

You can also create foreign DVs as external SubCAs, but a benefit of handling foreign DVs as end entities is that you can process and renew them using the same WS-API as you can use for inspection systems.

You can create a DV to be signed by a foreign CVCA by creating a new CA and selecting 'Signed By=External CA'. You need the CVCA certificate of the foreign CVCA to create the request to be sent. When creating this CA a self-signed CV certificate request is created.

You can at any time create a CV certificate request from a DV by going into 'Edit Certificate Authorities' and click 'Make Certificate Request'. This generates a CSR created by the CAs keystore. When receiving the signed certificate back, you can feed that to your IS-system. There is no need (or way) to import it into EJBCA.

You can renew a DV by going into 'Edit Certificate Authorities' and click 'Renew CA'. By uploading the CA certificate supposed to sign the certificate, you can get a new CSR created. You can import the received certificate by clicking 'Receive Certificate Response'. You only have to (or can) import one issued certificate to make your DV operational. If you get a DV signed by multiple CVCAs you can distribute the other, than the 'main', DV certificate to the IS's (or AT or ST) by other means.
By filling in the CA tokens password and checking the box 'Renew Keys' the DV will generate new keys. This works for both soft CA tokens and PKCS#11 CA tokens. The renewal CSR is not signed with the old keys, but that can be done manually.

DVs have short validity periods, and it may be good to have them automatically renewed. There is a service 'Renew CA Service' to automatically renew CAs. The User's Guide contain more information about this service.

Creating authenticated requests and link certificates

You can sign CV certificate requests by your CVCA or DV by going to 'Edit Certificate Authorities', typing the name of your CA in the text field (same name as appears in the list above the text field) and then clicking on 'Sign Certificate Request'. You will be a chance to upload the CV certificate request to the CVCA, and you will get an Authenticated request back. This is required when sending certificate requests from your DVs to other member states and when creating CVCA link certificates.

The renewing a DV and sending a request to another member state you can get the request automatically authenticated by signing the request with the DVs old keys. You can do this by first renewing the DV to create a new certificate request. Then you go into 'Sign Certificate Request' for the same DV and sign the request checking the checkbox 'Use previous key'. An authenticated request, authenticated with the DVs previous key will be returned.

To create CVCA link certificates the same approach is done. First renew the CVCA (generating new keys), which creates a new self-signed CVCA certificate internally. Download the new self-signed CVCA certificate (for example from Basic Functions). After this you can create a link certificate by typing the CVCAs name in the text field in 'Edit Certificate Authorities' and clicking 'Sign Certificate Request'. Upload the new CVCA certificate and select 'Use previous key' and 'Create link certificate'.

The reason for this cumbersome and a bit clumsy way to create link certificates is that issuing a link certificate can actually be made to switch CA completely, new keys, new algorithms and new Country/Mnemonic. Therefore you can use this approach to create a link certificate from you old CVCA to a completely new one.

Inspection Systems

The best interface for enrolling IS's is the Web service API. There is a method cvcRequest that implements initial issuance and automatic renewal of IS cvc requests.

Enrollment processing logic using WS API is:

A new IS with no old certificate issued must be pre-registered, be in status NEW and use a password.
An IS with status REVOKED or HISTORICAL can not be enrolled.
If the request is an authenticated request and the IS have an old valid (in time) certificate (in the EJBCA database) that can verify the outer signature, a new IS certificate is automatically allowed to be enrolled.
If the authenticated request can not be verified because the outer signature can not be verified at all (invalid signature or no verifying certificate in the EJBCA database), the request is rejected.
If the authenticated request can not be verified because the outer signature can be verified but the verifying certificate is not valid, the user must be in status NEW and use a password.

The complete certificate chain is always returned, with the IS certificate in the first position, DV certificate in the second and CVCA certificate last.

Revocation of an IS prohibits further issuance of certificates to that IS using the WS API.

There is a simple command line client for testing which is under dist/ejbca-ws-cli/cvcwscli.sh. This can be used to make requests and to parse, print and verify requests and certificates.

Note

Please note that IS end entity naming (CN, etc) must not be changed once a certificate has been issued to the IS end entity, as this will cause all future renewal to fail. Should this occur, a new IS end entity must be created.

Note

Existing IS end entities should not be reused for new systems or when replacing an old IS, but a new one should always be created.

Authentication and Signature Terminals

Please follow the same steps as in the previous section for Inspection Systems.

Web Service API

In the regular EJBCA WS-API there is a method for enrolling and renewing DVs and ISs: cvcRequest

The process when a CVC request is received through the WS-API call is:

Look up if there exists a user with the specified username.
If the user exists:

If the user's status is revoked, the request is denied (AuthorizationDeniedException).
See if the user have old certificates.
If there are old certificates and the request is an authenticated request (with outer signature):

If the request uses the same public key as the old certificate the request is denied (AuthorizationDeniedException).
If the old certificate can verify the request but the certificate is not valid we throw a CertificateExpiredException (in EJBCA 3.7.4 and earlier we tried to process the request as a non-authenticated request instead).
If the request can be verified using one of the old valid certificates the request is automatically granted and users status is set to new and the password set to the given password.
If the request can not be verified at all the request is denied (AuthorizationDeniedException).

If there are no old certificates we try to process the request as a non-authenticated request.

If the user does not exist we try to process the request as a non-authenticated request.
Processing the request as a non-authenticated request means that we try to authenticate using the password given, and that only works if the users status is NEW.

There are two more useful Web Service APIs that can be used from for example a SPoC in order to renew DVs: caRenewCertRequest and caCertResponse

Command line client

there is a command line client using the WS-API. You can use this for reference and sample how to use the WS-API.

The command line client have two functions:

cvcrequest - adds a new user and requests a CV Certificate.
cvcgetchain - retrieves the last certificate chain for a user.
cvcprint - used to parse and print CV Certificate and requests.

Type the command on the command line to get usage information.

ejbca> cd dist/clientToolBox
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli
Usage: cvcrequest cvcgetchain cvcprint cvcpem
  
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest
Usage : cvcrequest <username> <password> <subjectdn> <sequence> <caname> <signatureAlg> ...
...
  
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcprint
Usage : cvcprint <filename> [verifycert]
...

CLI authentication and privileges

The CLI uses client certificate authentication, and as such is allowed to perform administrative tasks in EJBCA as long as your client certificate has the correct RA administrator privileges in EJBCA.
To issue certificates for a request, an end entity must first be added in EJBCA. Unauthenticated requests entered using the CLI is authenticated using a one-time password set during entity registration.
Authenticated requests however are verified and granted or rejected based on the verification of the outer signature on the request. If an end entity already exists, and have a previously issued certificate, the previous certificate can authenticate the request and automatically grant it.
For DV requests, authenticated with a CVCA certificate, the CVCA certificate instead of a previously issued certificate can authenticate the request.

CLI examples

The command line interface is part of the client tool box. First you have to build the client tool box (that can be used from any remote computer):

ant clientToolBox
cd dist/clientToolBox

1.
Example command to receive a request from a foreign DV could look like:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser dv-de foo123 false "CN=dvca,C=DE" NULL NULL CVCAPK 1 USERGENERATED NEW DV DV

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest dv-de foo123 "CN=dvca,C=DE" SE001 SHA256WithRSA 2048 false dedv

Where your CVCA is called CVCAPK in EJBCA and uses algorithm SHA256WithRSA with 2048 bit keys.
Where an End entity profile, DV, is created with CN and C as required DN fields, and DV as available certificate profiles.
Where a Certificate profile, DV, is created of type SubCA.
Where the received request is stored in a file 'dedv.cvreq'.

The first command adds the end entity in EJBCA and only has to be made the first time. foo123 is the one-time password set to authenticate the request.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA (Edit Certificate Authorities->Import CA certificate), the request will be verified and granted. For authenticated request the one-time password is not used.

2.
An example command to generate keys and a request for an IS using SHA256WithECDSA and secp256r1 curve:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser issecp foo123 false "CN=ISSECP,C=SE" NULL NULL DVCA 1 USERGENERATED NEW IS IS

This command adds the IS as end end entity in EJBCA. It only has to be done the first time, or if the IS previous certificates expire. When using authenticated requests these are used instead of the one-time password, but if the previous certificate expires, a new one-time password is needed to authenticate the request.

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00005 SHA256WithECDSA secp256r1 true issecp

Where your DV is called DVCA in EJBCA and uses algorithm SHA256WithECDSA with secp256r1 curve. Where an End entity profile, IS, is created with CN and C as required DN fields, and IS as available certificate profiles.
Where a Certificate profile, IS, is created of type EndEntity.
Where the generated request is stored in a file 'issecp.cvreq', the generated private key in 'issecp.pkcs8'.
The issued IS certificate is stored in file 'issecp.cvcert'.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA, the request will be verified and granted.

To create an authenticated request for this user you can issue the following command, which authenticates the new request with the old key and certificate.

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00006 SHA256WithECDSA secp256r1 true issecpnew issecp.pkcs8 issecp.cvcert

The request will be automatically granted (the password passed will be ignored) and the new certificate will be written to 'issecpnew.cvcert'.

Importing CAs

For test purposes you may receive a private key and a CV certificate for the CVCA trust point used by the passport manufacturer when creating specimen passports. To test your process and inspection systems you can import a CVCA (with soft keystore) in EJBCA if you have a PKCS#8 private key and a CV certificate with the public key.

bin/ejbca.sh ca importcvca

Example import command using the given CV Certificate:

bin/ejbca.sh ca importcvca importcvca1 GO_CVCA_RSA2008.pkcs8 GO_CVCA_RSA2008.cvcert C=SE,CN=IMPCA1

Example import command using the same private/public keys but generating a new certificate:

bin/ejbca.sh ca importcvca importcvca1 GO_CVCA_RSA2008.pkcs8 GO_CVCA_RSA2008.cvcert C=SE,CN=IMPCA1 SHA1WithRSA 365

Using HSMs

The EU policy surely requires that you use an HSM to protect the CAs signature keys. Depending on the algorithms you choose you have different options and difficulties. Using PKCS#11 the Sun PKCS#11 provider only supports RSA with PKCS1 padding (SHA256WithRSA), and not PSS (SHA256WIthRSAAndMGF1). If you want to use the PSS algorithms you need to use the IAIK PKCS#11 provider. See the User's Guide for instructions how to use the IAIK PKCS#11 provider.
The same goes for ECC, check with your HSM vendor about support for ECC.

Currently tested HSMs are:

Utimaco
SafeNet
nCipher

There are four additional key properties (filled in the CAs token properties) when using a HSM controlling the use of the previous keys.

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.

Normally these properties are set completely automatically when you generate new keys from the Admin GUI. If keys are generated manually, or if there is a problem these properties can be modified or set manually.

Generating keys

Generating keys on an HSM can be done with the tool ejbcaClientToolBox.sh PKCS11HSMKeyTool.

cd dist/clientToolBox
./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /etc/utimaco/libcs2_pkcs11.so secp256r1 signKey 1

See User Guide for more general information about generating keys. For supported curves, see your HSM documentation. For example for Utimaco it can be found in chapter 8 of CS_AdminGuide.pdf.

Note that the Java PKCS#11 provider may not support all curves that your HSM supports.

To generate EC keys using the ejbcaClientToolBox.sh tool, a patch for JDK is needed due to a bug in JDK (see below).

Note that generation command may be different for different HSMs, see the HSM section in the User Guide for more details. For example on the SafeNet ProtectServer Gold you should use:

./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /slot1.cfg secp256r1 signKey

* Generating keys using HSM tools *

Depending on your HSM you may be able to generate keys, and the needed self signed certificate associated with it using HSM tools. For example for the SafeNet ProtectServer you can see the HSM documentation in the EJBCA User Guide for an example how to generate ECC keys for EJBCA using the HSM tools.

Using EC keys

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

PEM requests

Processing certificate requests in the Admin-GUI of EJBCA can use wither binary or PEM format certificate requests. If you receive a binary request and want to convert it to PEM it is easy:

Base64 encode the request, for example with openssl base64 -in MY.cvreq -a -out MY.cvreq.pem.
Add -----BEGIN CERTIFICATE REQUEST----- in the beginning of the file.
Add -----END CERTIFICATE REQUEST----- in the end of the file.

Example:

SPOC PKI

The SPOC CA is a regular X.509 CA and is configured as such, following the profiles of the SPOC specification (CSN 369791:2009).

The only thing in the specification of the SPOC CA that requires configuration is two private Extended Key Usages that are defined in the standard.

EJBCA 4.0 and later

From EJBCA 4.0 these key usages are standard and can be selected in certificate profiles.

EJBCA 3.11 and earlier

For EJBCA 3.11 and earlier you need to configure conf/extendedkeyusage.properties and add the two new key usage OIDs.

extendedkeyusage.oid.23 = 1.2.203.7064.1.1.369791.1
extendedkeyusage.name.23 = CSN369791-TLS-CLIENT 
extendedkeyusage.oid.24 = 1.2.203.7064.1.1.369791.2
extendedkeyusage.name.24 = CSN369791-TLS-SERVER

If the numbering have changed (i.e. other standard extended key usages have been added) since the publication of this sample, just make sure the numbers (23 and 24) are changed to follow consecutive numbering in the file.

After this change you simply have to re-deploy ejbca (ant clean; ant deploy) and they will show up as selectable values in Certificate Profiles in the EJCBA admin GUI.

A SPOC client should use "Client Authentication, CSN369791-TLS-CLIENT" and a SPOC server should use "Server Authentication, CSN369791-TLS-SERVER".

EJBCA support, development and maintenance by