EJBCA - Open Source PKI Certificate Authority
Search ejbca.org for:

Introduction

This User Guide contains guides and information how to perform day to day administrative tasks in EJBCA. It also contains information about fields that you find in the various section of the administrative interfaces. This guide is constant work in progress and if you would like to see a new section added, please contact us.

To go straight ahead and learn how to configure profiles and issue server certificates you can follow the guides:

  1. Create a Certificate Profile for SSL servers
  2. Create an End Entity Profile for SSL servers
  3. Issue a new end entity certificate for an SSL server

EJBCA Administration

Administrative tutorials

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

Administrating EJBCA

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

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

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

Finally you can also use the EJBCA client toolbox to perform administrative tasks using web services.

Admin GUI overview page

The first page of the admin GUI can display status information for the publish queue and the CA. Which of those that should be displayed can be configured in My Preferences.

Publish queue status

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

CA Status

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

Managing CAs

Creating CAs

After installation, which creates a default admin CA you can create more CAs.
Creating CAs can be made using the Admin-GUI or the command line interface (cli). The recommended way is using the Admin-GUI, since it gives more control of all parameters.

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

*** Using CLI ***

You can create CAs using the cli command:

ejbca.sh ca init

Issuing the command will give usage instructions. An example is:

bin/ejbca.sh ca init TestRoot "C=SE,O=PrimeKey,CN=TestRoot" soft foo123 2048 RSA 265 2.5.29.32.0 SHA256WithRSA

This will create a root CA with the DN 'C=SE,O=PrimeKey,CN=TestRoot'. The keylength is 2048 bit (RSA) and the validity of the root certificate is 365 days. You need to quote the DN so it is treated as one argument.

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

*** Using Admin-GUI ***

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

CA fields

*** Type of CA ***

Type of CA can be either X509 or CVC.
An X509 CA is a normal CA for secure email, login, web authentication, VPN etc etc.
A CVC CA is a CA issuing CV certificates, which are special certificates for EU EAC ePassports. CVC CAs are described in depth in the document about CVC CAs.

*** Key sequence ***

CVC Sequence
The key sequence is used in the certificate holder reference of an EAC CVC certificate / certificate request. According to the BSI specifications the sequence must be 5 bytes long. The initial value must be specified in the sequence field. The sequence MAY start with an iso 3166-2 countrycode.

When renewing keys for HSMs using the Admin-GUI, the new signing key label will be the old label with the new key sequence in the end. When renewing keys for HSMs using the Admin-GUI the key sequence is automatically increased.

For X.509 CAs the key sequence should not be important, except for key labels when renewing keys.

If you are unsure of the key sequence you can safely leave it to be handled automatically.

*** Key sequence format ***

Within EAC, there are several options regarding the sequence format. The format can be choosen in the field "Key sequence format". The following options are available:

5 byte numeric
The sequence MUST contain numeric characters [0-9]. The sequence shall be increased from 00000 to 99999
5 byte alphanumeric
The sequence MUST contain alphanumeric characters [0-9][A-Z]. The sequence shall be increased from 00000 to ZZZZZ
2 byte country code, 3 byte numeric
The sequence must start with a 2 byte country code (e.g. SE). The other bytes shall be increased from 000 to 999
2 byte country code, 3 byte alphanumeric
The sequence must start with a 2 byte country code(e.g. SE). The other bytes shall be increased from 000 to ZZZ
For X.509 the 5 byte numeric is recommended

*** Enforce unique public keys ***

'Enforce unique public keys' guarantees that certificates with the same public key can only be issued to the same user from this CA. This means that a user is allowed to have multiple certificates (e.g. due to renewal) with the same key as long as the same 'username' is used, but two users can not share the same public key. The check is only performed when new certificates are issued.

*** Enforce unique DN ***

