Validators and the Identifiers Command

In a typical Let's Encrypt / ACME implementation, 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): Validates domain names based on specific regular expressions.

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

• DNS01Validator: Handles DNS-01 challenges by verifying a DNS record associated with the domain.

• IPSubnetValidator (Custom): Validates domain ownership based on IP subnet restrictions.

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

Additionally, 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 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). 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: Added by listing each allowed domain in a space-separated list.

• Implicit Identifiers: Identified using a 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. by running the command with -x or --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.. This approach is useful for scenarios such as allowing all subdomains for a new company.

Configure Validators

By default, the following two validators are enabled:

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

  Tip:  Configuring more than one of these at the same time can result in unexpected behavior, since the processing order and rules around how multiple DNS validators are handled can result in validators being skipped.

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

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

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.