Validators and the Identifiers Command

In a typical ACME implementation using Let’s Encrypt, proof of domain ownership is established using challenges such as HTTP-01 or DNS The Domain Name System is a service that translates names into IP addresses.-01. Keyfactor ACME supports a similar challenge mechanism and includes support for four validators:

• DNSRegexValidator (Custom)

  Supports domain name validation and whitelisting based on regular expressions. This validator cannot be used concurrently with either the Http01ACMEValidator or the DNS01Validator. Only one of these three validators may be configured at a time.

• Http01ACMEValidator

  Supports HTTP-01 challenges by requiring the ACME client (e.g., Certbot) to place a file on the target server containing validation information. With Certbot, this is specified using the -d DOMAINS parameter A parameter or argument is a value that is passed into a function in an application..

  For HTTP-01 validation, the requested domain must exactly match a non-regex A regular expression--RegEx--is a pattern used to validate data by ensuring it meets specific criteria. Several fields on the CSR enrollment, CSR generation, and PFX enrollment pages support RegEx validation, including certificate subject and metadata fields. hostname The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). identifier defined in the system. Regular expression A regular expression--RegEx--is a pattern used to validate data by ensuring it meets specific criteria. Several fields on the CSR enrollment, CSR generation, and PFX enrollment pages support RegEx validation, including certificate subject and metadata fields. identifiers are not evaluated for HTTP-01 challenges.

  Important:  The Http01ACMEValidator does not support wildcard enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). requests. If you plan to use wildcards, do not enable this validator.

• DNS01Validator

  Handles DNS-01 challenges by verifying a DNS record associated with the domain. Supports following CNAME or NS records through multiple hops (up to a maximum of 100) to locate the TXT records configured for _acme-challenge.<DOMAIN>. Validates that the final TXT record matches the ACME challenge value.

• IPSubnetValidator (Custom)

  Supports domain validation and whitelisting based on IPv4 and IPv6 addresses. It operates independently of the HTTP and DNS validators and can be used alongside them.

For more information on the DNS-01 and HTTP-1 challenge types, refer to the Let’s Encrypt and cert-manager documentation:

Keyfactor ACME uses the Identifiers command to define a whitelist of allowed domain names for pre-authorization and CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. enrollment through the Keyfactor API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command.. Identifiers populate the SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. of issued certificates with the specified DNS names.

• Explicit Identifiers

  Explicit identifiers define allowed hostnames using exact values. These identifiers are required for HTTP-01 validation and must match the requested hostname exactly.

  Added by listing each allowed domain in a space-separated list.

• Implicit Identifiers

  Implicit identifiers are defined using regular expressions by running the Identifiers command with the -x or --regex option. These identifiers are evaluated only by the DNSRegexValidator and are not used for HTTP-01 or DNS-01 validation. This approach is useful for scenarios such as allowing all subdomains under a domain.

  Identified using a regular expression by running the command with -x or --regex. This approach is useful for scenarios such as allowing all subdomains for a new company.

By default, the following two validators are enabled:

• DNSRegexValidator

• IPSubnetValidator

Configure Validators

To change the validators that are configured:

1. Navigate to the to API\extensions\Validators folder on the Keyfactor ACME server, located by default at:

   C:\Program Files\Keyfactor\ACME\API\extensions\Validators

2. Browse to open the manifest.json file in a text editor (e.g. Notepad) and adjust the values as needed.

   Initial configuration:

   Copy

   {
     "extensions": {
       "Keyfactor.ACME.Extensions.OrderValidation.IACMEValidator": {
         "DNSRegexValidator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.DNSRegexValidator"
         },
         "IPSubnetValidator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.IPSubnetValidator"
         }
       }
     }
   }

   HTTP-01 Validator:

   Copy

   {
     "extensions": {
       "Keyfactor.ACME.Extensions.OrderValidation.IACMEValidator": {
         "Http01ACMEValidator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.Http01ACMEValidator"
         },
         "IPSubnetValidator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.IPSubnetValidator"
         }
       }
     }
   }

   DNS-01 Validator:

   Copy

   {
     "extensions": {
       "Keyfactor.ACME.Extensions.OrderValidation.IACMEValidator": {
         "DNS01Validator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.DNS01Validator"
         },
         "IPSubnetValidator": {
           "AssemblyPath": "Keyfactor.ACME.Validators.dll",
           "TypeFullName": "Keyfactor.ACME.Services.OrderValidation.IPSubnetValidator"
         }
       }
     }
   }
    