'Enforce unique DN' guarantees that certificates with the same Subject DN can only be issued to the same user from this CA. This means that a user is allowed to have multiple certificates (e.g. for different uses) with the same Subject DN as long as the same 'username' is used, but two users can not share the same Subject DN. The check is only performed when new certificates are issued.

*** Enforce unique Subject DN serialNumber ***

'Enforce unique Subject DN SerialNumber' guarantees that only one end entity with a specific Subject DN SerialNumber can be issued from this CA. When adding a new end entity, a check is done to ensure that there are no other end entities, issued by this CA before, have the same Subject DN SerialNumber. Note that end entities issued from other CAs can have the same Subject DN SerialNumber as end entities issued from this CA.

Note
Note that this option is currently extremely inefficient and will only work with a low number of users, in the hundreds or a few thousand. This is due to the face that it select all users from the database registered for a specific CA. Future versions of EJBCA can optimize this query.
*** Use Certificate Request History ***

The Certificate Request History stores the values used when generating a certificate for an end entity. Since the values of the end entity, such as the DN, can be edited between requests, this function ensures that there is a possibility to trace the values used for issuing a certain certificate. Information stored is:

  • fingerprint
  • serialNumber
  • issuerDN
  • username
  • timestamp
  • UserDataVO
The certificate request history is enabled by default, but you may turn it of to maximize performance and save database space.

The impact of loosing CertReqHistoryData and that you can not see the exact values of the UserDataVO that was in effect when the certificate was issued. This is mostly interesting if you use a subset of the user DN in the certificate (see certificate profile), and in this case it can also affect publishing and re-publishing of certificates. If you are not using a subset of user DN in the certificates using this feature should be safe, but still needs thorough testing in your environment. If unsure leave enabled.

*** Use User Storage ***

Certificates are normally issued in a two step process where a User is first added to the database with a username, password and additional information that should go into the certificate. Later EJBCA processes a request that this user should be issued a certificate and the provided credentials (username and password) is verified with the stored User data. In the EJBCA Admin GUI it is currently only possible to search for Users and not certificates, so without this enabled, the Admin GUI will not be very useful.

The user data storage is enabled by default.

If EJBCA is used as a factory and where the functionality of the Admin GUI is not required, this could be disabled to improve performance.

See Throw away CA in the admin guide for more information about this option.

*** Use Certificate Storage ***

Issued certificates are stored in the database to be able to provide them upon request or provide revocation information.

The certificate data storage is enabled by default.

If EJBCA is used as a factory and where the functionality of the Admin GUI is not required, this could be disabled to improve performance.

See Throw away CA in the admin guide for more information about this option.

*** CRL Period ***

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

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

*** Finish User ***

The Finish User configuration defines if the CA calls a process called "finishUser" after a certificate has been issued for an end entity. This process is what makes the user's password a one-time password, i.e. it removes the password and/or decreases the password use count.

  • With this setting enabled (default) an end entity password can only be used once (or as many times as defined in 'Number of allowed requests' when adding the end entity) to enroll for a certificate. After the certificate has been issued the user status is set to 'Generated' and the password blanked. When status is 'Generated' a new certificate can not be issued until status is reset to 'New', usually by editing the end entity.
  • With this setting disabled the password can be used unlimited number of times to enroll for certificates, and the status stays as 'New' after each time.

*** CMP RA Authentication Secret ***

CMP can be configured in RA mode to use one shared secret for each CA to authenticate messages from the RA. If "cmp.ra.authenticationsecret" in cmp.properties is set, this field will be ignored.

An empty value in this field will deny all RA mode CMP requests (if cmp.ra.authenticationsecret is not set).

Creating a SubCA signed by an external CA

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

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

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

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

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

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

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

Signing an External CA

In some cases you might want to have one of your CA:s signing another external CA. This can be done in two ways:

  1. Create a certificate profile and an end entity profile for Sub CAs. The certificate profile must be of type 'Sub CA' (almost at the bottom of the edit certificate profile page).
  2. Create an End Entity where you select a SubCA certificate profile when adding the end entity.
  3. Issue the CA certificate as you would normally issue any end entity certificate.
  4. The SubCA can be managed and revoked conveniently just as other end entities.
