Available Key Algorithms

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

Available ECDSA Curves

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

Available Bit Lengths

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

Validity

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

• fixed date with ISO8601 format 'yyyy-MM-dd HH:mm:ssZZ', i.e. '2017-06-03 18:15:00+00:00', or

• relative time in terms of years, months, days, hours, and seconds in the form '*y *mo *d *h *m *s', i.e. '2y-10d'

For a relative validity, the end date of the certificate is calculated by its start date plus the value configured. The start time usually is the time point of issuance (i.e. if no offset for the start time is configured).

The field 'notAfter' in the issued certificate will have the value 'now + validity days'. It can also, if noted in the field, be entered in terms of years, months and days. For instance '10y 9mo 8d' is translated to 10 years, 9 months and 8 days from now. Instead of the validity period an absolute end date could specify the end of the validity period. This date should be given in the format 'yyyy-MM-dd HH:mm:ssZZ', for example, the date 'June 3rd, 2017 at 6:15 PM' in UTC should be given as '2017-06-03 18:15:00+00:00'.

The Allow Validity Override option allows requesting a specific notAfter date. This is currently possible when using CMP (the CRMF request format), when using the API to issue certificates, or by using the enrollment page on the RA web.

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, if 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 notBefore.

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

Validity Offset

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

If a fixed end date in the form '2016-10-09 14:41:39+01:00' is used as certificate validity, only the start date of the certificate will be offset.

If a relative time in form of '*y *mo *d *h *m *s' is used as certificate validity, start and end date of the certificate are offset.

Example: Use the value '-5m' to have a notBefore date that is 5 minutes before the current time, in order to be valid on relying parties if their clocks are a bit behind.

Expiration Restrictions

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

If a fixed end date in the form '2016-10-09 14:41:39+01:00' is used as certificate validity, the restriction is applied after saving the certificate profile and a user message with the new fixed end date is shown.

If a relative time in form of '*y *mo *d *h *m *s' is used as certificate validity, the restriction is applied during certificate issuance if it does not conflict with other restrictions (i.e. time nesting with the SubCA certificate).

Allow Extension Override

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

This option should only be used when you know that the request comes from a very trusted source. Such a trusted source is normally an RA through CMP or WebService.

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

• If Overridable extension OID list'is used and Extension list is disallowed is cleared, any OID on this list can be overridden, but no other OIDs can.

• If Overridable extension OID list is used and Extension list is disallowed is selected, no OID on this list is allowed to be overridden, but all other OIDs can be overridden.

Allow Subject DN Override by CSR

If subject DN override is allowed, the X509 subject DN created in a certificate can come directly from the CSR in the request sent by the user. This is instead of the normal way where the user's registered DN is used.

Using this option you can create certificates with very strange DNs, or with DNs in very specific orders.

This option should only be used when you know that the request comes from a very trusted source. Such a trusted source is normally an RA through CMP or webservice.

Allow Subject DN Override by End Entity Information

If subject DN override is allowed, the X509 subject DN created in a certificate can come directly from the request meta information sent by the user. This is instead of the normal way where the user's registered DN is used.

Using this option you can create certificates with very specific ordering of subject DN fields. Note the following:

• The provided subject will still have black-listed characters and white spaces removed.

• '+' is escaped since multivalued RDNs are not supported.

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

If 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 using the Admin GUI for creating entities, you must also add Custom certificate serial number to the used end entity profile.

With web services, use the 'setCertificateSerialNumber' for your 'UserDataVOWS' user.

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

Note that the row 'serialNumber' number in the 'CertificateData' database table must have a unique index for this feature to 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 can 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 the number of bits to be used in the serial number.

Example:

Allow Backdated 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. For more information, see Throw Away CA.

Store Certificate Data

Allows meta information about certificates to 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.

Path Length Constraints

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.   

Key Usage

The Key usage extension defines the suggested purpose of this certificate. For users, certificate usage is often separated in certificates used for signatures (Digital signature and Non-repudiation), and certificates used for encryption (Key encipherment and Data encipherment).

For CA certificates, Key Usage is normally set to Key certificate sign' and 'CRL sign.

