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.

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.

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.

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.

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.

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.

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.

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:

• fingerprint

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

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

PrintableString encoding in DN

Using PrintableString encoding instead of UTF8 encoding for the DN. PrintableString encoding will be used for the CA DN and for the DN of the certificates issued by that CA. When configuring PrintableString encoding in DN, if any RDN contains a character not in the PrintableString set, that RDN will instead default to UTF8 encoding.

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.

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

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:

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:

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.

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.

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.

Allow Changing Revocation Reason

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

Allowed revocation reasons: Revocation reason can only be changed to Key Compromise from following previous revocation reasons: Key Compromise, Privileges Withdrawn, Unspecified, Cessation of Operation, Affiliation Changed and Superseded.

Backdating revocation date: Revocation reason can be changed with a backdated revocation date. Please note that this date cannot be later than the previous revocation’s revocation date, and must be enabled on Certificate Profile level with the “Allow Backdated Revocation” flag.

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

Request Processor

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:

• CMP

• REST

• WS

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
  

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,

1. Go to "Edit CA" page of intended CA

2. Scroll down to "Externally signed CA creation/renewal" section.

3. In "Step 2" subsection, select the cross certificate chain file and check "Store as a separate cross-certificate chain" box.

4. Now click on "Receive Certificate Response" to save the cross chain.

This chain may contain multiple levels of hierarchy and the CA certificates need not be imported in EJBCA as external CA. After the import a success message will be shown in all Certification Authorities page. This does NOT convert the CA into a "Externally signed CA" and EJBCA internal certificate chain is retained.

Multiple cross chains may be uploaded for a CA and they may also be removed in "Edit CA page" from "CA alternate cross-certificates" section. 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 same root subjectDn may be uploaded to replace the old chain.