Using an end entity is the recommended way to sign Sub CAs, because of the better management features.

You can however also get the external Sub CA visible as a CA in EJBCA.

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

Renewing a SubCA signed by an external CA

When you renew a SubCA signed by an external CA you create a new request that is sent to the external CA. The External CA issues a new certificate that you import in your SubCA.

You can renew the SubCA in two ways:

  1. Using the same CA signing keys.
  2. Generating new CA signing keys.
To renew a CA go to "Edit Certificate Authorities" select the SubCA and use the button "Renew CA" in the bottom of the page. When you use the same signing keys there is nothing in particular to consider. When you also choose to renew the CA signing keys (check the checkbox "Renew keys") you must give the CA Token password as input to the renewal process, i.e. fill in the field "Authentication code for renewing keys". When you renew keys in an active SubCA you can choose:
  1. Activate keys (default) - immediately activates the new keys. This makes the SubCA off-line waiting for the certificate response. The SubCA can not issue certificates until the response from the External CA is received.
  2. Do not activate keys - generates new keys and a request, but does not activate the new keys. The SubCA can continue to issue certificates with the old signing keys until the response is received from the External CA.
If you choose to not activate the new keys immediately you must give the CA Token password when receiving the response from the External CA.

Not that how PKCS#11 works with sessions, once logged in to the session you are logged in and it does not matter which password you use in the GUI. Don't be surprised that it works with any password when using PKCS#11 CA tokens.

Requesting a cross or bridge certificate

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

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

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

Signing a roll-over certificate (NewWithOld)

One way to handle update of trust points when renewing a Root CA is to generate a certificate that contains the new key signed with the old key. For X.509 CAs you can create such a certificate:

  1. In 'Edit CA' screen, renew a Root CA, selecting to also renew keys.
  2. Download the new Root CA certificate.
  3. In the Edit Certificate Authorities screen, type the name of the CA in the input field and click 'Sign Certificate Request'.
  4. Upload the new Root CA certificate, select the checkboxes 'Use previous key' and 'Create link certificate' and click 'Sign Certificate Request'.

The certificate that you upload must have the same DN as the CA you selected, and the certificate must also be verifiable using the CAs currently active signature keys. This means that you can only use this function to create a 'NewWithOld' certificate, and not for other signing purposes.

Converting an OpenSSL CA

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

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

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

Certificate profiles

CertificateProfiles define different types of certificates, with regards to DN-contents, extensions etc.

Create a Certificate Profile for SSL servers

This section will show you how to create a certificate profile suitable for SSL/TLS servers, such as web servers.

  • Under "CA Functions", press "Edit Certificate Profiles".
  • Enter a name for your end entity certificate profile e.g. "SSLServerCertificateProfile", and press "Add".
  • Select "SSLServerCertificateProfile" and press "Edit Certificate Profile".
  • Under "Validity" enter 365d (1 year validity).
  • Under "Key usage", choose "Digital Signature" and "Key encipherment (ctrl-click to select multiple).
  • Un-check "Allow Key Usage Override".
  • Check "Use Extended Key Usage".
  • Under "Extended Key Usage", choose "Server Authentication".
  • Under "Available bit lengths", "1024 bit", "2048 bit" and "4096 bit".
  • Under "Available CAs", choose your CA "AdminCA1" (the CA you use to issue server certificates).
  • Under "Type", select "End Entity".
  • Press "Save"

Certificate Profile fields

*** Validity ***

The validity determines the validity in days of certificates from the time the certificate is issued. The field 'notAfter' in the issued certificate will have the value 'now + validity days'. It can also, if noted in the field, be entered in terms of years, months and days. For instance '10y 9mo 8d' is translated to 10 years, 9 months and 8 days from now. Instead of the validity period an absolute end date could specify the end of the validity period. This date should be given in the default locale for the jvm.

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

