Certificate Field Validators

Certificate field validators are run on specific fields on the CSR, such as the dnsName SAN field.

Google Safe Browsing Validator

The Google Safe Browsing Validator performs a lookup of the domains in the certificate against the Google Safe Browsing Lookup API v4. The Google Safe Browsing API is listing websites used for distribution of malware and phishing.

The Google Safe Browsing API should only be used for non-commercial purposes.

Before the validator can perform lookups against the API, you need to create an API key using the Google Developer Console, see https://console.developers.google.com/.

CAA Validator

ENTERPRISE

The Certificate Authority Authorization (CAA) validator is based on RFC 6844, erratum 5065, RFC 9495 and the CA/Browser Forum Baseline Requirements Certificate Policy for the Issuance and Management of Publicly-Trusted Certificates. These specify that for complying CAs issuing certificates containing DNSName fields (for TLS validation) and rfc822Name fields (for S/MIME validation) values in the subjectAltName extension, the CA must perform a lookup check to the DNS CAA records of all specified names and check that the CAA records allow issuance for the given issuer.

The result of all CAA lookups is written to the server logs on INFO level.

TLS Validation

A typical CAA record has the following format:

example.com. 243	IN	CAA	0 issue "ca.org"

This record says that the issuer known as "ca.org" is permitted to issue certificates (including wildcards) for all domains and subdomains to the domain "example.com". In the EJBCA case, this means that according to CAA, an end entity that includes the field DNSNAME=example.com in the subjectAltName (SAN) extension must pass a CAA Validator check before having a certificate issued to it.

S/MIME Validation

CA/B Forum specifies the criteria for allowing or rejecting a SMIME certificate request based on a performed CAA check defined on the S/MIME Base Requirements document.

A typical S/MIME CAA Record has the following format:

example.com. 243	IN	CAA	0 issuemail "ca.org"

This allows the issuer known as ca.org to issue certificates that include email fields with the domain (user@example.com).

To comply with the S/MIME base requirements, the domain part of the rfc822name attributes will be validated against this records.

For example, a certificate request with a "Subject Alternative Name" like rfc822name=john.doe@example.com , can be issued for ca.org, since there is a record allowing this.

For the complete set of examples, check Section 5 - RFC 9495.

In order for this type of validation to be triggered, in addition to creating the CAA validator, in the certificate profile the field "Email protection" has to be marked in the "Extended Key Usage" field.

When using a CAA validator, either Email Protection or Server Authentication should be selected, not both.

Configuration

Issuance Phase

The CAA Validator can be run during the data phase only.

Fields

EJBCA allows the administrator to configure the following when setting up a CAA Validator:

Field Name Description

Issuers

This value should match the value field in the CAA record of the DNS, thus "ca.org" in the above example. If required, you can specify multiple issuers by separating them with a semicolon. For example, specifying "ca1.org;ca2.org;ca3.org" will match a CAA record with either ca1.org, ca2.org or ca3.org.

DNS Resolver

Optional field for specifying an IP address as DNS Resolver (such as 8.8.8.8 or 8.8.4.4). If left blank, Google's Public DNS will be used.

Port can be appended to the end of the IP address. If left blank, then the default port 53 will be used.

Lookup DNAMEs

Select to look up and follow any DNAME records found during CAA processing. To comply with RFC 6844, it is recommended to keep this option enabled.

Validate DNSSEC

Select to validate DNSSEC to be validated. If enabled and your DNS is signed with DNSSEC and your DNS presents a faulty set of records (suggesting a possible MitM attack), CAA validation will fail. It is strongly recommended to enable DNSSEC checks to ensure the authenticity of DNS responses.

Trust Anchor

Trust anchors are configured to allow obtaining secure answers from the root zone of the DNS using DNSSEC. By default, IANA root anchor is used. This value may be modified but should remain unchanged unless the record is signed by another trust anchor.

Fail on lookup error

The default behavior is to permit issuance if a lookup error is encountered more than once and EJBCA can establish that the domain is not signed with DNSSEC. To always prohibit issuance when a lookup error is encountered, enable this option. To have this option enabled may be a compliance requirement if you are contacting your own DNS resolver for CAA lookups.

DNS Protocol Select one Dns Protocol either UDP or TCP. If left blank, then default protocol should be UDP(Recommended).

Ignore Top Level Domains

CAA records are seldom put on TLD level, and looking up CAA records for the TLD can waste milliseconds. With this setting, you can specify a newline-separated list of top-level domains for which no CAA lookups will be performed. For example:
com
se

CAA lookups will still be performed on subdomains as usual, e.g. foo.com and foo.bar.se.