The fixed profiles have sensible defaults. For more information, refer to RFC 5280.

Allow Key Usage Override

Enable to allow users to over-ride the key usages defined in the profile when requesting a certificate. Enabling Allow Key Usage Override allows having one certificate profile, but still issue certificates for different purposes. Leave it disabled unless you are sure what you are doing.

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 on the Admin Web System Configuration page. Select the Extended Key Usages tab and 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. For more information, see Extended Key Usages.

Certificate Policies

Certificate Policies indicates which policy a certificate issued with this profile is issued under. Certificate Policies are more described in several RFCs. A certificate policy is in the form of an OID: 2.5.29.32.0

The OID 2.5.29.32.0 is the 'anyPolicy' as defined by RFC 5280. If you make your own policy you must create your own OID, constructed from an 'Enterprise Number' assigned by IANA. Getting an Enterprise Number is free, and you can get it from IANA.

For example: The PrimeKey enterprise number is 22408 and an OID can be constructed like 1.3.6.1.4.1.22408.1.1.1.1. Here 1.3.6.1.4.1 is IANA standard prefix, PrimeKey is 22408 and the following stands for products->ejbca->attibutes->ejbcaDeviceCertificate. The numbers after 22408 are defined by PrimeKey.

Issuer Alternative Name

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

Usage examples:

• Use the Issuer Alternative Name extension 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.

• Add subject and issuer alternative name with a DirectoryName to a Root CA by setting the value for Subject Alternative Name to "DirectoryName=L=SWE\,ST=FOO", thus with the comma escaped.

CRL Distribution Points

The CRL Distribution Point (CDP) extension provides information 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.

A CRLDistributionPoint for a CA in EJBCA could look like:

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 configured a publisher to publish CRLs to LDAP:

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 selecting 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 do not 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

Note that if a URI contains a ';' it has to be double-quoted. For example, if you have two URLs:

• http://cdpurl-1/mycrl.der

• http://cdpurl-2/getcrl;binary

You could then put them together as: http://cdpurl-1/mycrl.der;"http://cdpurl-2/getcrl;binary"

CRL Issuer

According to RFC5280 a CRL issuer is:

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

The contents of the field in the profile is a DN, like "CN=CRLIssuerForManagementCA,O=foo,C=SE". You have to build the actual CRL Issuer software yourself. If set, and the certificate profiles includes it, the CRL Issuer is included in the CRL Distribution point in issued certificates.

Freshest CRL

The Freshest CRL extension (also called Delta CRL Distribution Point) 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.

From RFC5280:

The freshest CRL extension identifies how delta CRL information is obtained.  The extension MUST be marked as non-critical by conforming CAs. Further discussion of CRL management is contained in Section 5.

The same syntax is used for this extension and the cRLDistributionPoints extension, and is described in Section 4.2.1.13. The same conventions apply to both extensions.

OCSP Service Locator

This extension is used when revocation information for the certificate containing this extension is available using the Online Certificate Status Protocol (OCSP) [RFC6960] (former RFC2560). The URI field is the location of the OCSP responder, using the conventions defined in RFC6960, usually a plain URL such as http://ocsp.company.com/. The default URL for the internal OCSP responder in EJBCA is http://hostname:8080/ejbca/publicweb/status/ocsp.

CA Issuer URI

This value is used for the Authority Information Access CRL extensions field CA Issuer as specified in RFC5280 (section 5.2.7).

The URIs specified in this semi-colon separated list must point to files containing either a single certificate (.cer or .der) or a collection of certificates (.p7c).

Use LDAP DN Order

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

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

• first-to-last, reverse order: C=Country, O=Organization, CN=Common name

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