The validity of a certificate is determined as follows:

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

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

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

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

The last option you have is to set a global maximum validity date for certificates issued from the EJBCA instance. You can do this by setting the option 'ca.toolateexpiredate' in ejbca.properties. See the documentation in conf/ejbca.properties.sample for more details. If a validity period would exceed this value, if it is configured, an error occurs and no certificate is issued.

*** Allow extension override ***

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

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

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

*** Allow subject DN override ***

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

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

*** Allow certificate serial number override ***

The generated certificate serial number could be overridden if "Allow certificate serial number override" is enabled in the used certificate profile.

If the admin web GUI should be used for creating entities you must also add "Custom certificate serial number" to the used end entity profile.

With web services you use the 'setCertificateSerialNumber' for your 'UserDataVOWS' user.

Please note that the row 'serialNumber' number in the table 'CertificateData' of the database must have an unique index for this feature to work should work, normally you use an index for unique issuerDN, serialNumber. Without index the feature is automatically disabled.

create unique index certificatedata_idx1 on CertificateData (issuerDN,serialNumber);

If you run the WS stress test of clientToolBox you may specify that the test should use 'setCertificateSerialNumber'. A new random serial number will then be used for each created user. The java system property 'maxCertSN' specifies how many bits that should be in the serial number. Example:

JAVA_OPT="-DmaxCertSN=16" $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh EjbcaWsRaCli stress WsCA1 20 2000 wsCreatedUser wsCreatedUser
*** Path Length Constraints ***

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

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

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

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

A CRLDistributionPoint for a CA in EJBCA could look like:

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

(such as the link from the web distribution pages)

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

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

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

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

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

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

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

Please note that if an URI contains a ';' it has to be double-quoted. For example if you have two URLs:

  • http://cdpurl-1/mycrl.der
  • http://cdpurl-2/getcrl;binary
You could then put them together as:
http://cdpurl-1/mycrl.der;"http://cdpurl-2/getcrl;binary"

*** CRL Issuer ***

According to RFC3280 a CRL issuer is:

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

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

*** Freshest CRL ***

(a.k.a. Delta CRL Distribution Point)

The Freshest CRL extension is used for Delta CRLs. How to issue delta CRLs is explained in CA configuration. The freshest CRL extension identifies how delta CRL information is obtained. The same syntax is used for this extension and the cRLDistributionPoints extension,

*** OCSP Service Locator ***

This extension is used when revocation information for the certificate containing this extension is available using the Online Certificate Status Protocol (OCSP) [RFC2560]. The URI field is the location of the OCSP responder, using the conventions defined in RFC2560, usually a plain URL such as http://ocsp.company.com/. The default URL for the internal OCSP responder in EJBCA is http://hostname:8080/ejbca/publicweb/status/ocsp.

*** Use LDAP DN order ***

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

  • Ldap DN order (rfc 2253): CN=Common Name, O=Organization, C=Country
  • X.500 DN order: C=Country, O=Organization, CN=Common name
In theory the order of the DN should not matter, because comparisons between DNs should be done on the RDN level. In practice DN comparisons is often done using string comparisons, where the string value is depending on the order.

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

  • In the Certificate profile (Edit certificate profiles)
  • In the CA configuration (Edit Certificate Authorities)
The relationship between the settings is that they are both evaluated in an OR expression. This means that if both are true the DN will have Ldap DN order, but if any one of them is false the DN will have X.500 order.

*** Extended Key Usage ***

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

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

*** Cardnumber ***

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

End Entity profiles

EndEntityProfiles defines which parts of user DN should be registered for various types of end entities. It defines which parts that is already pre-set, and which can be altered etc. It also contains other information, that is specific to each individual end entity, for issuance of certificates.

An EndEntityProfile can be connected to specific CertificateProfiles so users belonging to a specific EndEntityProfile can only get certificates from the specified CertificateProfile.

