Validation Methods¶

ACME providers can validate by checking the contents of a TXT record in DNS, or by fetching a file in a known location from a web server.

The ACME package support validating directly with standalone methods or webroot, but those options are less secure than DNS-based options. The ACME package also supports numerous methods to update various DNS providers. Wildcard certificates can only be obtained through DNS-based methods (Wildcard Certificates)

Tip

DNS-based update methods are the best practice as they do not require external inbound access. They can be used for internal systems that do not allow or cannot receive Internet traffic.

The following list is only a portion of the validation methods supported by the package.

nsupdate¶

The nsupdate method uses RFC 2136 style DNS updates to populate a TXT record in DNS.

Before starting, an appropriate DNS key and settings must be in place in the DNS infrastructure for the domain to allow the host to update a TXT DNS record for _acme-challenge.<domain name>.

This method has the following options:

Server:

The IP address or hostname of the DNS server to which the client sends updates

Key Name:

The name of the update key

Leave this blank unless it is different than _acme-challenge.<domain name>

Key Algorithm:

The algorithm used for the key, which must match the key and the server

Key:

The update key for this record

Zone:

Sets the zone name the package sends to the DNS server in the update request

DNS-Manual¶

The manual DNS method can be utilized when a firewall cannot receive inbound traffic and it does not have access to any automatic DNS-based method.

The manual in the name indicates that the process must be performed by hand both initially and when it is time to renew the certificate. The firewall obtains the authorization value and then the TXT record must be manually created or updated with this value.

Warning

Avoid using this method unless no other method is available.

To use this method:

Add an entry to the Domain SAN list
Mode: Enabled
Enter domain name (e.g. myhost.example.com)
Set Method to DNS-Manual
Click Save
Click Issue

Locate the record info in the output:

[Mon Feb 6 14:49:23 EST 2017] Add the following TXT record:
[Mon Feb 6 14:49:23 EST 2017] Domain: '_acme-challenge.www.example.com'
[Mon Feb 6 14:49:23 EST 2017] TXT value: 'xPrykHSri5epT5yrJJWyY536Z1T51r_Ef4LkWJry-iw'
[Mon Feb 6 14:49:23 EST 2017] Please be aware that you prepend _acme-challenge. before your domain
[Mon Feb 6 14:49:23 EST 2017] so the resulting subdomain will be: _acme-challenge.www.example.com
[Mon Feb 6 14:49:23 EST 2017] Please add the TXT records to the domains, and retry again.

Add or update the TXT record in the domain’s DNS server for _acme-challenge.<domain name> with the TXT value from the output
Wait approximately 2 minutes, or longer, for DNS to propagate
Click Renew

Namecheap API¶

For certain accounts with Namecheap, API access may be obtained that allows remote manipulation of DNS records. This can be used with the ACME package to validate certificates for domains with DNS hosted at Namecheap using their BasicDNS servers.

Warning

The Namecheap DNS API requires that the client read all records and then write them all back when making any change. This is potentially dangerous. Take a backup of all DNS records on the domain before attempting to use the API.

The first step is to request API access:

Login to a Namecheap account
Navigate to Profile > Tools under the account
Look for Namecheap API Access under Business & Dev Tools
If the status does not say On, then click Manage and change the slider to On.

Note

API access must be approved by Namecheap. There are qualifications to meet, such as a specific number of domains or a balance on the account. Check the Namecheap API documentation for more information. The process is documented as taking 2 days, but may take longer. If API access is not enabled after several days, contact Namecheap support.

Once the API is enabled, then perform the following steps:

Login to a Namecheap account
Navigate to Profile > Tools under the account
Look for Namecheap API Access under Business & Dev Tools
Click Manage
Note the API key for use in the ACME package
Click Edit and add whitelisted IP addresses that can contact the API using this API key.

Now setup the account in the ACME package:

Add an entry to the Domain SAN list
Mode: Enabled
Enter domain name (e.g. myhost.example.com)
Set Method to DNS-Namecheap
Click + to expand the method-specific settings
Fill in the info

API Key:

The API Key displayed in the Namecheap API Access manager, as described previously.

Username:

The Namecheap account username associated with the API Key.
Ensure the other options are set properly, per Create a certificate.
Click Save
Click Issue/Renew

Other DNS Methods¶

The package contains several additional DNS-based methods for other providers. These work similar to the nsupdate method above, but have configuration values specific to each provider. Contact the DNS provider or server administrator to obtain the necessary settings or credentials.

FTP Webroot¶

The FTP webroot method is useful when the firewall is performing NAT (port forward or 1:1) or reverse proxy duty for handling traffic for the domain. The firewall can use SFTP or FTPS to store the domain validation files on a web server behind the firewall so it does not have to host the files itself.

This method has the following options:

Server:: The server where the package will send the challenge response files, e.g. sftp://x.x.x.x

Note

This method supports sftp:// and ftps:// servers.
Username/password:: Credentials for the SFTP/FTPS account
Folder:: Full path to the target directory including /.well-known/acme-challenge at the end

Warning

Make sure the specified user has write permissions to the directory!

Webroot Local Folder¶

This method works similar to FTP Webroot but with the files hosted on the firewall itself. This method cannot be utilized by the GUI web server as that would mean exposing the GUI to the Internet, which is a major security issue.

This method can, however, be used in conjunction with the HAProxy package to host the files on the firewall itself in some circumstances. See https://forum.netgate.com/post/677786 for details.

Standalone (HTTP/TLS-ALPN)¶

The Standalone methods for HTTP and TLS-ALPN run a small web server natively that is active only while the validation process is running. The TLS-ALPN method is more secure as it encrypts communication with the ACME provider.

Warning

These methods are not best practices as they expose a service on the firewall to the Internet. Only use these methods if no other method is available.

Warning

The service must be accessible using port 80 (HTTP) or 443 (TLS-ALPN)!

If the firewall is using port 80 (HTTP) or 443 (TLS-ALPN) for another service, such as the firewall GUI or its redirect, then this method may not be viable. If the service on the port is public, then it cannot be used. If the service is private, then it may be possible to relocate the existing service or bind the update method to an alternate port, then port forward on the WAN interface.

A firewall rule must allow traffic to the target port at all times, it cannot be automatically enabled and disabled in the current package.

Note

The standalone binding should only be changed if the port is forwarded via NAT to a different port (e.g. 80 forwarded to 8080)

Standalone HTTP¶

Standalone HTTP Server has the following options:

Port:: Port to which the package will bind listening for HTTP requests with a stand-alone server. Must be 80 or port 80 must be forwarded to this port on the default gateway WAN.

Warning

If port 80 is used by the standalone service, the GUI redirect must be disabled on System > Advanced using the Disable webConfigurator redirect rule option. If the redirect is active when standalone mode attempts to use the port, it will print an error message stating that socat is unable to bind to the port.
Bind to IPv6 instead of IPv4:: If the domain name for the firewall has both an A and AAAA DNS record, check this option so that validation can occur over IPv6.

Standalone TLS-ALPN¶

Standalone TLS-ALPN Server has the following options:

Port:: Port to which the package will bind listening for TLS-ALPN requests with a stand-alone server. Must be 443 or port 443 must be forwarded to this port on the default gateway WAN.

Warning

If port 443 is used by the standalone service, the GUI must be moved to an alternate port on System > Advanced using the TCP Port option for the GUI. If the redirect is active when standalone mode attempts to use the port, the standalone service will fail.