EJBCA - Open Source PKI Certificate Authority
Search ejbca.org on Google:
EJBCA 6.7.0 Enterprise (r25420)

EJBCA support, development and maintenance by

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 server certificate from a CSR

EJBCA Administration

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 addendentity
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 on-line. External CAs are always show as ok. If the CA or CA token is not on-line, you should check the CA activation page, to see if the CA can be activated.

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. If CRLs have expired you can generate new CRLs. See CRL generation for more information.

Managing Crypto Tokens

A Crypto(graphic) Token in EJBCA is where keys are stored. A Crypto Token can be either backed by a soft keystore (file in the database) or an HSM PKCS#11 slot.

In the EJBCA Admin GUI the menu item "Crypto Tokens" will show you all the Crypto Token related management. Activation of Crypto Tokens can also be done from the CA Activation page.

There is also a CLI for all the functionality available in the Admin GUI. Run

bin/ejbca.sh cryptotoken

for a list of available sub-commands.

New Crypto Tokens

  • Name: A user-friendly name for the Crypto Token.
  • Type: PKCS#11 HSM slot mapping or a Soft PKCS#12 keystore in the database.
  • Authentication Code: The PKCS#11 slot PIN or the password that will protect the soft keystore.
  • Repeat Authentication Code: Should be the same as the previous field.
  • Auto-activation: If the authentication code should be stored (obfuscated) in the database and used to always keep the Crypto Token active.
  • Allow export of private keys: EJBCA will not try to prevent Soft Crypto Token keystore export if this box is checked.
If you select (as type) to use a PKCS#11 Crypto Token additional fields are displayed (PKCS#11 may require additional configuration of your app server, see Installation pages):
  • PKCS#11 Library: PKCS#11 shared library configured as available in conf/web.properties.
  • PKCS#11 Reference Type: What kind of a slot reference that is described by the next parameter (Id, Index or Label).
  • PKCS#11 Reference: PKCS#11 slot number, index or label.
  • PCKS#11 Attribute File: If required, this is a PKCS#11 attribute file configured as available in conf/web.properties. This should only be required for non common HSMs.
The PKCS#11 properties above are described in more technical detail in the Adminguide's HSM section. A unique Crypto Token identifier will be generated when the token is created.

In EJBCA Enterprise Edition, it is also possible to create new Crypto Tokens by using the WS API call createCryptoToken in your application or with the Web Services CLI.

View or Edit a Crypto Token

The view is very similar to the creation of a token except for showing the id and activation status. It is not possible to change the Crypto Token id, type or the change the authentication code of soft Crypto Tokens.

Activation and deactivation

In the list of Crypto Token there are 3 possible actions available:

  • Activate: Enter a authentication code and clicking "Activate" will activate an inactive Crypto Token.
  • Deactivate: Clicking "Deactivate" will deactivate an active Crypto Token.
  • Reactivate: Clicking "Reactivate" will reactivate an active Crypto Token with auto-activation enabled.

Key management

While viewing an active Crypto Token it is possible to also view and interact with the Crypto Token's keys. The shown SubjectKeyID column is a SHA1 over the public key.

  • A new key pair can be created by giving it an alias, a key specification and clicking generate.
  • Key pairs can be removed by clicking "Remove" for the specific key pair or selecting multiple keys and clicking "Remove selected".
  • A key pair can be tested by clicking "Test" for the specific key pair.
  • A key pair's public key can be downloaded in PEM format by clicking "Download Public Key".
Please note that the shown key specifications might not be supported by underlying PKCS#11 modules and an error will be shown when trying to use such a key specification.

In EJBCA Enterprise Edition, it is also possible to generate new keys by using the WS API call generateCryptoTokenKeys in your application or with the Web Services CLI.

CryptoToken Authorization

For all authorized CA operations, authorization for underlying Crypto Token operations are implied. The minimum authorization required to create a CA is authorization to "view" and "use" (or "modify") a Crypto Token.

Since modification of PKCS#11 Crypto Tokens could change the slot mapping, we require the same authorization for creation and modification. The full list of authorization rules follow:

  • /cryptotoken/: Required for displaying the Crypto Token management in the Admin GUI.
  • /cryptotoken/view/cryptoTokenId: Required for viewing Crypto Token information and listing key pairs.
  • /cryptotoken/use/cryptoTokenId: Required for binding a Crypto Token to a CA.
  • /cryptotoken/modify/: Required for creating or modifying a Crypto Token.
  • /cryptotoken/delete/: Required for deletion of a Crypto Token.
  • /cryptotoken/activate/cryptoTokenId: Required for activation of a Crypto Token.
  • /cryptotoken/deactivate/cryptoTokenId: Required for de-activation of a Crypto Token.
  • /cryptotoken/keys/generate/cryptoTokenId: Required for key pair generation.
  • /cryptotoken/keys/remove/cryptoTokenId: Required for key pair removal.
  • /cryptotoken/keys/test/cryptoTokenId: Required for key pair testing.

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 365 --policy 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 'Certificate Authorities' in the menu, entering a new CA name in the text field and clicking 'Create'.

*** Using EJBCA's web service ***

In EJBCA Enterprise Edition, if EJBCA's web service is set up, it is also possible to create new CA by using the WS API call createCA in your application or with the Web Services CLI.

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.

*** Signing Algorithm ***

The signing algorithm to use for issuing certificates, signing CRLs etc.

*** Crypto Token ***

The Crypto Token where the CA's key mappings are expected to exist.

The list of available Crypto Tokens are those that the administrator is authorized to view and use. The Crypto Token must also be active and contain a key that can be used with the CA signing algorithm in order to be shown.

The purpose mappings are the key alias in the Crypto Token to use for what:

  • defaultKey: The key to use no specific alias is selected (Required).
  • certSignKey: The key to use for certificate issuance. Must comply with the Signing Algorithm and only valid choices are shown.
  • crlSignKey: The key to use for CRL signing. Even though it could theoretically be separate from the certSignKey according to the RFCs, client support is rare and the certSignKey will always be used.
  • keyEncryptKey: Key to use for key recovery when enabled. Decrypts escrowed keys and must be RSA.
  • hardTokenEncrypt: Deprecated functionality, do not use.
  • testKey: Key used by health-check to verify that the Crypto Token is usable. Usually a short key for speedy connection checks.