Create an End Entity Profile for SSL servers

This section will show you how to create an end entity profile suitable for SSL/TLS servers, such as web servers. You should previously have created the certificate profile for SSL servers.

  • Under "RA Functions", press "Edit End Entity Profiles".
  • Enter a name for your end entity profile e.g. "SSLServerEndEntityProfile", and press "Add".
  • Select "SSLServerEndEntityProfile" and press "Edit End Entity Profile".
  • Under the "Subject DN Fields" select "O, Organization" and press "Add".
  • At "O, Organization" enter "EJBCA Edu" in the textbox, check the "required" checkbox and uncheck the "modifiable" checkbox.
  • Under the "Subject DN Fields" select "C, Country" and press "Add".
  • At "C, Country" enter "SE" in the textbox, check the "required" checkbox and uncheck the "modifiable" checkbox.
  • Under the "Subject Alternative Fields" select "DNS Name" and press "Add".
  • Uncheck "Use" at "Email Domain".
  • Under "Default Certificate Profile", choose "SSLServerCertificateProfile" (created earlier).
  • Under "Available Certificate Profiles", choose "SSLServerEndEntityCertificateProfile".
  • Under "Default CA", choose "AdminCA1" (the CA you use to issue server certificates).
  • Under "Available CAs", choose "AdminCA1" (same as above).
  • Under "Default Token", choose "P12".
  • Under "Available Tokens", choose "P12", "JKS" and "PEM" (ctrl-click to select multiple).
  • Press "Save".

End Entity Profile fields

*** Subject DN Fields ***

Subject DN fields define which DN components should be present for an end entity. If "Enable End Entity Profile Limitations" in the "System Configuration" is enabled this restricts the values that can be used when adding or editing an end entity using all interfaces, be it web GUI, web service, cmp or something else. If you define values as required and non-modifyable you can specify one or more values. If you specify multiple values separated by ';', the admin in the web GUI will get a drop-down list to select from.

When having several fields of a certain type with mixed required and not required fields some special handling might be needed when adding users using web sevrice API. If you have for example:

  • The first OU field is required (Bar1) and not modifiable.
  • The next 3 OU fields are modifiable only (not required).
  • The last OU is required (Bar1) and not modifiable.

Then when adding an end entity with DN "CN=Foo,OU=Bar1,OU=Bar2" will result in an error:

org.ejbca.core.model.ra.raadmin.UserDoesntFullfillEndEntityProfile: Subject DN field 'ORGANIZATIONUNIT' must exist. 

This is because EJBCA can not keep track of which fields you mean to set, if it is one of the required or non-required. To help EJBCA determine this you can specify the non-required OU fields with empty values, "CN=Foo,OU=Bar1,OU=,OU=,OU=,OU=Bar2".

*** Subject Alternative Names ***

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

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

IP address

An IP address can be either an IPv4 address or an IPv6 address.
Example IPv4:

192.168.2.54

Example IPv6:

2001:DB8:85A3:0:0:8A2E:370:7334
Krb5 Principal Name

The Krb5 principal name is of the form "principal1/principal2@realm", and should be entered as such in the field. Example:

user@PRIMEKEY.SE

for a normal user in the realm PRIMEKEY.SE.
Or:

krbtgt/PRIMEKEY.SE@PRIMEKEY.SE

for a kdc.

*** Certificate Validity ***

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

*** Revocation reason to set after certificate issuance ***

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

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

*** Reverse Subject DN Alt Name Checks ***

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

*** Maximum number of failed login attempts ***

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

End Entities

Creating Users

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

Issue a new end entity certificate for an SSL server

