CA Fields

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.

CA Types

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.
• SSH: SSH Certificates, see SSH CA

Signing Algorithm

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

Alternative Signing Algorithm

The alternative signing algorithm used for issuing hybrid certificates, signing CRLs etc.

Crypto Token

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.
• alternativeCertSignKey: The alternative key to use for hybrid certificate issuance. Must comply with the Alternative 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. See Key Recovery.
• 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.

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

This generator is not designed to generate a specified level of entropy, although the entropy will be fixed and can be easily calculated according to the rules below.

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:

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.

• serialNumber
• issuerDN
• username
• timestamp
• UserDataVO

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. When this option is enabled and Use Append-Only table is disabled, revoked certificates are stored in the CertificateData table. CRL generation and OCSP responses account for these revoked entries. 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 called NoConflictCertificateData. This table is used for CRL generation only and will not be queried for OCSP revocation responses. If you require OCSP responses in addition to CRL for the throw away certificate do not enable this option.

Pre-Produce OCSP Responses

ENTERPRISE

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.

Produce OCSP response upon issuance/revocation

With Produce OCSP response upon issuance/revocation enabled, an OCSP response will be generated and persisted every time a certificate is issued or revoked by this CA.

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

Name constraint	Description
example.com	Matches example.com and subdomains as a dnsName.
@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 Constraint is encoded as PrintableString, the certificate must also be issued with PrintableString in the subjectDN, otherwise Name Constraint matching will fail.
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.
uri:example.com	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

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

CRL Period

The following CA configuration settings control when and if a new CRL is generated:

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.

To issue a last CRL as defined in ETSI 319 411-2 (CSS-6.3.10-07), with nextUpdate set to '99991231235959Z' (ETSI EN 319 411-1 CSS-6.3.9-06), configure CRL Expire Period to '9999y'.

Allow Changing Revocation Reason

This setting enables changing revocation reasons for previously revoked certificates issued by the Certificate Authority. The revocation reason can be changed through RA Web UI, REST API, and Web Services.

Allowed revocation reasons

The revocation reason can only be changed to Key Compromise from the following previous revocation reasons:

• Key Compromise
• Privileges Withdrawn
• Unspecified
• Cessation of Operation
• Affiliation Changed
• Superseded

Backdating revocation date

The revocation reason can be changed with a backdated revocation date. Note that this date cannot be later than the previous revocation’s revocation date, and must be enabled on the Certificate Profile level using the Allow Backdated Revocation option, see Certificate Profile Fields.

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 http://ca.example.xy/cacert.cer.

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 4.2.2.1). 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 CA Issuer URI and OCSP Service Locator in Certificate Profile Fields.

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

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.

For more information, see C-ITS ECA Overview and Managing C-ITS ECAs.

X509 Cross Certificate Chain(s)

To upload a cross-certificate chain, do the following:

1. Go to the Edit CA page of the intended CA.
2. Scroll down to the Externally signed CA creation/renewal section.
3. In the Step 2 subsection, select the cross certificate chain file and select Store as a separate cross-certificate chain.
4. Click Receive Certificate Response to save the cross-chain.

The cross-certificate chain may contain multiple levels of hierarchy and the CA certificates do need not be imported into EJBCA as external CA. After the import, a success message is shown on all Certification Authorities pages. This does not convert the CA into an "Externally signed CA" and EJBCA internal certificate chain is retained.

Multiple cross-chains may be uploaded for a CA and can also be removed on the Edit CA page section CA alternate cross-certificates. The links shown as root subjectDn may be used to download or view the chain. These chains must end with a self-signed root certificate. A renewed chain with the same root subjectDn may be uploaded to replace the old chain.

Currently, only the ACME protocol can be used to select a cross-chain. For more information, see the Account Registration and Certificate Enrollment section in ACME with Certbot.