EJBCA support, development and maintenance by

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

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

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

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

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

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

[email protected]

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.

*** CRL Period ***

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

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

*** Finish User ***

The Finish User configuration defines if the CA calls a process called "finishUser" after a certificate has been issued for an end entity.

• 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

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

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

*** 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 validity in days of certificates from the time the certificate is issued. The field 'notAfter' in the issued certificate will have the value 'now + validity days'. It can also, if noted in the field, be entered in terms of years, months and days. For instance '10y 9mo 8d' is translated to 10 years, 9 months and 8 days from now. Instead of the validity period an absolute end date could specify the end of the validity period. This date should be given in the 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.

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

Currently this works for extensions in CRMF (CMP) requests and extensions embedded as a pkcs_9_at_extensionRequest in PKCS#10 requests.

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

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

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

*** 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 "[email protected]", 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 "[email protected]". 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

*** CRL Issuer ***

According to RFC3280 a CRL issuer is:

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

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

*** Freshest CRL ***

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

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

*** OCSP Service Locator ***

This extension is used when revocation information for the certificate containing this extension is available using the Online Certificate Status Protocol (OCSP) [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 Extension as specified in RFC4325. The URI specified in this field must point to a certificate containing file containing either a single certificate (.cer) 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".

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

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

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

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

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

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

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

[email protected]

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

krbtgt/[email protected]

for a kdc.

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.

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

*** 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 AdminCA adminca.pem -initauthorization

This command imports the certificate of the external Administration CA and initializes the authorization system of EJBCA. You need to configure SSL and the truststore of the application server yourself, 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.

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

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

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

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

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

*** Adding a Peer Connector ***

Outgoing connections must be allowed to be able to add a new Peer Connector. From the Peer Systems overview, click the Add button. Configure the following fields and click Create.

• Name: Your name for the peer.
• URL: The target end point where the peer is listening. Normally you only need to change the hostname of the URL.
• Enabled: If a Peer Connector is enabled connections to the peer are allowed to be created when needed.

*** Edit, Clone or Delete a Peer Connector ***

From the Peer Systems overview, click the Edit button for an existing Peer Connector. In the view of the Peer Connector you can modify and save the existing name, URL or state. In the Edit view, you additionally have buttons for cloning (Clone) or deleting (Delete) the current object.

*** Authorization of incoming connections ***

If no Administrator Role exists for the connecting system's client certificate, you are presented with a Create Authorization button. Clicking this button will allow you to quickly setup a new Administrator Role with for the incoming client certificate and a relevant set of access rules or add the incoming client certificate to an existing Administrator Role.

If an Administrator Role already exists for the connecting system's client certificate, you are presented with a Modify Authorization button where you can change the relevant set of access rules for the Administrator Role.

Note that this is just a simplified view of EJBCA's normal authentication and authorization management and the created Administrator Role can be edited just like any other Administrator Role.

*** Publishing using Peer Connectors ***

Publishers are used to propagate certificate or CRL information to a peer system. The PeerPublisher implementation allows this information to be pushed to a configured Peer Connector.

The connecting system needs to be authorized to the /peerincoming /peerpublish/writecert /peerpublish/writecrl /ca/[CAName] access rules to be able to push both certificate and CRL data.

*** Certificate data synchronization ***

In a setup where an EJBCA CA instance (or a cluster) uses external EJBCA VA/OCSP responders, revocation information needs to be propagated from CA to VA. Information about newly issued certificates and revocation updates are normally sent using a (Peer)Publisher, but the first time a new VA is connected the current state of all previously issued certificates needs to be pushed to the VA.

In the overview of peer connectors, click Manage for the peer connector representing the VA and select the Certificate Data Synchronization tab. Configure the relevant subset of information to synchronize and click Start to initiate the synchronization as a background task. The progress can be followed either in this view or in the Peer Systems overview.

Note that the subset of revocation information to send affects how database queries are performed. Depending on your database it might be faster to only synchronize everything or only one subset of data at the time.

The connecting system needs to be authorized to the /peerincoming /peerpublish/readcert /peerpublish/writecert /ca/[CAName] access rules to be able to check synchronzation data and push missing or outdated certificate entries.

*** Renewal of remote Internal Key Bindings ***

In a setup where an EJBCA CA instance (or a cluster) uses external EJBCA VA/OCSP responders, a CA delegates signing of OCSP responses to an OCSP signing certificate (configured as a OcspKeyBinding) at the VA. The OCSP signing certificate should be short-lived and to make renewal easier, this is available as a remote management operation on the CA.

In the overview of peer connectors, click Manage for the peer connector representing the VA and select the Remote Key Bindings tab. Click Renew to generate a new certificate. Optionally you can also select to generate a new key pair for the next OCSP signing certificate.

Renewal of remote Internal Key Bindings can be automated using a Remote Internal Key Binding Updater service.

The connecting system needs to be authorized to the /peerincoming /internalkeybinding/view/[IKB] /internalkeybinding/modify/[IKBName] /cryptotoken/view/[CTName] access rules to be able to renew an Internal Key Binding certificate. Additionally /cryptotoken/keys/generate/[CTName] is required if key renewal should be allowed.