This section will show you how to issue a certificates suitable for SSL/TLS servers, such as web servers. You should previously have created the certificate profile and end entity profile for SSL servers.

  • Goto "RA Functions" -> "Add End Entity".
  • Choose the end entity profile "SSLServerEndEntityProfile".
  • At "Username" enter "testsrv.domain.com".
  • At Password enter a password.
  • Under "CN, Common Name" enter "testsrv.domain.com".
  • And at "DNS Name" enter "testsrv.domain.com".
  • Under "Certificate Profile" you should not be able to choose anything but the default "SSLServerCertificateProfile".
  • Under "CA" you should not be able to choose anything but the default "AdminCA1".
  • Under "Token", choose "P12".
  • Press "Add End Entity".
  • Goto "Public Web" and then "Create Keystore".
  • Enter the username, testsrv.domain.com, and password for the user you created, and press "OK".
  • Choose "Key length" "1024".
  • Under "Certificate Profile" you should not be able to choose anything but the default "SSLServerCertificateProfile" .
  • Press "OK".
  • A new certificate will be generated and downloaded to your desktop.
  • If you like you can import the P12 file (double-click it on windows) to look at the certificate inside.

Create User certificates

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

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

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

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

Create server certificates

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

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

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

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

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

openssl pkcs12 -in pkcs12-file -nodes

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

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

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

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

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

Request Browser Certificate Renewal

If renewal is enabled there is an extra link under "Enroll" on the public web page called "Request Browser Certificate Renewal". The page requires authentication with a client certificate and makes it possible for the user to request the certificate to be renewed.

The renewal functionality is provided in a separate web module called renew.war which is not deployed and linked to by default. It can be enabled in conf/web.properties by setting web.renewalenabled=true and then (re-)deploy EJBCA.

Administrators

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

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

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

Administrators issued by external CAs

Administrator certificates in EJBCA does not have to be issued by a CA in the same installation, but can be issued by any other CA. By leveraging this feature you can for example use a national ID for administration of an organizational PKI

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

  1. Add the CA-certificate to p12/truststore.jks with "keytool -import -trustcacerts -file externalca.pem -keystore p12/truststore.jks -storepass changeit -alias externalca"
  2. Redeploy EJBCA (ant deploy) and restart the application server to make sure the new truststore is in use
  3. Import the CA-certificate under "Admin GUI - Edit Certificate Authorities - Import CA Certificate.." or use the CLI
  4. Add the Administrator to the desired Administrator group under "Admin GUI - Edit Administrator Privileges"
  5. To allow administrators to log in when their certificates are not present in the EJBCA database you have to set web.reqcertindb=false in conf/web.properties.

*** Installing EJBCA with external administrators ***

You can even install an EJBCA instance from scratch, with a certificate from an external CA as the initial SuperAdmin certificate. Start with bootstrapping EJBCA as usual with 'ant bootstrap', but instead of running 'ant install' you run:

bin/ejbca.sh ca importcacert AdminCA adminca.pem -initauthorization

This command imports the certificate of the external Administration CA and initializes the authorization system of EJBCA. You need to configure SSL and the truststore of the application server yourself, of you have a p12/tomcat.jks and p12/truststore.jks this can be done for you on JBoss by 'ant deploy'.

The initial administrator that is set up has DN 'CN=SuperAdmin', but you can change this using the -superadmincn (run 'bin/ejbca.sh ca importcacert' for documentation). Also check the 'bin/ejbca.sh admins' command for information how to configure other admins.

After this command is run, and SSL configured correctly, you can log in to EJBCA and create your CAs in the admin GUI. No initial CA is created for you.

*** Events Log ***

When viewing Ejbca log, a link is provided to view the administrator's certificate in the database. However, the administrator who has his/her certificate issued by an external CA does not have a certificated stored in the database. So when the external administrator logs in, its certificate serialnumber, issuerDN and subjectDN are stored in the log-file. When viewing the log, instead of the link, the external administrator's certificate serialnumber and issuerDN are displayed. In addition, when the viewed event is "Administrator Logged In", even the external administrator's certificate subjectDN is displayed.

*** When Approving Actions ***