Ignore Domain Names

Domain names to exclude from CAA validation. Wildcards are supported. For example:
foo.com
foo.bar.se
*.onion
*.nocaa.co.uk
nocaa.co.uk

Ignore Critical Property Tags

Critical tags to ignore during CAA lookup. This allows for CAA lookup to continue even if critical tags unknown to EJBCA are encountered. For example:

contactemail
contactphone

Use with caution! By default unknown critical tags result in issuance prohibited. Ignoring critical tags does not conform with RFC6844

Use IODEF E-mail

Select to enable sending e-mails to any mailto-links registered on the DNS as CAA IODEF records. Doing so enables the following additional settings:

From	The From field in the resulting e-mail.
Subject	The Subject line in the resulting e-mail.
Additional Information:	Any additional information required, in addition to the following default message which will be appended at the end: A faulty Certificate Request was made for the domain 'example.com' for the issuer ca.com which was rejected by the CA due to the issuer not having a CAA record on the domain's DNS.
Use IODEF WEB	Enables sending IODEF incident reports to any http/s-links registered on the DNS as CAA IODEF records.

Note the following regarding CAA validation:

CAA validation will pass if the DNS lacks CAA records entirely.
CAA validation will pass if the DNS has only TLS records (issue, issuewild, etc) for a S/MIME validation.
CAA validation will pass if the DNS has only S/MIME records (issuemail) for a TLS validation.
EJBCA uses IPv4 to perform lookups of CAA records.
EJBCA currently does not validate parameters in CAA records, but such records will still be evaluated correctly. Parameter handling is planned in future versions.
The CAA Validator requires TCP and UDP port 53 to be open in the firewall.
Current iodef implementation does not support TLS protocol to send iodef reports over a secure connection. This will be added per request by customers or in future releases.
Another limitation is that the implementation does not support callback, only immediate responses with code 200 OK are supported. For more information, refer to RFC-6546.
The attributes in the produced incident report are the minimum required ones. Optionals are ignored for now but could be added if requested.
EJBCA currently does not support the CAA Contact property as defined in section 1.6.1 of the Baseline Requirements.

CAA Validator Logging

The CAA validator logs both success and failure. Since success can be considered a security event, to be shown as evidence, this is logged in the security audit log. Failures are not security events per se and logged to the standard server log at info level.

Example failure:

15:49:07,017 INFO  [org.cesecore.keys.validation.KeyValidatorSessionBean] (default task-24) VALIDATOR_VALIDATION_FAILED;FAILURE;VALIDATOR;CORE;msg=CAA Validator 'CAA Validator' failed issuance of certificates 
to issuer primekey.com, with messages: 
[Not allowed to issue certificate for dnsName *.allow.klaan.nu. Result type was: Issuance of wildcard certificates for this domain is prohibited. Parameters: {} Message: 
, Allowed to issue certificate for dnsName *.klaan.nu. Result type was: May issue, no CAA results for domain. Parameters: {} Message: 
, Not allowed to issue certificate for dnsName allow.klaan.nu. Result type was: Rejected due to issuer not having a CAA record at domain's DNS, or issuance being prohibited. Parameters: {} Message: ].

Example success:

15:50:58,930 INFO  [org.cesecore.audit.impl.log4j.Log4jDevice] (default task-8) 2017-09-20 15:50:58+02:00;VALIDATOR_VALIDATION_SUCCESS;SUCCESS;VALIDATOR;CORE;ejbca;1865017768;;caaklaan1;msg=CAA Validator 'CAA Validator' 
has permitted issuance of certificates to issuer primekey.com, with messages: 
[Allowed to issue certificate for dnsName *.klaan.nu. Result type was: May issue, no CAA results for domain. Parameters: {} Message: 
, Allowed to issue certificate for dnsName a.allow.klaan.nu. Result type was: May issue. Parameters: {} Message: primekey.com
, Allowed to issue certificate for dnsName b.allow.klaan.nu. Result type was: May issue. Parameters: {} Message: primekey.com].

The debug logging DNS lookup result available can amount to large volumes and is therefore set at a debug level disabled by default. To enable a separate DNS lookup log, you can send the DEBUG log for the class CaaDnsLookup to a separate log, similar to the OCSP Transaction and Audit logging. For more information, see Logging.

Domain Block List Validator

Domain Block List Validators allow DNSNAME attributes in Subject Alternative Name to be checked before issuance.

The intended use case is to require confirmation during the approval process for certain high-value domains (provided that approvals are enabled), but Domain Block List Validators can also be used for blocking known fraud sites, for example.

You can configure multiple validators with different settings. The following example shows a validator configured to allow validation while warning the administrator during the approval process.

Issuance Phase

The Domain Block List Validator can be run during the data or approval phase. If configured to run during the approval phase, and validation fails, a confirmation message will be shown in the RA Web for the approving administrators.

If the validator has been set to run during the approval phase and no approval requirements exist for the CA or Certificate Profile, then it will have no effect.

Fields

The following lists available Domain Block List Validator fields:

Field Name

Description

Normalizations to apply

The normalization to be performed against the domains before comparing against the block list. Only one normalization is currently available:

ASCII Lookalikes: This normalizes character or character sequences that look similar. IDN/Punicode characters of domains are not changed. The following characters and character sequences are normalized:

From	To	From	To	From	To	From	To	From	To	From	To	From	To
ci	a	cl	d	vv	w	6	b	9	g	I (i)	l (L)	2	z
fi	a	rn	m	0 (zero)	o	q	g	1 (one)	l (L)	5	s	u	v

Checks to perform

The checks control how domains are compared against the entries in the block list. At least one must be selected.

Base domain: All base domains will be compared against the block list. If issuing a certificate for "a.b.example.com", then "a.b.example.com", "b.example.com", "example.com", and "com" will be checked against the block list.

Domain component: All domain components will be checked, individually. So for "a.b.example.com", the block list will be searched for "a", "b", "example", and "com".

Exact match: Domains that match exactly will be matched. Note that this check is included with "Base domain". For "a.b.example.com", it will only search the block list for "a.b.example.com".

Existing block list

Shows information about the currently active block list and only displays once a block list has been uploaded.

Number of entries: Number of domains in the block list. The effective number of block listed domains may be greater due to normalization and the checks performed.

Upload date: Time when the block list was uploaded. Shown in UTC timezone.

SHA-256: Hash of the entire file, as uploaded (i.e. including comments and whitespace).

Upload new block list

Click Browse to upload a block list. Any existing block list will be replaced when a new one is uploaded.

For information on syntax, see Certificate Field Validators#Block List File Syntax. Depending on your configuration, there may be a file size limit. With a limit of 1 MB, you will be able to put around 50 000 domains in your block list. To work around this limit, you can split the block list and use several validators.

Block List File Syntax

Block list text files contain one block listed domain per line:

IDN domains must be Punycode encoded
Empty lines are ignored
Leading and trailing whitespace is ignored
Text after a # is considered a comment and is ignored.
Comments may contain ASCII or UTF-8 text, but the file may not contain a byte order mark (BOM). If in doubt, save the file in plain ASCII format.

The following shows an example of a block list text file:

sample_blocklist.txt

BASH

# Sample block list file. Created 2019-03-01

bank        # If domain component blocking is enabled, then this will block "bank.com", "bank.example.com" but NOT "memorybank.com"

example.com # With base domain blocking one can block a domain including subdomains.
net         # ...or entire TLDs (Top Level Domains)

evil.example.edu           # It is possible to block a specific subdomain only
xn--rvare-jua.example.com  # This is an IDN domain "rövare.example.com"

Domain Allow List Validator

Domain Allow List Validators allow DNSNAME attributes in Subject Alternative Name to be checked before issuance.

The intended use case is to relax the validation process for a few selected domains. The validator supports wildcard(*) for easier configuration.

Fields

The Domain Allow List Validator Settings contains one field that accepts a configuration file with allowed domain names. The syntax of the file is described below. Click Browse to upload an allowed domain list. Any existing list will be replaced when a new one is uploaded.

The allowed domain list follows similar rules as the Block List Validator:

IDN domains must be Punycode encoded with the exception of the asterisk character (*) to indicate wildcards.
Empty lines are ignored.
Leading and trailing whitespace is ignored.
Text after a # is considered a comment and is ignored.
Comments may contain ASCII or UTF-8 text, but the file may not contain a byte order mark (BOM). If in doubt, save the file in plain ASCII format.

The following shows an example of a allow list text file:

sample_allowed_domains.txt

BASH

permit.com
permit.example.com
#good.example.com
permit2.example.com # this is a comment
    permit3.example.com     
permit4.example.com# comment
permit5.*.example.com # allows: 'permit5.abc.example.com' and 'permit5.*.example.com' but blocks: 'permit5.example.com' or 'permit5..example.com'
*.permit6.*.example.com # allows: 'abc.permit6.xyz.example.com' or '*.permit6.xyz.example.com' or 'abc.permit6.*.example.com' but blocks: 'permit6.xyz.example.com' or 'abc.permit6.example.com'
permit7.example.* # allows: 'permit7.example.io' or 'permit7.example.com' but blocks: 'permit7.example'