The most common order is first-to-last (i.e. C,O,CN), but for historical reasons EJBCA uses last-to-first (CN,O,C). Some applications do require first-to-last order however and therefore EJBCA gives you the choice (by clearing 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 references, see RFC2253 and RFC4514.

When using a Custom DN Order, the LDAP DN order setting is also applied by default, defining which component comes first (CN or C for example), regardless of the exact order you specified in the text field. Clear Apply LDAP DN order setting for the Custom DN Order to use the exact order as specified.

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 of the Start offset (startOffset) and Period length (periodLength) fields as follows:

notBefore = cert.notBefore + startOffset
notAfter = notBefore + periodLength

Qualified Certificate Statement

The Qualified Certificate Statement is generally described in RFC 3739 and in ETSI documents. The following fields implement the predefined QC-statement from RFC 3739. See section 3.2.6.1 in RFC 3739. RFC3739 does not specify if QC should be critical or not, it may be either.

• Use PKIX QCSyntax-v2: RFC3739 defines an older version (v1 from rfc3039) and a new (v2 from rfc3739).

• Semantics Id: An object identifier, for example 1.2.3.4.5.

• Name Registration Authorities: If present, should contain a name of one or more name registration authorities, responsible for registration of attributes or names associated with the subject (for example rfc822Name=).

The next fields implement the QC-statements defined in the Qualified Certificate profile in ETSI TS 101 862:

• Use ETSI QC Compliance: Statement claiming that the certificates is a Qualified Certificate (section 5.2.1 in the profile document).

• Use ETSI Secure Signature Creation Device: Statement claiming that the private key related to the certified public key resides in a Secure Signature Creation Device (section 5.2.4 in the profile document).

• Use ETSI transaction value limit: Statement regarding limits on the value of transactions. If set, the following fields must be specified:

  • Value Limit Currency: For example, EUR, SEK.

  • Value Limit Amount: For example, 10000.

  • Value Limit Exponent: For example, 0, 1. Total value = amount * 10^exponent.

The fields for Custom QC-statement String implement a QC-statement with the following ASN.1:

qcStatement-YourCustom QC-STATEMENT ::= { SYNTAX YourCustomUTF8String
 IDENTIFIED BY youroid }
-- This statement gives you the possibility to define your own QC-statement
-- using an OID and a simple UTF8String, with describing text. A sample text could for example be:
-- This certificate, according to Act. No. xxxx Electronic Signature Law is a qualified electronic certificate

YourCustomUTF8String ::= UTF8String

• Use Custom QC-statement String: Include this custom QC-statement in the QC-statements extension in the certificates.

• Custom QC-statement OID: Your OID as defined above, you must define this OID yourself.

• Custom QC-statement Text: The describing text as defined above.

A typical eIDAS QC Statement (EN 319 412-5) may consist of:

• id-etsi-qcs-QcCompliance

• id-qcs-pkixQCSyntax-v2

• id-etsi-qcs-QcSSCD

• id-etsi-qcs-QcPDS = www.primekey.com/repository

• id-etsi-qcs-QcType = 0.4.0.1862.1.6.1 (Electronic Signature)

• SematicsID = 0.4.0.194121.1.2

Certificate Transparency

ENTERPRISE EDITION This is an EJBCA Enterprise Edition (EE) feature.

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. For more information, refer to the CT website.

The following options are visible if the CT module is available (In EJBCA Enterprise Edition):

• 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 Labels: Which labels to submit to and obtain Signed Certificate Timestamp (SCTs) from. Each label contains a set of CT logs. At least one log from each selected label will be submitted to. New logs and labels can be added in the System Configuration, see Certificate Transparency.

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

  • By Validity: Automatically sets the number of minimum SCT responses based on the validity of the certificate. The value is determined by the CT Policy for Chrome (May 2016).

  • Custom: Specifies the minimum number of SCT responses manually. This value cannot be less than the number of selected labels since at least one CT log from each label will be written to and expect a response

• Maximum number of SCTs: After having received this number of SCTs, EJBCA will stop contacting log servers.

  • By Validity: Sets the number of maximum SCT responses by validity i.e. maximum = minimum. This ensures that no more SCTs than required will be included in the final certificate

  • Custom: Specifies the maximum number of SCT responses manually. This value cannot be less than the number of selected labels since at least one CT log from each label will be written to and expect a response.

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

Microsoft Template Value

The Microsoft Template Value is a special Microsoft extension used in Domain Controller (AD controller) certificates. It should only be used in certificates issued to Domain Controllers.

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.

Card Number

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