When there are actions the administrator has to approve, the current administrator's username and e-mail address from the database are compared with those of the requesting administrator and those administrators who already approved the request to ensure that only legitimate administrators are to approve the current request. However, the administrator whose certificate is issued by an external CA has neither username or e-mail address stored in the database. Instead, the administrators' "admindata" are compared to establish the legitimacy of the acting administrator. "admindata" is a string containing the administrator's certificate serialnumber and issuerDN.

Renewing Superadmin

Renewing the superadmin certificate is done in the same way as for any client certificate. You can use both the GUI or the CLI to renew the superadmin. The superadmin certificate is normally issued as a PKCS#12 keystore (if not issued as a browser certificate for smart card enrollment).

Using the admin GUI:

  • Go to Search/Edit End Entities.
  • Search for user 'superadmin'.
  • Click Edit End Entity.
  • Set a new password and set status to NEW, click Save.
  • Go to Public Web and then Create Keystore.
  • Enter superadmin username, and the password you gave.
  • In the next screen, select key length 2048 and click OK.
  • Your new superadmin keystore is downloaded. You can install it in your browser.

Using the CLI:

bin/ejbca.sh ra setuserstatus superadmin 10
bin/ejbca.sh ra setclearpwd superadmin password
bin/ejbca.sh batch

Your new superadmin keystore is generated and stored in sudirectory p12. The password is password, as given to the setclearpwd command.

Administrator roles

This section is a tutorial that will guide you through creating a new administrative user and new administrative group with limited privileges.

Pre-defined roles

The current predefined administrator roles that exists in EJBCA are:

  • The CA administrator:
    • manages certificate profiles
    • manages end entity profiles
    • manages log configuration
    • can create RA administrators
    • can renew a CA with new certificate and new keys
  • The RA administrator:
    • can create end entities
    • can modify end entities
    • can revoke end entities
    • can delete end entities
    • can view existing end entities and their history
  • The supervisor:
    • can view created end entities
    • can search the log and see who have done what
  • The super administrator:
    • has overall access to EJBCA
    • can edit system configuration
    • can manage CAs
    • can manage publishers (LDAP, AD, custom)
    • can create CA administrators

Creating a Certificate Profile For the Administrator

This section will show you how to create a new Certificate Profile for administrators. The administrators certificates will be issued by a CA called AdminCAv1

  • Under "CA Functions" -> "Edit Certificate Profiles"
  • Enter a name for your end entity certificate profile e.g. "AdministratorEndEntityCertificateProfile"
  • Select "ENDUSER"
  • Press "Use Selected as Template"
  • Select "AdministratorEndEntityCertificateProfile"
  • Press "Edit Certificate Profile"
  • Under "Validity" enter 365d (1 year validity).
  • Under "Key usage", choose "Digital Signature" and "Key encipherment (ctrl-click to select multiple).
  • Un-check "Allow Key Usage Override".
  • Check "Use Extended Key Usage".
  • Under "Extended Key Usage", choose "Client Authentication".
  • Under "Available bit lengths", "1024 bit", "2048 bit" and "4096 bit".
  • Under "Available CAs", choose "AdminCA1" (the CA you use to issue admin certificates).
  • Press "Save".

Creating an End Entity Profile for the Administrator

This section will show you how to create a new End Entity Profile for administrators. The profile will be connected to the Certificate Profile created above.

  • Under "RA Functions" -> "Edit End Entity Profiles"
  • Enter a name for your end entity profile, "AdministratorEndEntityProfile"
  • Press "Create"
  • Select "AdministratorEndEntityProfile" and press "Edit End Entity Profile"
  • Under the "Subject DN Fields" add a few DN fields that you want in the admin DN, for example O, UID and C.
  • Under "Default Certificate Profile", choose "AdministratorEndEntityCertificateProfile"
  • Under "Available Certificate Profiles", choose "AdministratorEndEntityCertificateProfile"
  • Under "Default CA", choose "AdminCAv1"
  • Under "Available CAs", choose "AdminCAv1"
  • Press "Save"