3. Save the file.

Configure Whitelists

Identifiers define which domain names or addresses are authorized for Keyfactor ACME enrollment. How an identifier is evaluated depends on the validator configuration in use.

• HTTP-01 and DNS-01 validation requires explicit, non-regex hostname identifiers that exactly match the requested domain name.

• Regular expression identifiers are evaluated only by the DNSRegexValidator and are not used for HTTP-01 or DNS-01 validation.

• Wildcard identifiers require wildcard support to be enabled and are evaluated based on the active validator configuration.

• IP subnet identifiers are evaluated only by the IPSubnetValidator.

After configuring the Keyfactor ACME software, set the supported domain list for it as follows:

1. Open a command prompt using the Run as administrator option.

2. Change to the Configuration directory under the directory in which you installed Keyfactor ACME. By default, this is:

   C:\Program Files\Keyfactor\ACME\Configuration

3. Execute a command similar to the following, where the values in red are replaced with correct values for your environment (see Table 6: Identifiers Command Options):

   KeyfactorACMEConfig.exe identifiers -a FQDN_one FQDN_two FQDN_three
   Tip:  Run the Keyfactor ACME commands at the command line or in a regular PowerShell window, NOT using the PowerShell ISE (as it does not have support for the “Console” class).

   For example:

   • Support three explicit domain names:

     KeyfactorACMEConfig.exe identifiers -a help.keyexample.com support.keyexample.com live.keyexample.com

   • Support one domain name with wildcards:

     KeyfactorACMEConfig.exe identifiers -a *.keyexample.com -w

     Note:  In order to support wildcards, the use of wildcards must be enabled. See Settings.

   • Support any domain name beginning with lowercase a-z and ending with the domain keyexample.com by specifying a regular expression:

     KeyfactorACMEConfig.exe identifiers -a [a-z]+\.keyexample\.com -x

   • Support one IPv4 subnet with host variations in CIDR notation:

     KeyfactorACMEConfig.exe identifiers -a 192.168.12.0/24 -s

   • Support a single IPv6 CIDR range:

     KeyfactorACMEConfig.exe identifiers -a 2001:db8:abcd::/48 -s

   • List the configured identifiers:

     KeyfactorACMEConfig.exe identifiers -l

Table 6: Identifiers Command Options

Short Name	Long Name	Description	Value
-a	--add	The list of domain names allowed in certificate requests.	Space separated list of strings.
-l	--list	List all identifiers present in the database—whether they are explicit, based on a regular expression, wildcard, or IP address—and whether they are valid or revoked.
-x	--regex	Specifies that the strings provided with the -a option are regular expression strings. If none of -s, -x, or -w is specified, it indicates that the values entered are explicit values. The -s, -x and -w parameters are mutually exclusive.	A regular expression identifying one or more supported domain name structures.
-s	--subnet	Specifies that the strings provided with the -a option are IP address values. IP values are only supported in certificate SANs. Both IPv4 and IPv6 are supported. If none of -s, -x, or -w is specified, it indicates that the values entered are explicit values. The -s, -x and -w parameters are mutually exclusive.	Values must be provided in CIDR notation.
	--version	List the version of the command.
	--help	Display the command help screens.
-w	--wildcard	Specifies that the strings provided with the -a option are wildcard strings. If none of -s, -x, or -w is specified, it indicates that the values entered are explicit values. The -s, -x and -w parameters are mutually exclusive.