If no crypto token has been specified, a soft (PKCS#12) crypto token can be automatically generated, and will have the same name as the CA. This crypto token will be set to automatically activate, and will have the default password foo123. This crypto token will also have the NODEFAULTPWD set as false, which allows the crypto token to be manipulated without using a password. Changing the password (via the CLI) or turning off auto activation will also invalidate the using the default password.

*** Extended Services Key Specification ***

Each CA has a set of Extended Services than can be enabled and sign requests in various formats. For some of the services, the CA will delegate signing to soft keys stored in the database as part of the CA object. These keys will have signing certificates issued by the CA's signature keys and similar SubjectDN to the CA. This field allows selection of the key specifications to use for these soft keys. Currently the following Extended CA services use this key specification (Extended CA services may also use CA keys):

  • Cryptographic Message Syntax (CMS, superseded PKCS#7) for signing exported logs: A soft key pair in the database will be used.

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

To use this feature efficiently you should have a database index over (subjectKeyId,issuerDN) on the table CertificateData. See doc/sql-scripts for index scripts.

*** Enforce unique DN ***

'Enforce unique DN' guarantees that users with the same Subject DN can not be issued certificates 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.

The check only affects new users, i.e. if you have two users with the same DN before enabling the limitation, these old users can still share the same DN and get new certificates.

To use this feature efficiently you should have a database index over (subjectDN,issuerDN) on the table CertificateData. See doc/sql-scripts for index scripts.

*** 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
Turning on certificate request history will reduce performance and use more database space, and is disabled by default since EJBCA version 6.0. If request history is needed please consider using the audit log functionality instead.

*** 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 (or enrollment code) 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 certificate factory, where the functionality of the Admin GUI is not required, user data storage be disabled to improve performance. See the Throw Away CA section in the Admin Guide for more information about this mode.

*** Use Certificate Storage ***

Issued certificates are stored in the database to be able to provide them upon request or provide revocation information. Certificate storage can also be turned off in the Certificate Profiles. Setting either setting to false will lead to certificates not being stored.

The certificate data storage is enabled by default.

If EJBCA is used as a certificate factory, where the functionality of the Admin GUI is not required, certificate data storage be disabled to improve performance. See the Throw Away CA section in the Admin Guide for more information about this mode.

*** Certificate Policy Id ***

Setting the Certificate Policy Id when creating a CA affects the certificate policy extension in the CA certificate. You can define Certificate Policy Id in:

  • CA settings
  • Certificate Profile
  • Both
When a CA is created or renewed, the Certificate Policy Id fields of the CA settings and the Certificate Profile are merged when the CA certificate is created. This means that if you have a value defined in both places, both Certificate Policy Ids will be included in the CA certificate.

For consistency reasons it might be a good idea to only use the Certificate Policy Id in the Certificate Profiles, as it is the same for all type of certificates, and merge effects can be confusing.

*** Name Constraints ***

You may restrict the domain names and IP addresses under which a CA is allowed to issue certificates. Root CA operators might require that this certificate extension is used in sub CAs that are operated by customers. The intended work-flow is to specify the name constraints on the end-entity for a sub CA, which will cause the name constraints extension to be included in the sub CA certificate once it's generated. It's also possible to add name constraints directly on a CA.

Note: Name constraints are added on the Issuing CA in a certificate hierarchy, i.e. not in the end user/server certificate, and not in the Root CA certificate.

Note: Name constraints must first be enabled in the Certificate Profile and the End-Entity Profile (the latter is for end-entities only). At the time of writing (May 2014) they are not supported in Apple Safari or on iOS devices, so this extension can not yet be marked as critical if there are such clients. The default mode is non-critical for this reason.

EJBCA supports domain name, directory name, e-mail (RFC 822 name) and IP address (both IPv4 and IPv6) constraints. These syntaxes are accepted:

example.com
Matches example.com and subdomains.
@example.com
Matches all mailboxes at example.com.
mailbox@example.com
Matches a specific e-mail address.
C=SE,O=Company
Matches against the beginning of the Subject DN. The certificates must not use LDAP DN order, which is enabled by default!
Also note that the RDN encoding must match. If the Name Contraint is encoded as PrintableString, the certificate must also be issued with PrintableString in the subjectDN, otherwise Name Contraint matching will fail. If you get an name constraint error about "CMSCertificate" when creating a CA, then you have some problem with the Subject DN matching.
198.51.100.0/24
Matches an IPv4 subnet. The IP address checked is the one in the certificate, which in turn is checked if the host is accessed by IP address.
2001:db8::/32
Similarly, matches an IPv6 subnet.

Name constraints are only checked for the types of constraints that are specified. So, if e.g. no IP addresses are addresses then the IP address will not be constrained. Conversely, if e.g. a domain name is listed as permitted then no other domain names will be permitted. If neither any permitted or excluded names are entered, then the Name Constraints extension will be omitted from the certificate.

An example Name Constrained certificate, as displayed using OpenSSL could contain:

X509v3 Name Constraints: 
  Permitted:
    DNS:onlythis.com
    DirName: C = US, ST = MA, L = Boston, O = Example LLC
  Excluded:
    IP:0.0.0.0/0.0.0.0
    IP:0:0:0:0:0:0:0:0/0:0:0:0:0:0:0:0

To issue such a certificate you would make the following configuration:

  • In the Certificate Profile check "Name Constraints - Use"
  • In the End Entity Profile check "Name Constraints, Permitted - Use" and "Name Constraints, Excluded - Use"
  • Add the End Entity and put the following in the fields for "Name Constraints, Permitted" and "Name Constraints, Excluded"
  • Generate the certificate and verify the contents with 'openssl x509 -in cert.pem -text'
onlythis.com
C=US,ST=MA,L=Boston,O=Example LLC
0.0.0.0/0
::/0

If you have been issued a name constrained Sub CA certificate from another Root CA, you may want to import certificates issued by this CA into other EJBCA instances. You then import the Sub CA certificate as an 'External CA' in the new EJBCA instance. When you import end entity certificates you may run into two settings that you need to tune, 'useLdapDnOrder' and 'usePrintableStringSubjectDN'. These settings are not possible to edit normally for an 'External CA', but you can edit them using the CLI.

bin/ejbca.sh ca editca --caname "Name Constrained CA Name" --field useLdapDnOrder --value false
bin/ejbca.sh ca editca --caname "Name Constrained CA Name" --field usePrintableStringSubjectDN --value false
*** Issuing Distribution Point on CRLs ***

Enabling Issuing Distribution Point on CRLs will put the default CRL Dist. Point (the first of there are several) in an Issuing Distribution Point extension in generated CRLs. According to RFC5280 this CRL extension MUST be critical. If you however notice that your CRLs are rejected, you can still choose to have this extension non-critical.

*** Keep expired certificates on CRL ***

This setting regulates what happens with revoked expired certificates. The default is unchecked (false) and should be left unchecked in all but a rare few use cases.

For most CA operations the default behavior, as specified in RFC5280, should be used. In this setting expired and revoked certificates are removed from the CRL. This keeps the size of the CRL down as it will not grow more than your active revoked certificates. Since basic certificate validation starts by verifying certificate validity, this is sufficient for most normal usage of CRLs. This behavior is specified in RFC5280, section 3.3 and 5.2.4

Some specific standards mandates that certificates are kept on the CRL even after certificate expiration. By checking this checkbox, expired and revoked certificates are never removed from future CRLs, and thus the CRL can grow infinitely if you are not careful. For example CABForum specifies this in their 'Minimum Requirements for the Issuance and Management of Publicly-Trusted Code Signing Certificates', version 1.1, section 13.2.1.

When this option is selected the expiredCertsOnCRL CRL Extension as per ISO 9594-8 par. 8.5.2.12 is added to the CRL.

Note: This setting should be set at CA creation and then never changed. This is because if unchecked, revoked and expired certificates will be set in state 'archived' and not be put on a CRL again, even if the checkbox is re-checked again.

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

*** Default user certificate AIA extension ***

The values of the semi-colon separated list for the 'CA issuer' and 'OCSP Service Locator' (only one URL possible) are used for the certificates Authority Information Access extension as specified in RFC5280 (section 4.2.2.1).
Certificate profiles used to issue end entity certificates with that CA must have the "Authority Information Access", as well as the "Use CA defined CA issuer" and/or the "Use CA defined OCSP locator" options enabled.

See also information about the CA Issuer URI field and the OCSP Service Locator field.

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

  • With this setting enabled 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 last certificate has been issued the user status is set to 'Generated' and the password is 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.
  • Note that the password will only be blanked for token types other than User Generated

*** 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 (unless cmp.ra.authenticationsecret is configured).

*** CA Name Change ***

Changing CA names is implemented as per ICAO 9303 7th edition part 12. Some information can also be found in the document supplements to ICAO 9303 6th edition. At this moment this feature is NOT part of X509 standard (RFC5280).

In order to apply CA Name Change during renewal, user needs to do the following on "Edit CA" page:

  • Activiate checkbox "Use CA Name Change" and specify new Subject DN in "New Subject DN" text field (If options are hidden in the GUI, administrator needs to activate "Enable CA Name Change" on "System Configuration" page)
  • Enable link certificates
  • Renew CA by clicking on "Renew CA" button

The CA Name Change renewal process results in the following in addition to standard X509 CA renewal:

  • Renewed CA will be presented as new CA in EJBCA GUI
  • Renewed CA certificate will have updated Subject DN
  • CRLs issued by renewed CA will still contain certificates revoked before renaming
  • CRL numbering will continue after the last CRL issued before renaming
  • If created, link certificates will have the CA Name Change extension specified with ICAO 9303 document

Note
CRLs checking procedure for CRLs issued by CA that has gone through Name Change process will have to be modified from standard X509 CRL checking procedure. More details about it can be found in ICAO 9303 7th edition part 12 in appendix chapter D1.2.3 CRL Processing.

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 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 'Certificate Authorities' page in the Administration GUI.
    1. Create a new CA in the same way as internal CAs, but when selecting signing CA, select 'External CA' instead. The fields 'Certificate Profile', 'Validity', 'Subject Alternative Name' and 'Policy Id' will become gray and are no longer editable.
    2. Fill in the Description and CRL Specific data.
    3. Make sure that the certificate chain is available, this can be done in one of three ways:
      1. Select a file containing the CA certificate chain of the signing CA. This file should be in PEM encoding. If there is more than one top CA certificate then all their certificates should be appended into one single file. It should be in plain PEM format without blank lines before or after. An example is below.
      2. Append the chain to the signed certificate file in the same way when receiving the request (see below).
      3. Import the complete certificate chain beforehand as External CAs (Certificate Authorities->Import CA Certificate).
    4. Click on the 'Make Certificate Request' button in the bottom of the page.
  2. After successfully clicking 'Make Certificate Request' the generated PKCS10 certificate request will be displayed. You can copy and paste it to the signing CA or download the PEM file if that approach is preferred.
  3. The external CA should sign the certificate request and return a certificate. Meanwhile, the newly created CA will have the status 'Waiting for Certificate Response' and will not appear anywhere in the system except in the 'Edit CA' page.
  4. 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'.
  5. If the received certificate forms a valid certificate chain with the previously uploaded chain or contained a full chain, the status of the CA will be set to 'Active'.
  6. 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.
  7. The new externally signed CA is ready to use.

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 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 (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 will issue the SubCA as an end entity.
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.

*** Using the CLI ***

You can also create a CA signed by an external CA using the CLI. The process is basically the same as when using the GUI.

Create the CA generating a CSR (Crypto token password is set to foo123):

bin/ejbca.sh ca init CaSignedByExteral "CN=This CA is Signed by an external CA" soft foo123 secp256r1 ECDSA 365 null SHA256withECDSA --signedby External -externalcachain chain.pem

The file chain.pem contains the certificate chain of the external CA, just as described above. Running the above command a CSR named 'CaSignedByExteral_csr.der' will be saved to your disk, containing a PKCS#10 CSR in binary format. Send the CSR to the external CA and get the signed sub CA certificate returned back.

Import the sub CA certificate, activating your CA:

bin/ejbca.sh ca importcacert CaSignedByExteral subcacertificate.pem

The file 'subcacertificate.pem' contains the received sub CA certificate.

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.

In EJBCA 5.0.x and before it was possible to manage external CAs in a more visible manner. This feature is no longer available.

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 "Certificate Authorities" select the SubCA and use the button "Renew CA" in the bottom of the page. The CA's Crypto Token must be active to make a certificate signing request (and optionally for key generation).

When you generate new keys for the SubCA, the new keys will not be used until you upload a new CA certificate for this key pair. Until then, the CA will continue to work as if nothing has happened (and issue certificates with the current CA signing key pair).

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 that you intend to get cross certified by another CA by and click on 'Edit'.
  2. In the lower part of the screen, click on 'Make Certificate Request' and skip upload of the signing certificate chain.
  3. 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 usually should not) 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.

If you choose to upload the resulting certificate chain, this will convert your CA from an internal CA to an externally signed CA.

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 by checking "Create link certificate" before renewing the CA. The latest link certificate can then be downloaded from the edit CA view.

For CVC CAs a link certificate is always generated during the renewal.

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

CA Rollover

It is possible to renew a CA certificate, but not activate the new certificate and key immediately. This is useful for CA certificates that will become valid at some point in the future (in EJBCA, such certificates can be created by checking "Allow Validity Override" in the certificate profile). A such certificate is called a rollover certificate or a next CA certificate, and can be used in the SCEP protocol.

First, make a certificate request as usual. Then you may receive the CA certificate response without activating it. To do so, edit the CA and check the "Rollover certificate (activated later)" checkbox. Then select the new CA certificate file its corresponding key. Then click "Receive Certificate Response". A message will appear, which shows when the rollover certificate becomes valid, and may be activated.

At a later point, the new rollover certificate may be activated. To activate it, edit the CA and scroll down to "CA Life Cycle". There should be text telling when the current certificate expires and when the rollover certificate becomes valid. If not, the CA doesn't have any rollover certificate. Click the button "Perform CA Rollover", and the new rollover certificate will be activated.

There is also a service, Rollover Service, that can be configured to activate rollover certificates automatically once they become valid. There will be a a 10 minute delay in this case to allow for a small amount of clock skew.

Approval profiles

As of EJBCA 6.6.0, there are two types of approval profiles: Accumulative Approval Profile and Partitioned Approval Profile.

Approval Profile Fields

*** Accumulative approval profile ***
  • Number of Required Approvals: How many administrators need to approve the request
*** Partitioned Approval Profile ***

This profile can contain several steps that have to be approved in sequence. Each step, however, contains one or more partitions that can be approved simultaneously. It is also possible to set fields to store data when a partition is approved.

  • Name: The name of the partition
  • Roles which may approve this partition: What administrator roles that are allowed to approve or reject this partition
  • Roles which may view this partition: What administrator roles that are allowed to view this partition
  • Data fields: data that should be collected when approving this partition. Different types of data are supported and as many fields as needed can be added.
    • Check Box: to mark something as 'yes' or 'no'
    • Number (Short): a number of no more than 6 digits is expected to be entered
    • Number (Long): a longer number is expected to be entered
    • Radio Button: several options are set and only one of them has to be chosen when approving the request
    • Text Field: longer text can be entered
  • Add notification: configure a note that will be sent to the administrators who can approve or reject this partition. See Approval Notification about what parameters are possible to use.
  • Add user notification: configure a note that will be sent to the end user when the status of this partition is changed. The notification will be sent to the email specified in the end entity. See Approval Notification about what parameters are possible to use.
*** Common fields for both profile types ***
  • Request Expiration Period: How long the request is valid from the time it was created. When a request has expired, it is no longer possible to process and a new request has to be created.
  • Approval Expiration Period: used for Non-Executable Action Requests and specifies the period from the time the last administrator approved the request until it is no longer possible to execute the request's action. See Two Different Approval Requests for more details about Executable and Non-Executable Action Requests.

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 "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 "ManagementCA" (the CA you use to issue server certificates).
  • Under "Type", select "End Entity".
  • Press "Save"

Another way of creating a new Certificate Profile is to use an existing profile as template:

  • In the list of certificate profiles, click on "clone" the fixed profile SERVER.
  • Enter a name for your end entity certificate profile e.g. "SSLServerCertificateProfile", and press "Create from template".
  • Press "Save"

Import/Export Certificate Profiles

It is possible to import and export certificate profiles in the Admin GUI.

*** Export Certificate Profiles ***

Every non-fixed certificate profile is exported to the specified local directory as an xml file inside a zip file named "certprofiles.zip". The name of the xml file has the format certprofile_PROFILENAME-PROFILEID.xml.

*** Import Certificate Profiles ***

All profiles to be imported should be included in a zip file. The file containing a single profile should be an xml file and its name is in the format certprofile_PROFILENAME-PROFILEID.xml. Any file with a name that is not in this format will be ignored.

Certificate Profile Fields

*** Available key algorithms ***

List of allowed key algorithms that public key used in the certificate requests must comply with.

*** Available ECDSA curves ***

List of allowed named curves. Select "Any allowed by bit lengths" to additionally allow any curve matching the selected bit lengths restriction.

*** Available bit lengths ***

List of allowed key sizes that public key used in the certificate requests must comply with. Currently this validation only checks that the used key's size is within the interval of lowest and highest selected value. Select 0 bits for implicit EC curves.

*** Validity ***

The validity determines the end date of the issued certificates and can be configured as:

  1. fixed date with ISO8601 format 'yyyy-MM-dd HH:mm:ssZZ', i.e. '2011-06-03 18:15:00+00:00', or
  2. relative time in terms of years, months, days, hours, and seconds in the form '*y *mo *d *h *m *s', i.e. '2y-10d'
For a relative validity, the end date of the certificate is calculated by its start date plus the value configured. The start time usually is the time point of issuance (i.e. if no offset for the start time is configured).

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 format 'yyyy-MM-dd HH:mm:ssZZ', for example, the date 'June 3rd, 2011 at 6:15 PM' in UTC should be given as '2011-06-03 18:15:00+00:00'.

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.

Undefined validity:
There is a part in section "4.1.2.5. Validity" of RFC5280 that specifies a date to be used to indicate that a certificate has no well-defined expiration date.
"To indicate that a certificate has no well-defined expiration date, the notAfter SHOULD be assigned the GeneralizedTime value of 99991231235959Z."
You can set this in EJBCA as follows:

  • Update cesecore.properties setting the ca.toolateexpiredate. This is a global setting, so keep in mind all CAs etc would be able to use super-long expiration date!
  • Create a new CA certificate profile with validity set to 9999-12-31 23:59:59+00:00.
  • Create a new CA with validity set to 9999-12-31 23:59:59+00:00 using the CA profile created in previous step.
  • Create a new end entity certificate profile with validity set to 9999-12-31 23:59:59+00:00.
  • Create new end entity profile that uses certificate profile created in step 4.
  • Add new end entities and issue a certificates for them.

Short lived certificates:
In a Certificate Profile you can configure validity down to minutes. Also using validity override and requesting a specific validity time through the protocols and APIs (WS, CMP, SCEP) short times can be requested, down to minutes and seconds. When using shorter validity periods than what is configured in the Certificate Profile the value in the profile will function as an upper limit. Longer times than that is not possible to issue.

*** Validity offset ***

A validity offset (used for setting back or forth start date to handle clock skew) can be configured in the certificate profile as a relative time in the form of '*y *mo *d *h *m *s'. With this the certificates default offset (specified in cesecore.properties '-10m') will be overwritten.

If a fixed end date in the form '2016-10-09 14:41:39+01:00' is used as certificate validity, only the start date of the certificate will be offset.
If a relative time in form of '*y *mo *d *h *m *s' is used as certificate validity, start and end date of the certificate are offset.
Example: Use the value '-5m' to have a notBefore date that is 5 minutes before the current time, in order to be valid on relying parties if their clocks are a bit behind.

*** Expiration restrictions ***

Expiration restrictions can be configured in the certificate profile in order to not let the user certificates expire on certain weekdays, but before or after.

If a fixed end date in the form '2016-10-09 14:41:39+01:00' is used as certificate validity, the restriction is applied after saving the certificate profile and a user message with the new fixed end date is shown.
If a relative time in form of '*y *mo *d *h *m *s' is used as certificate validity, the restriction is applied during certificate issuance, if it does not conflict with other restrictions (i.e. time nesting with the SubCA certificate).

*** Allow extension override ***

If extension override is allowed, X509 certificate extensions featured in certificate requests are honored, otherwise they are ignored. Externally supplied extensions are added to certificates "as-is". In the case such an extension is already defined in the certificate profile (i.e. having the same OID), the definition in the profile will be overridden including the criticality flag.

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.

To control in detail which extensions can be overridden and which can not the optional text field 'Overridable extension OID list' and the accompanying check box 'Extension list is disallowed' can be used. The field contain a comma separated lists of OIDs, for example '2.5.29.17, 2.5.29.32'. This is used in order to give RAs some control of the contents, but still enforcing policy for critical parts so the RA can not (accidentally) issue invalid certificates. For example you may wish that the RA can control the SubjectAlternativeName field, but not the KeyUsage of CertificatePolicies fields.

  • If 'Overridable extension OID list' is used and 'Extension list is disallowed' is unchecked any OID on this list can be overridden, but no other OIDs can.
  • If 'Overridable extension OID list' is used and 'Extension list is disallowed' is checked, no OID on this list is allowed to be overridden, but all other OIDs can be overridden.
*** Allow subject DN override by CSR ***

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

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 subject DN override by End Entity Information ***

If subject DN override is allowed, the X509 subject DN created in a certificate can come directly from the request meta information sent by the user. This is instead of the normal way where the user's registered DN is used.
Using this option you can create certificates with very specific ordering of subject DN fields.

  • The provided subject will still have black-listed characters and white spaces removed.
  • '+' will be escaped, since we don't support multivalued RDNs yet.
  • RDNs with empty attribute values will be removed.
  • Names have to comply with the CeSecore naming style (e.g. SURNAME=... instead of SN=..).

This option should only be used when you know that the request comes from a very trusted source (RA) over EJBCA's web service "certificateRequest" call. In this case the SubjectDN of the UserDataVOWS object will be used without modification.

In the case that "Allow subject DN override by CSR" is also specified, the CSR's subject DN will be used when present.

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

With External RA (ExtRA) the CertificateRequestRequest takes a certificate serial number as a parameter.

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
*** Allow back dated revocation ***

Revocation information of a revoked certificate contains the date and time from which the certificate is not valid (the revocation time). Normally the revocation time is set to the time of the revocation. But with this feature enable it is possible to set an earlier time when revoking a certificate from the profile. This is called a back dated revocation.

Currently you can only back date revocations with the use of Web Service, either by using the WS API call revokeCertBackdated in your application or with the Web Services CLI.

Note
Do not enable this feature if the profile will be used by a CA that is issuing delta CRLs.
*** Use Certificate Storage (Certificate Profiles) ***

Issued certificates are stored in the database to be able to provide them upon request or provide revocation information. Certificate storage can also be turned off in the CA settings. Setting either setting to false will lead to certificates not being stored, not even meta information.

The certificate storage is enabled by default.

If EJBCA is used as a certificate factory, where the functionality of the Admin GUI is not required, certificate storage can be disabled to improve performance. See the Throw Away CA section in the Admin Guide for more information about this mode.

Note
Disabling this setting will prevent features that depends on the actual certificate data being present from working. This setting is by default true and shouldn't be modified unless understood well.
*** Store Certificate Data ***

Disabling this setting allows meta information about certificates be stored, but will omit storing the actual certificate data (base64Cert) to the database. Meta information about the certificate includes revocation status, expiration information, fingerprint, etc.

Note: This setting has no effect if 'Use Certificate Storage' is disabled.

Note
Disabling this setting will prevent features that depends on the actual certificate data being present from working. This setting is by default true and shouldn't be modified unless understood well.
Note
This setting, when set false, also disables most OCSP extensions for affected certificates, since these are commonly dependent on the certificate being present in the VA.
*** 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.   
*** Issuer Alternative Name ***

Using the Issuer Alternative Name extension simply copies the Subject Alternative Name value from the issuing CA certificate and places it into the certificate produced.

An example of usage is to create a CA with Subject Alternative Name "rfc822Name=ca@org.org", and including that in the CA certificate. If you include Issuer Alternative Name in the certificate profile used to issue end entity (or sub CA) certificates, the end entity certificates will get Issuer Alternative Name "rfc822Name=ca@org.org". The end entity certificates can have a totally different Subject Alternative Name, as this is registered for the specific end entity.

*** 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 RFC5280 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=CRLIssuerForManagementCA,O=foo,C=SE". You have to build the actual CRL Issuer software yourself. If set, and the certificate profiles includes it, the CRL Issuer is included in the CRL Distribution point in issued certificates.

*** 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) [RFC6960] (former RFC2560). The URI field is the location of the OCSP responder, using the conventions defined in RFC6960, 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.

*** CA Issuer URI ***

This value is used for the Authority Information Access CRL extensions field 'CA Issuer' as specified in RFC5280 (section 5.2.7).
The URIs specified in this semi-colon separated list must point to files containing either a single certificate (.cer or .der) or a collection of certificates (.p7c).

*** Use LDAP DN order ***

In a certificate the order of the DN components (CN,O,C etc) can be put in different order, in the binary encoded certificate.

  • last-to-first, forward (historically called LDAP DN Order in EJBCA): CN=Common Name, O=Organization, C=Country
  • first-to-last, reverse order: C=Country, O=Organization, CN=Common name

When using string representation of DNs, the actual order is commonly not displayed, but the tool used will display in the order it sees fit which might be the reverse of the real, binary, order. In order to see the real, binary, order an asn1 parsing tool, like OpenSSL, can be used. In practice DN order can be important as comparisons is often done using string comparisons, where the string value may be depending on the order or not.

The most common order is first-to-last (i.e. C,O,CN), but for historical reasons EJBCA uses last-to-first (CN,O,C). Some applications do require first-to-last order however and therefore EJBCA gives you the choice (by unchecking 'LDAP DN order'). There are two places in EJBCA where this can be configured:

  • In the Certificate profile (Certificate Profiles)
  • In the CA configuration (Certificate Authorities)

The relationship between the settings is that they are both evaluated in a logical AND expression. This means that if both are true the DN will have last-to-first (LDAP) DN order, but if any one of them is false the DN will have X.500 order.

For some references see RFC2253 and RFC4514

*** 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 simply. In the 'Extended Key Usages' tab in the 'System Configuration' page in the Admin web, add your custom extended key usage's OIDs and readable name. After adding the new key usage, it can be chosen in the 'Edit Certificate Profile' page. See also the Admin Guide.

*** Document Type List ***

The DocumentTypeList extension is used to indicate the document types (as contained in the MRZ) that the corresponding document signer is allowed to produce. The list should be separated with a comma ','. For example: "P", or "P,ID"

See ICAO MRTD Technical Report LDS and PKI Maintenance for reference.

*** Private Key Usage Period ***

The Private Key Usage Period certificate extension is specified in RFC 3280.

EJBCA calculates the extension's notBefore and notAfter components based on the issuing time of the certificate (cert.notBefore) and the values filled into the "Start offset" (startOffset) and "Period length" (periodLength) fields as follows:

notBefore = cert.notBefore + startOffset
notAfter = notBefore + periodLength
*** Certificate Transparency (Enterprise only) ***

This is a module in EJBCA Enterprise Edition that implements Certificate Transparency (CT) as specified in RFC 6962. The purpose of CT is to create public audit logs of all certificates issued by the public SSL/TLS CAs. The presence of audit records is planned to be required for EV certificates in Google Chrome from February 2015 (and other web browsers and non-EV certificates later on as well). Note that CT is only relevant for CAs issuing public SSL/TLS certificates; other types of CAs should not use CT. More information can be found on the CT website.

The following options are visibile if the CT module is available (i.e. in the enterprise edition of EJBCA):

  • Use in new certificates: During certificate issuing, whether EJBCA should submit a pre-certificate to CT logs and include the resulting SCTs in the certificate.
  • Use in OCSP: Whether EJBCA should submit certificates and fetch SCTs from CT log during OCSP requests, and include the SCTs in an OCSP response extension.
  • Use CT publishers: Whether certificates should be published by the CTCustomPublisher. A publisher of the type CTCustomPublisher must be created and enabled in the certificate profile.

Depending on which of the options above are enabled, one or more of the following options may appear:

  • Enabled CT Logs: Which logs to submit to and obtain Signed Certificate Timestamp (SCTs) from. New logs can be added in the System Configuration, see the admin guide.
  • Minimum number of SCTs: If fewer servers respond with an SCT than this number, the underlying operation will fail (certificate issuing or generation of an OCSP response extension).
  • Maximum number of SCTs: After having received this number of SCTs, EJBCA will stop contacting log servers.
  • Submit existing certificates: If existing certificates (defined as not already having an SCT) should be submitted to CT logs during OCSP responses or publishing.
  • Number of retries: If a log server times out it will be tried again after all other logs have been tried. This is the maximum number of tries per server.

If part of the DNS in the SubjectAlternativeName extension should be a secret, that part can be redacted and replaced by the String "(PRIVATE)" in the precertificate that will be published to the Certificate Transparency Log. When adding the end entity to EJBCA, the part of the DNSName that should be redacted in the SubjectAlternativeName in the precertificate should be surrounded by parentheses. For example, when entering DNSName "(top.secret).domain.se", the precertificate in the Certificate Transparency Log will have the DNSName "(PRIVATE).domain.se" in its SubjectAlternativeName, but the certificate itself will have the DNSName "top.secret.domain.se" in its SubjectAlternativeName. EJBCA implements this feature according to RFC 6962.

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

*** Subset of Subject DN ***

By Using a subset of Subject DN in the certificate you can register users with more information than is present in the issued certificate. Example:

  • Use "Subset of Subject DN" in a certificate profile, with selected values CN,O and C.
  • Register an end entity with "CN=Tomas Gustavsson,O=PrimeKey,OU=Ignored,C=SE", and the configured certificate profile.
  • Issue a certificate using the certificate profile.
  • Issue a certificate. The issued certificate will contain subject DN "CN=Tomas Gustavsson,O=PrimeKey,C=SE".
Note
Do not use a "Subset of Subject DN" when issuing CA certificates. That can have undesired consequences, such as colliding CAIds and inability to find CA certificates.
*** Single Active Certificate Constraint ***

This value add the constraint that only a single active certificate may exist for an end entity at any point of time. Issuing a new certificate for an end entity using this constraint automatically leads to the revocation of any unrevoked and unexpired previous certificates. Revocation reason will be set as "Superseded".

Note
This configuration value is only available for End Entity Certificate Profiles.

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.

Enable End Entity Profile Limitations

In System Configuration, it is possible to enable and disable End Entity Profile limitations.

  • If this option is disabled, it does not matter what End Entity Profiles an administrator has access to. Instead, the administrator's ability to perform actions is limited by which CAs he or she is authorized to access.
  • If this option is enabled, in addition to the limits set by which CAs the administrator is authorization to access, there are limits set by which End Entity Profiles the adminstrator is authorized to access.

Please note that when this option is disabled, the list of End Entity Profiles under System Functions -> Administrator Roles -> Access Rules might be empty.

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 in the section "Create a 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 "ManagementCA" (the CA you use to issue server certificates).
  • Under "Available CAs", choose "ManagementCA" (same as above).
  • Under "Default Token", choose "User Generated".
  • Under "Available Tokens", choose "User Generated", "P12", "JKS" and "PEM" (ctrl-click to select multiple).
  • Press "Save".

Import/Export End Entity Profiles

It is possible to import and export end entity profiles in the Admin GUI.

*** Export End Entity Profiles ***

Every non-fixed end entity profile is exported to the specified local directory as an xml file inside a zip file named "entityprofiles.zip". The name of the xml file has the format entityprofile_PROFILENAME-PROFILEID.xml.

*** Import End Entity Profiles ***

All profiles to be imported should be included in a zip file. The file containing a single profile should be an xml file and its name is in the format entityprofile_PROFILENAME-PROFILEID.xml. Any file with a name that is not in this format will be ignored.

End Entity Profile fields

*** Username Field ***

The Username value represents an unique identifier for an end entity (user, server, device, etc). During the operation of adding an end entity username can be manually set or automatically generated. Checking the Auto-generated checkbox in the end entity profile will generate unique values when end entities are added.

*** Password Fields ***

Passwords are used when a user (end entity) is requesting a certificate and/or when generating a keystore. Usually this is required and no default value is configured. When the password is only used during the request procedure this is called an "Enrollment Code" in the public web to avoid making users confused or worried, since it is only valid once and is not used to protect the keys. There is no difference between an "Enrollment Code" and a "Password" other than the name.

You can use auto-generation of passwords with email notification to send the user a generated password together with information on how to fetch the certificate.

You can also specify the minimum bit-strength a password is allowed to have in order to make policy compliance easier. The strength of a password is calculated as floor(log2(number of allowed password characters)*(the number characters in the password)). For non-generated passwords the number of allowed password characters is estimated to 72. Example usage:

Password: "foobar123" (9 characters)
Allowed characters: a-z, A-Z, 0-9, 22 additional printable characters (72 in total)
Password strength / char: log2(72) = 6.17
Password strength: floor(6.17 * 9) = floor(55.53) = 55 bits
Setting this value to 55 will require the RA admin to set a 9 character password or longer.

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

In the Validation field you may restrict the allowed input, using a regular expression (regex). EJBCA uses Java Pattern syntax, which is similar to the Perl regex syntax. Matching is case sensitive by default, but this can be changed by adding (?i) in front of the regex. Here are some examples:

  • [0-9]+ allows digits only
  • [0-9A-Za-z]+ allows digits and English letters only, no spaces
  • [0-9A-Za-z ]+ allows digits and English letters and spaces
  • .+@.+ allows strings containing "@", for example e-mail addresses
  • [a-zA-Z0-9+._-]+@[a-zA-Z0-9.-]+ allows e-mail addresses with English characters only
  • [a-zA-Z0-9+._-]+@yourdomain\.com allows only e-mails from a specific domain
  • [a-zA-Z0-9._-]+\.yourdomain\.com allows only subdomains of yourdomain.com (but not yourdomain.com itself)
  • ([a-zA-Z0-9._-]+\.)?yourdomain\.com allows yourdomain.com with or without a subdomain

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.EndEntityProfileValidationException: Subject DN field 'ORGANIZATIONALUNIT' 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".

There is one particular subject DN field that deserves extra informations, postalAddress.
PostalAddress is not encoded simply as a string as one might think, but is an ASN.1 sequence. If you only enter the value as a string it will be encoded as a simple UTF8String, which is invalid. You need to enter is as a hex encoded ASN.1 DirectoryString. This is done by hex encoding the ASN.1 object and prepending it with #, i.e. #30...

*** 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>, permanentIdentifier=<Permanent Identifier values>

The text fields and check boxes for Subject Alternative Names generally work in a similar way as the Subject DN fields.

RFC 822 Name (e-mail address)

Configuration of email fields can be a bit tricky, since there are two places in the End Entity profile where email adresses can be configured:

  1. Email field - registers a user email in the EJBCA database (used for email notifications etc).
  2. Subject alternative name field - add an email address to the SubjectAlternativeName field in an issued certificate.

These two fields can be the same, but does not have to be, which is why configuration can be a bit tricky if you configure them individually.

For the Subject alternative name field there are different options:

  • Use entity e-mail field checked: this results in a single entry for 'End Entity E-mail' when adding a new end entity.
    • Required: if checked the 'End Entity E-mail' field must be filled and can not be omitted.
  • Use entity e-mail field unchecked: this results in a separate input field for 'RFC 822 Name'.
    • Required: if checked the 'RFC 822 Name' field must be filled and can not be omitted.
    • Modifiable: if checked the RA administrator can fill in an email address.
      If a domain (foo.com) is set in the profile the RA administrator can fill in the first part of the email, i.e. before @ (since the domain is pre-filled), but also the domain part can be modified.
      If Modifiable is unchecked a full, fixed, email address must be provided in the profile, and all end entities will be registered with this email address (the profile can be configured with only domain part, but filling an email adress by the RA administrator later will not work).
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.

Permanent Identifier (RFC 4043)

The Permanent Identifier is of the form "identifierValue/assigner" where identifierValue is an optional string and assigner is an optional OID, and should be entered as such in the field. If the identifierValue string contains a '/' (slash) character it should be escaped with an back slash ("\/").
Examples:

abc0123/1.2.3.4
abc0123/
/1.2.3.4
/
*** 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.

This function requires the 'Allow validity override' function in the Certificate Profile.

*** 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. Note that what is called a "password" in the admin web is often called an "enrollment code" in the public web. 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.

*** Custom certificate extension data ***

By checking 'Use' for custom certificate extension data in the end entity profile, a text area is provided when adding or editting an end entity for supplying custom certificate extension data.

Extension data are entered in the text area in the same format as for Java properties files; typically, key=value with one entry on each line. What extension data is accepted and/or required depends on what custom extensions that have been chosen in the certificate profile as 'Used Custom Certificate Extensions' and how they are configured.

For example, custom extensions of type BasicCertificateExtension configured with the property dynamic=true accept custom extension data in the form 'OID.value=value' where OID is the OID of the configured extension and value is the value to put in the extension in the configured encoding.

1.2.3.4.value = 65486c6c206f6f776c720064
1.5.6.value = Hello world

See Custom Certificate Extensions in the admin guide for more information about available extensions, how to configure them and what values they require.

An example configuration of a certificate extension taking dynamic value in RAW hax encoded format is:

OID: 1.2.3.4
Display Name: SingleExtension
Class Path: org.cesecore.certificates.certificate.certextensions.BasicCertificateExtension
Critical: false
Properties: 
  dynamic=true
  encoding=RAW
*** Number of allowed requests ***

By checking 'Use' for number of allowed requests you enable the possibility to request several certificates in a row, without the user status being set to generated. Normally after a username/password pair has been used to generate a certificate, the users status is set from 'new' to 'generated'. This makes the password invalid, thus implementing a one-time password scheme. By selecting a number higher than one for 'number of allowed requests' the user can request several certificates before the status is set to 'generated'. This makes it possible to enroll for several certificates directly, for example one authentication and one signature certificate.

The 'number of allowed requests' in the End Entity Profile will set the default, and maximum value available when adding or editing a new end entity. When editing an existing end entity and setting the status to new, from a non-new status, the 'number of allowed requests' will automatically be altered to the default value for the profile. If the end entity profile used no longer uses the 'number of allowed requests' the request counter for the end entity will be removed when the end entity is edited.

Plug in field restrictions

Administrators can develop further custom user field restictions using the Fieldvalidator as described in Customizing EJBCA.

End Entities

Creating Users

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

Create server certificates

A good way to create server certificates is to generate a PKCS12, JKS or PEM file for the server, depending on what server it is. This means that the private key is generated by the CA, you do not have to generate a CSR on your server for this. 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 "Create Certificate from CSR".

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.

Issue a new PKCS#12 keystore for an SSL server

This section will show you how to issue a PKCS#12 keystore suitable for SSL/TLS servers, such as web servers. You should previously have created the certificate profile and end entity profile for SSL servers in the sections above.

  • 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 "ManagementCA".
  • Under "Token", choose "P12".
  • Press "Add".
  • 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.

Issue a new server certificate from a CSR

This section will show you how to issue a certificate suitable for SSL/TLS servers from a CSR generated by the server. You should previously have created the certificate profile and end entity profile for SSL servers in the sections above.

  • Goto "RA Functions" -> "Add End Entity".
  • Choose the end entity profile "SSLServerEndEntityProfile".
  • At "Username" enter "testsrv.domain.com".
  • At Password enter a password. It will be used only during enrollment, as a one-time code.
  • 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 "ManagementCA".
  • Under "Token", choose "User Generated".
  • Press "Add".
  • Goto "Public Web" and then "Create Certificate from CSR".
  • Enter the username, testsrv.domain.com, and password for the user you created. Note that the password field is called "enrollment code" here. Paste the CSR from the server and press "OK".
  • A new certificate will be generated so you can download it to your desktop.

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 enrollment code, 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.

*** Suite B/ECC Certificates in Browsers ***

IE and Firefox do not yet (march 2014) support browser-based ECC certificate enrollment. They always default to RSA regardless of the CA ECC properties (is there some javascript to override?). The way to install ECC certificates in a browser is as follows:

  1. Edit batchtool.proprties file in folder conf: keys.alg=ECDSA, keys.spec=P-384 (or whatever named spec you need).
  2. Set all NEW entity passwords first: bin/ejbca.sh ra setclearpwrd entity-user entity-pw.
  3. Run bin/ejbca.sh batch - processes all NEW entities and places p12 files in folder p12 (or batch generate for a single user by appending username to batch command).
  4. Copy the *.p12 files from the p12 directory on the ejbca server.
  5. Install p12 keystore in browser.

Certificate Renewal

Certificate renewal is a often missunderstood term. Certificate renewal simply means issuance of a new certificate containing the same public key as an already issued certificate. It does not mean issuing a new certificate with the same certificate serial number, and it does not mean that the CA in some magical way has access to the end entitys private key.

To renew a certificate using the admin GUI, simply:

  1. Go to 'Search/Edit End Entities' and find the end entity in question.
  2. Set status to NEW.
  3. Have the end entity create a new certificate request (CSR), using the same public key as the first certificate.
  4. Send the new certificate request to the CA (the same way you did when getting the first certificate).
  5. Get the certificate back.

Since the CA has all public keys of end entities, as they are in the certificates that the CA stores, this process can be automated. How to automate that is more advanced and can be done in many ways, suitable for different work-flows. How to do that is not described here.

Request Browser Certificate Renewal

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

Renewal will result in the status of the end entity being set to NEW and the password set to an auto-generated password. The end entity must have notifications set or the password will be unretrievable.

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.

Renaming Users

The username is used to for example bind issued certificates or key recovery data to a specific end entity. In the case where the username has to be changed, this can be modified in the Edit End Entity view of the Admin GUI or using the 'bin/ejbca.sh ra renameendentity' CLI.

Renaming an end entity this way will automatically update CLI administrators with this name and other internal database objects where this is used. This also means that unless you have added database indeces to CertificateData, CertReqHistoryData, HardTokenData and KeyRecoveryData or if you have a large number of pending publisher queue objects issued under this end entity, this operation will be heavy on the database and take a long time to complete.

Administrators

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

  1. During the TLS 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 roles. 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 truststore (ant deploy-keystore) and restart the application server to make sure the new truststore is in use
  3. Import the CA-certificate under "Admin GUI - Certificate Authorities - Import CA Certificate.." or use the CLI
  4. Add the Administrator to the desired role under "Admin GUI - Administrator Roles"
  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 deploying EJBCA as usual with 'ant deploy', but instead of running 'ant install' you run:

bin/ejbca.sh ca importcacert ManagementCA ManagementCA.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, or if you have a p12/tomcat.jks and p12/truststore.jks this can be done for you on JBoss by 'ant deploy-keystore' and 'ant web-configure'.

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 either the Admin 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 setendentitystatus 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 role with limited privileges. A role is assigned certain access rules, and users are assigned a role. All users assigned to a role will have the access privileges defined by the access rules in this role.

Roles created during install

During installation EJBCA created a super administrator role, by default called the Super Administrator Role. By default this role:

  • has overall access to EJBCA
  • can edit system configuration
  • can manage CAs
  • can manage publishers (LDAP, AD, custom)
  • can create CA administrators

Pre-defined Role Templates

EJBCA also comes with three default role templates designed to cover most use cases, or to be easily extendable. If none of these are suitable a role can be created with the Custom template and be manually configured in Advanced Mode.

  • The CA Administrator:
    • manages certificate profiles
    • manages end entity profiles
    • manages log configuration
    • manages publishers
    • can create RA administrators
    • can renew a CA with new certificate and new keys
    • can have full read access to the audit log
  • 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
    • can have full read access to the audit log
  • Supervisor:
    • can view created end entities
    • has full read access to the audit log
  • Auditor:
    • has full read access to the Audit Log
    • has full read access to authorized CAs
    • has full read access to authorized Certificate Profiles
    • has full read access to Crypto Tokens and keys
    • has full read access to authorized Publishers
    • has full read access to authorized End Entities
    • has full read access to authorized End Entity Profiles
    • has limited read access to Administrator Roles
    • has full read access to Internal Key Bindings
    • has full read access to Peer Systems
    • has full read access to Services
    • has full read access to SCEP aliases and authorized CMP aliases
    • has full read access to all system configuration

Advanced access rules

When editing access rules, you can click on 'Advanced mode' to get access to advanced access rule configuration. In this mode you will see all available access rules, in detail, and can accept or reject specific rules for the role you are editing. The rules are numberous, and new rules may be included in new versions of EJBCA. They have somewhat human readable names and can often be figured out. See 'About Roles and Rules' below for a detailed description how the principe of access rules work. Note that rules not available to the current admin will be disabled, and rules pertaining to CA's and Crypto Tokens that the admin doesn't have access to will be hidden.

Using advanced access rules you can define you own roles in detail and construct a role set suitable for most auditing schemes.

Creating a new administrator

This example will walk you through creating a new administrator certificate, adding this administrator to a role and testing the access.

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

  • Under "CA Functions" -> "Certificate Profiles"
  • Click on "Clone" for the profile named "ENDUSER"
  • Enter "AdministratorEndEntityCertificateProfile" as the new name and click on "Create from Template".
  • Press "Edit" for the new 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 "ManagementCA" (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 "ManagementCA"
  • Under "Available CAs", choose "ManagementCA"
  • Press "Save"
Issue the following new end entity based on the new end entity profile.
CN: SoftCard RA Admin1

*** Creating a new RA Role ***

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

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

*** Adding new Administrators to the RA Role ***

  • 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 "Administrator Roles", press "Administrators" under "RAAdministratorRole".
  • Choose the CA that the administrator belongs to, "ManagementCA".
  • Paste the text from "Certificate Serial Number" in the "Match value".
  • Press "Add"

In EJBCA Enterprise Edition, it is also possible to add a new administrator to an existing role by using the WS API call addSubjectToRole in your application or with the Web Services CLI.

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

Note that the authorization privileges are cached and there will be a delay before a rule change is used.

About Roles and Rules

*** Roles and Rules ***

Permissions in EJBCA are never given out on an individual basis, but to a certain Role which contains a list of aspects and access rules. While Roles can be named at the user's discretion, Rules represent the resource they are named after. Access to this resource is also associated with an AccessRuleState, which may be one from the following table.

Access Rule States
Type Description
Unused This explicitly declares that a Role does not have a rule for this resource.
Accept Access is granted for this resource. If set to be recursive, Accept will also be default for any rules of type Unused deriving this rule.
Decline Access is denied for this resource. Will trump any recursive Accept rules previously encountered.

*** The Access Tree ***

Resources are created according to a hierarchical structure, much like a file tree. A typical resource could be /ca_functionality/create_certificate which consists of three subresources: the root /, its child ca_functionality and the end node create_certificate. If desired, a Rule could be applied to any one of these. Access to the end resource (create_certificate) can be granted by either giving it the value Accept or setting Accept for any of its parents nodes and setting them as recursive. Access can be denied by setting access to it or any of its parents as Decline or using Unused the whole way down. This is further illustrated by the following figure:

EJBCA Access Tree

Requesting access to the above resources will result in the following:

Resource Result Reason
/ Denied Status is unknown, hence denied.
/a Denied Explicitly denied.
/a/a Denied Even though /a/a is granted, /a explicitly denies access to its children.
/b Granted Explicitly granted.
/b/a Granted Granted thanks to the recursive accept in /b.
/b/a/a Denied Explicitly denied, which trumps the recursive grant in /b/a.
/b/a/a/a Denied Denied as a result of /b/a/a.
/c Granted Explicitly granted.
/c/a Denied Unknown in spite of the fact that /c was granted, hence defaults to denied.
/d Denied Unknown, hence denied.
/d/a Granted Explicitly granted.

View Log options

When viewing the log, you can chose what logs to see by chosing an option from a list.

Event

You can chose what kind of event to see. For example, Administrators logged in, CA related activities, certificate related activities, End Entity related activities, activities that caused error... etc.

CA

You can chose to see all the logs related to a specific CA.

Module

You can chose to see all the logs related to a specific module, tex. CA, RA, Public Web, Hard Token, Approval, Service... etc.

Username

You can chose to see all the logs related to a specific username.

Certificate

You can chose to see all the logs related to a specific certificate. The certificate is specified by its serialnumber written in hexadecimal format.

Administrator Certificate

You can chose to see all the logs created by a specific administrator. The administrator is specified by his certificate serialnumber written in hexadecimal format.

Comment

You can chose to see all the logs created with a specific comment.

Administrator details

You can chose to see all the logs created by a specific type of administrator, his or her IP address or the hexadecimal serialnumber of the administrator certificate used. There are six types of administrators:

  • An administrator who logs in with a certificate. Typically an administrator who logs into the Admin GUI to perfom tacks that need administrator privileges. An administrator who logs in with a certificate is loged with his certificate serialnumber and SubjectDN.
  • An administrator who logs into the public web using only username and password. An administrator who logs into the public web is loges with his IP address.
  • An RA user. The RA user is loged with his IP address.
  • An administrator performing administrative tasks through commandline.
  • An administrator performing administrative tasks through batch commandline.
  • An internal user performing tasks within Ejbca.

The log can be displayed on the screen or exported as a XML file.

Signing log files

If so desired the exported log file can be signed by a specific signing certificate of a certificate authority. This will generate a binary (DER) format CMS/PKCS#7 MIME Message (p7m) file. Specific CMS compatible tools are needed to validate the signature and to 'strip' it off as to allow importing into other tools such as a text editor.

Below is an example using 'OpenSSL'; 'ca.pem' is the PEM format CA certificate and logexport.p7m is the file downloaded from the logging interface.

$ openssl smime -verify -nodetach -CAfile ca.pem -inform DER -in logexport.p7m -out logexport.xml
Verification successful
   

Managing Internal Key Bindings

See the concepts page for a high level description of what Internal Key Bindings are.

All Internal Key Bindings share the following properties:

  • Type: OcspKeyBinding or AuthenticationKeyBinding.
  • Id: Unique identifying number.
  • Name: A unique and human readable name.
  • Crypto Token: The Crypto Token where we reference a key pair.
  • Key Pair Alias: A reference to the currently used key pair in the specified Crypto Token.
  • Signature Algorithm: The signature algorithm user during signing, for example the signing of an OCSP response.
  • Next Key Pair Alias: A reference to the next key pair to use in the specified Crypto Token when renewing.
  • Bound Certificate: A certificate issued for the current key pair's public key.

Actions

From the overview page the following actions are available:

  • Enable/Disable: Marks the Internal Key Binding as Active/Disabled. Only Active ones will be used and processed by health-check.
  • Delete: Removes the Internal Key Binding, but will not remove the referenced key pair or certificates.
  • New keys: Generates a new key pair in the referenced Crypto Token using the same key specification as the current key has and an alias derived from the current alias.
  • CSR: Creates a Certificate Signing Request using the next key pair (or current key pair when no next key pair exists).
  • Update: Searches the database for the latest issued matching certificate for the next key pair (or current key pair when no next key pair exists) by using SubjectKeyId.
  • Renew: When the CA that issued the current certificate is active and resides in the same instance, this will create a new certificate using the same End Entity as the last one was issued with. If a next key pair exists, that key pair will be used.

OcspKeyBinding

A CA can delegate the signing of OCSP responses to a separate key pair. This is configured as an Internal Key Binding.

  • The certificate must have Key Usage: Digital Signature.
  • The certificate must have Extended Key Usage: OCSPSigner.
  • The certificate normally has the "OCSP No Check" extension enabled.
  • The list of trusted certificates will be used to validate the OCSP request signature (if a signature is required).

Implementation specific properties:

  • Non existing is good: If true a certificate that does not exist in the database, but is issued by a CA the responder handles will be treated as not revoked. Default (when both this value and value of "Non existing is revoked" are false) is to treat it as "unknown". Since the OCSP responders database normally contains all issued certificate this gives sensible values (in line with RFC6960) to "ok", "revoked" and "unknown" certificates. Setting this value to true is useful if you want an External OCSP responder database to only contain revoked certificates, and not all certificates. In this case the responder will answer "ok" to requests for certificates that do not exist in the database. If both "Non existing is good" and "Non existing is revoked", the responder will answer "ok"
  • Non existing is revoked: If true a certificate that does not exist in the database, but is issued by a CA the responder handles will be treated as revoked; the revocation reason will be "Certificate Hold" and the revocation time is January 1st, 1970. Default (when this value and value of "Non existing is good" are false) is to treat it as "unknown". If both "Non existing is good" and "Non existing is revoked", the responder will answer "ok".
  • Max-Age HTTP header (seconds): A hint to caching proxies when using HTTP GET for how long to retain a response, and should be set to a value lesser than or equal to the response validity. A value of 0 means no caching.
  • Request must be signed with a trusted certificate: When true, request signatures will be checked against the list of trusted certificates or trust anchors.
  • Response validity (seconds): How long the OCSP response is valid and may be used. A value of 0 means the there is always a newer response available.
  • ResponderID: Defines the ResponderID type included in the response. The ResponderID is either a Name (SubjectDN of the signing certificate used for response) or Keyhash (SHA-1 digest of the public key of the signing certificate used for response).
  • Include signing certificate in response: When true, the signing certificate will be included in the response.
  • Include certificate chain in response: When true, the entire certificate chain, except for the root CA certificate, will be included in the response (note that this is only applicable if 'Include signing certificate in response' is true).

See the section OCSP installation for the full description on how to set up delegated OCSP signing.

AuthenticationKeyBinding

The identity in outgoing SSL connections is configured as an Internal Key Binding.

  • The certificate must have Key Usage: Digital Signature and Key Encipherment.
  • The certificate must have Extended Key Usage: Client Authentication.
  • The list of trusted certificates will be used to validate the remote server side SSL certificate.

Validation of the remote TLS certificate is subject to basic TLS certificate path validation and for example OCSP checks are currently not supported. You can configure the list of trusted remote server side TLS certificats in the following ways:

  • By default, any remote server side TLS certificate issued by a CA that exists in the local EJBCA instance will be trusted.
  • By specifying a CA, you can choose to trust only TLS certificates issued by this CA.
  • By specifying both a CA and a certificate serial number, only the specific TLS certificate will be trusted.
In the case where an external CA is used and you need to trust a specific TLS certificate, the certificate must be known to the local instance as well. You can for example use the bin/ejbca.sh ca importcert to ensure that this is known.

No implementation specific properties exist for this Internal Key Binding.

See the section Setting up Peer Connectors for Outgoing Connections or OCSP signer renewal for examples of how this is used.

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 './dist/clientToolBox' 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 Validation/Conformance Tool (EJBCA Enterprise only)

The ValidationTool is a standalone client-side application for certificates and OCSP response validation and conformance checks.

For details see the ValidationTool manual.

Build the tools with:

ant validationtool

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

To use any of the ValidationTool commands just call 'bin/validationtool.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.

A source distribution can also be created by running:

ant validationtool-src

The directory 'dist/validationtool-src' is then created. You may optionally zip it together and extract it any location. The ValidationTool can then be built by moving to its modules/validationtool directory and run:

ant jar

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.

Note: The GUI can guess which end entity the request belongs to if the file name contains the name of an existing end entity. For instance if the request files are named user1-00002.csr, user2-00002.csr and user3-00002.csr" and there exists end entities in EJBCA user1, user2 and user3 then they will already be selected.

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", "ant deploy-keystore", and "ant web-configure" 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 Expiration

The SSL certificate used for SSL in JBoss 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/web.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 setendentitystatus tomcat 10
  2. bin/ejbca.sh ra setclearpwd tomcat <password from httpsserver.password>
  3. bin/ejbca.sh batch tomcat
  4. cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
  5. Restart JBoss.
A small convenience ant target is present which can simplify the proceess and save some typing (it's running the above three ejbca.sh commands in succession):
  1. ant renew-keystore
  2. cp p12/tomcat.jks $APPSRV_HOME/server/default/conf/keystore.jks
  3. Restart JBoss.