Issue the following new end entity based on the new end entity profile.
CN: SoftCard RA Admin1

Creating a new RA Administrator group

The RAadmin shall have access to add/list/edit end entites. To create a new administrator group:

  • Choose "Edit Administrator Privileges" in the left frame.
  • Press "Add".
  • Choose a name for your new administrator group, "RAAdministratorGroup".
  • When the group is created, press "Access Rules".
  • Choose the administrator groups role, "RA Administrator".
  • Under "Authorized CAs", choose which CAs the administrator group should have access to. Choose "AdminCAv1".
  • Under "Edit End Entity Profiles" Select "AdministratorEndEntityProfile".
  • Press "Save".

Adding new Administrators to the RA Administrator group

  • Choose "Search/Edit End Entities" and select your newly created end entity, choose "View Certificates".
  • Copy the value of "Certificate Serial Number", e.g. "5F003A0113F507F9".
  • Go to "Edit Administrator Privileges", press "Administrators" under "RAAdministratorGroup".
  • Choose the CA that the administrator belongs to, "AdminCAv1".
  • Paste the text from "Certificate Serial Number" in the "Match value".
  • Press "Add"

Test the new administrator

Try to log in with the new administrators to see the difference between that and the superadmin.

You should also try the different roles and privileges to see the differences between them all.

EJBCA client toolbox

There is a set of tools that could be used without an EJBCA. Built from the EJBCA source, but the resulting distribution package can be moved to any machine. The client toolbox provides commands to function as a Web Service RA, to manage keys on PKCS#11 HSM, to perform EJBCA health checks, to enroll CVC EAC certificates, to test CMP and SCEP protocol, and much much more.

Build these tools with:

ant clientToolBox

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

To use any of the tools just call 'ejbcaClientToolBox.sh' in this directory. You may call the script from any location. Running the command will provide on-line documentation for available commands and options.

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

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

ejbcaClientToolBox.sh

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

ejbcaClientToolBox.sh ocsp

EJBCA Batch Enrollment GUI

The EJBCA Batch Enrollment GUI is a standalone Java desktop application which can be used to enroll multiple end entities from certificate signing requests at once. The application uses the web services interface for communication with EJBCA so an authorized administrator needs to be logged in to it in order to perform the operations.

Building and running

The application is built from the EJBCA directory by typing 'ant batchenrollment-gui' and can then be started with the scripts 'bin/batchenrollmentgui.sh' or 'bin/batchenrollmentgui.cmd'.

Using

When the application starts the connection dialog asks for connection information and login credentials. You need to supply some sort of truststore and keystore in the same way as when using the web services interface. When using PKCS11 the keystore file path should be the path to the PKCS#11 shared library.

Enroll end entities:

  1. Drag and drop certificate signing requests to the table in the main window or use the button Add... to browse for the files.
  2. For each request map it to an end entity and choose an output filename for the resulting certificate.
  3. Click the button Enroll.

Signed requests

The application also supports signed certificate signing requests. That is requests that are wrapped in a PKCS#7/CMS structure also containing a signature and a signing certificate that can be verified by the application before issuing the certificate. In order for the verification to work the Batch Enrollment GUI needs to have a PEM file with trusted certificates configured under the menu Edit -> Settings....

Misc information

Backup and restore of EJBCA

To backup an EJBCA installation you need to:

  • Backup the database
  • Backup all $EJBCA_HOME/conf/**
  • Backup all $EJBCA_HOME/p12/**
To restore:
  • Restore database
  • Unzip new EJBCA
  • Restore conf and p12
  • Run "ant deploy" to configure JBoss and deploy EJBCA. If you are using another application server, consult the Installation doc for deployment.

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

SSL certificate expire

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

You can do this through the admin-GUI by:

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

You can also do everything using the CLI:

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