The following includes a reference to all Certificate Authority (CA) configuration fields and values.
For an overview of the main elements and conceptual information on CAs, see Certificate Authority Overview and for information on how to create, edit and manage CAs, see Certificate Authority Operations.
The CA Type can either of the following:
- X509: A normal CA for secure email, login, web authentication, VPN etc.
- CVC: A CA issuing CV certificates, which are special certificates for EU EAC ePassports. For more information on CVC CAs, see CVC CA.
- ECA: Enrollment Certificate Authority, issuing enrollment credentials for ITS PKI environments, see C-ITS ECA.
The signing algorithm to use for issuing certificates, signing CRLs etc.
The Crypto Token where the CA's key mappings are expected to exist.
Lists available Crypto Tokens 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 used for:
- 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 disabling auto activation will also invalidate 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 services 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.
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 country code.
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, leave it to be handled automatically.
For more information, see CVC Sequence.
Serial Number Octet Size
Sets the length in octets of certificate serial numbers generated in issued certificates. Possible values can range between 4 and 20 octets, and the default for all new CAs is 20 octets.
The default serial number generator is a Constant Octet Size Random Serial number Generator.
The purpose of this certificate serial number generator is to generate random serial numbers with a fixed octet size. If you specify the octet size to be 8 octets, the serial number will be 8 octets, if you specify 20 octets it will be 20 octets, etc.
To achieve this the following process is performed:
- The specified number of octets is retrieved from a CSPRNG (SecureRandom in various shapes and forms).
- The octets are converted into a positive BigInteger (serial numbers are ASN.1 INTEGERs) by taking the absolute value of the BigInteger created from the random bytes
- If this integer does not fulfill requirements and limitations specified by RFC5280 and X.690, the serial number is discarded
- This process is repeated with new octets from the CSPRNG until an integer fulfilling the tests has been retrieved.
- The resulting integer is returned as the serial number from the generator
RFC 5280 defines serialNumber be a positive INTEGER. Simply using an integer conforming to RFC5280 will lead to variable length encoding of the serial number in the certificate. If the (random) integer 3 is retrieved from the CSPRNG it will be encoded as '03' and the number 65535 as 'FFFF', etc. Also if the number is too large, ASN.1 integers being in two-complement representation, it will be encoded as 9 bytes.
To achieve fixed octet length serials we apply restrictions according to X.690. X.690 defines that INTEGER consist of one or more octets, and also defines as follows:
If the contents octets of an integer value encoding consist of more than one octet, then the bits of the first octet and bit 8 of the second octet:
a) shall not all be ones; and b) shall not all be zero.
This sets minimum and maximum boundaries for the integer.
- Minimum 4 octets value is 00800000 and maximum value is 7FFFFFFF."
- Minimum 8 octets value is 0080000000000000 and maximum value is 7FFFFFFFFFFFFFFF."
- Simply extend with '00' and 'FF' for other octet sizes.
Serial number random algorithms
For configuration of random serial number generator algorithms, see configuration in conf/cesecore.properties, field ca.rngalgorithm.
There are a number of choices, including:
- Java SecureRandom with a specified algorithm as defined by Java SecureRandom Number Generation Algorithms
- SHA1PRNG (default)
- DRBG (from Java 11)
- default (plain SecureRandom())
- defaultstrong (plain Java SecureRandom.getInstanceStrong(), not recommended)
- BCSP800Hybrid (from EJBCA 7.4.1, a Bouncy Castle FIPS/SP800 compliant DRBG chain)
For source code implementation details, see the class SernoGeneratorRandom.java.
Key Sequence Format
Within EAC, there are several options regarding the sequence format. The format can be chosen 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 cannot 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. For more information, see Create Database Indexes in Creating the Database and for index scripts, refer to doc/sql-scripts.
Enforce Key Renewal
Enforce Key Renewal guarantees that certificates with the same public key cannot be issued from this CA. This means that it is not allowed to have multiple certificates with the same key, even for the same end entity. The check is only performed when new certificates are issued.
To use this feature efficiently you should have a database index over (subjectKeyId) on the table CertificateData. For more information, see Create Database Indexes in Creating the Database and for index scripts, refer to doc/sql-scripts.
This feature will not allow for key recovery as it implies multiple certificates with the same public key in the database.
Enforce Unique DN
Enforce unique DN guarantees that users with the same Subject DN cannot 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 cannot 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. For more information, see Create Database Indexes in Creating the Database and for index scripts, refer to doc/sql-scripts.
Enforce Unique Subject DN Serial Number
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 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 selects 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.
The following Information is stored:
Certificate Request History is disabled by default as of EJBCA version 6.0. Enabling certificate request history reduces performance and uses more database space, If request history is needed, consider using the audit log functionality instead, see Audit Log Overview.
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 can be disabled to improve performance. For more information, see the Throw Away CA section in Maximizing Performance.
Use Certificate Storage
Issued certificates are stored in the database to allow providing them upon request or to provide revocation information. Certificate storage can also be disabled in the Certificate Profiles. Disabling either setting will result in 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. For more information, see Throw Away CA.
Accept Revocations for Non-Existing Entries
If Use Certificate Storage is disabled, issued certificates are not stored in EJBCA. Thus, by default you cannot revoke these types of certificates. To allow revoking certificates, enable this option. For more information, see the Throw Away CA section in Maximizing Performance.
Default Certificate Profile for Non-Existing Entries
Throw away certificates have no persisted information referring to any certificate profile. The Default Certificate Profile for Non-Existing Entries option determines which Certificate Profile to use by default while revoking throw away certificates issued by this CA. The option is only applicable to throw away CA's.
Use Append-Only Table
While accepting revocations for throw away certificates, selecting Use append-only table will persist all certificate data of the revoked throw-away certificate to a separate, append-only database table.
Pre-Produce OCSP Responses
ENTERPRISE This is an EJBCA Enterprise feature.
Allows generation and serving of pre-produced OCSP responses for this CA. See OCSP Response Pre-Production for detailed information.
Store Responses On-demand
Enabling Store Responses on-demand will persist a copy of OCSP responses generated while requesting the status of certificates issued by this CA. The persisted response will be used to serve future requests for the same certificate until the response validity expires or a newer response is generated. For more information, see OCSP Response Pre-Production.
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
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.
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 workflow 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. The end entity for the Sub CA is created on the Root CA (issuing the Sub CA certificate).
It is also possible to add name constraints directly on a Sub CA during creation. The Name Constraint settings are then configured in the Create CA screen and applied when a Sub CA, signed by a Root CA in the same instance of EJBCA, is created and the Sub CA certificate issued.
- Name constraints are added on the Issuing CA certificate in a certificate hierarchy, that is not in the end user/server certificate, nor in the Root CA certificate.
- Name constraints functionality is enabled in the Certificate Profile and the End Entity Profile (for end entities only). The default mode is non-critical since iOS devices and certain clients may lack name constraints support.
EJBCA supports the following constraints:
- Domain name
- Uniform Resource Identifier (URI)
- Directory name
- E-mail (RFC 822 name)
- IP address (both IPv4 and IPv6).
The following syntaxes are accepted:
Matches example.com and subdomains as a dnsName.
|@example.com||Matches all mailboxes at example.com.|
|firstname.lastname@example.org||Matches a specific e-mail address.|
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 Constraint is encoded as PrintableString, the certificate must also be issued with PrintableString in the subjectDN, otherwise Name Constraint matching will fail. If you get a 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||Similar to the previous entry but matches an IPv6 subnet.|
|Matches a URI with example.com as host. |
To differentiate URIs from dnsNames, a URI must be prefixed with uri:
|uri:.example.com||Matches a URI with example.com as host, allowing a subhost such as www.example.com or host1.example.com.|
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, configure the following:
- In the Certificate Profile, select Name Constraints - Use.
- In the End Entity Profile select Name Constraints, Permitted - Use and Name Constraints, Excluded - Use.
- Add the End Entity and specify 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
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, consider configuring the settings useLdapDnOrder and usePrintableStringSubjectDN. The settings must be edited using the CLI for an External CA:
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
Microsoft CA Compatibility Mode
This setting ensures that CRLs and OCSP responses are signed with the key expected by Microsoft Windows clients after CA rekeying.
The Microsoft CA Compatibility Mode setting is irreversible and a warning is displayed.
Also note that this field should not be manually changed using the ConfigDump Tool in existing installations. If changed, it will require clearing caches.
For more information about the Microsoft CA Compatibility Mode, see Microsoft Compatible CA Key Updates.
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. It is disabled by default and should only be enabled for a few and rare 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 mandate 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. 188.8.131.52 is added to the CRL.
This setting should be set at CA creation and then never be 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.
Use CRL partitions
Allows CRLs to be partitioned in several smaller CRLs, instead of one large CRL. For more information, see Partitioned CRLs.
The following CA configuration settings control when and if a new CRL is generated:
|CRL Expire Period||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.|
If set to an unreasonably high value leading to a year greater than 9999 (for example '9999y'), the nextUpdate field will be set to the undefined value 99991231235959Z, as specified in RFC 5280 (section 184.108.40.206).
If the CRL Validity is set past the CA's expiration date (unless using the value 9999), then the CRL's validity will be capped at the end of the CA's validity date. Note that if the CA is revoked prior to expiration, then the CRL's validity will be unaffected.
|CRL Issue Interval||A fixed interval when CRLs are 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, corresponding to a CRL Overlap Time of 23h (see below). The default value here is 0, which means that a new CRL will be issued when the old one is about to expire. Keeping the default value 0 has the same as effect as setting this value to the same value as CRL Expire Period.||No|
|CRL Overlap Time||The new CRL is generated this amount of time before the old CRL expires. The default value is 10 minutes, meaning that if the CRL Expire period is 24 hours, a new CRL will be issued after 23h50m.||No|
|Delta CRL Period||The validity period for generated delta CRLs if delta CRLs are issued. Delta CRLs are only issued if this period is larger than 0.||No|
|Generate CRL Upon Revocation|
If a certificate issued by this CA is revoked, the next CRL or delta CRL is generated immediately after revocation. If the single active certificate constraint option of the certificate profile used to enroll a certificate is selected, all active certificates of this end entity are revoked and exactly one new CRL for every CA with this option selected is generated, if at least one of the certificates issued by this CA had been revoked.
You only need to define either CRL Issue Interval or CRL Overlap Time (although it is perfectly possible to define both). The default settings ensure that there is no time period (even a few seconds) when there is no valid CRL issued, and they give clients a timeslot of 10 minutes to download a new CRL before the old one expires. If you want to increase this timeslot, you should either decrease the CRL Issue Interval, or increase the CRL Overlap Time.
Unless you create new CRLs manually, you must configure a CRL Updater Service to generate the CRLs for you. For more information, see Services.
CRL CA Issuer URI
This value is used for the Authority Information Access CRL extensions field 'CA Issuer' as specified in RFC 5280 (section 5.2.7). It should be a URL that points to either a single DER encoded certificate or a collection of certificates in a BER or DER encoded "certs-only" CMS message, e.g .
Multiple URIs are specified as a semi-colon separated list and each URI must point to a file containing either a single certificate (.cer) or a collection of certificates (.p7c). For more information, see the CA Issuer URI section in Certificate Profiles Fields.
Default CA Defined Validation Data
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 RFC 5280 (section 220.127.116.11). Certificate profiles used to issue end entity certificates with that CA must have the Authority Information Access, Use CA defined CA issuer, and/or Use CA defined OCSP locator options enabled.
For more information, see Certificate Profile Fields.and in
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 cannot 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).
A request processor is a plugin which in some way modifies or acts upon an incoming CSR before issuing certificates when using the following protocols:
For more information, see Creating Custom Request Processors.
CA Name Change
Changing CA names is implemented as per ICAO 9303 7th edition part 12. Information can also be found in the document supplements to ICAO 9303 6th edition. Currently, this feature is not part of X509 standard (RFC5280).
To apply CA Name Change during renewal, go to the Edit CA page and do the following:
- Select Use CA Name Change and specify a new Subject DN in New Subject DN text field.
(If options are hidden in the GUI, your administrator needs to activate Enable CA Name Change on the System Configuration page)
- Enable link certificates
- To Renew CA, click Renew CA
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
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.
ECA Specific Fields
ITS Enrollment Certification Authorities (ECAs) certificates contain a completely different set of attributes compared to X.509, thus the CA fields are also rather different. Below is a description of CA fields specifically used for ECA creation only.
- CertificateId: Unique identifier for the Enrollment Authority (EA). Any text string is allowed but there are protocol-specific naming structures described in specifications such as the C-ITS Point of Contact (CPOC) Protocol release 1.2.
- Geographical Regions: Indicates in which region the certificate is valid. EJBCA currently supports circular, rectangular, and identified European regions.