Certificate validation - rejetto/hfs GitHub Wiki
Choosing HTTP or DNS certificate validation
HFS can request a free HTTPS certificate from Let's Encrypt and renew it automatically. Before issuing a certificate, Let's Encrypt checks that you control every name on it. In Admin > Internet > HTTPS, the Validation selector chooses how HFS proves this.
DNS validation and the Validation selector described here are part of the HFS 3.4 development version (branch
4). Older versions offer HTTP validation only.
Which method should I choose?
| Your situation | Choose |
|---|---|
| Your domain reaches HFS from the Internet on TCP port 80, and you do not need wildcards | HTTP |
You need a wildcard such as *.example.com |
DNS, then your DNS provider |
| Port 80 cannot reach HFS, for example because of your ISP, firewall, CGNAT or network setup | DNS, then your DNS provider |
| You need a certificate for a public IP address rather than a domain | HTTP; DNS validation cannot validate IP addresses |
HTTP validation (HTTP-01) uses port 80 and cannot issue wildcard certificates. DNS validation (DNS-01) checks a temporary DNS TXT record and supports wildcards. See Let's Encrypt's explanation of the challenge types.
A certificate does not by itself make HFS reachable. If you use DNS validation because incoming connections are blocked, you still need a suitable network setup for visitors to reach HFS over HTTPS.
HTTP validation
Choose HTTP if all the names in your request reach HFS on public port 80.
HFS serves a temporary verification response under /.well-known/acme-challenge/. Let's Encrypt connects to that address to check it. DNS records, router forwarding and firewall rules must allow the request to reach HFS. If you use a reverse proxy, it must forward these verification requests correctly.
No DNS API token is needed. The same connectivity must be available when HFS renews the certificate. If the request contains a wildcard, choose DNS instead: HTTP cannot validate it.
DNS validation
Your DNS provider is the service hosting your domain's DNS records. It may be different from the company where you bought the domain or where your website is hosted.
- Enter the names in Domain for certificate, separated by commas or new lines.
- Choose your provider from the Validation selector, for example DNS ยท Cloudflare.
- Enter the provider's API credentials as described below.
- Click Request. HFS creates the temporary TXT records, waits for DNS propagation, requests the certificate and removes its temporary records.
- Enable Automatic renew before expiration to let HFS repeat the process using the saved credentials.
The page shows the current step and any error. Closing the page does not cancel a running request; reopening it shows the current status. If HTTPS is disabled, enable it after obtaining the certificate.
DNS validation needs outbound access to the provider API, public DNS and Let's Encrypt. It does not require an incoming connection to HFS.
Cloudflare
Create an API token with Zone / Zone / Read and Zone / DNS / Edit permissions, limited to the zones you want HFS to validate. Paste the token into HFS's API token field. HFS discovers the zone ID automatically; use a token, not the Global API Key.
Cloudflare provides instructions for creating and scoping an API token.
DigitalOcean
The domain's DNS zone must already exist in your DigitalOcean account. Create an API token with the custom scopes domain:read, domain:create and domain:delete, then paste it into HFS's API token field. These scopes allow the temporary records to be created and removed; see DigitalOcean's create and delete scope documentation.
Additional built-in providers
| Provider | Credentials and setup |
|---|---|
| DNSimple | An account API token, not a user token. HFS discovers the account ID automatically. See DNSimple tokens. |
| IONOS | The complete IONOS Hosting API key, including its public prefix and secret. HFS finds the zone by name. This entry is for the IONOS Hosting DNS API, not the separate IONOS Cloud DNS service. |
| Linode | An API token with read/write access to Domains. The zone must be hosted by Linode/Akamai; HFS discovers its ID. See Linode API authentication. |
| Name.com | Your API username and API token, for the Name.com CORE API. |
| OVHcloud / OVHcloud Canada | An application key, application secret and consumer key for the selected region. Choose OVHcloud for Europe, or OVHcloud Canada for Canada. See the permissions below. |
| Porkbun | An API key and Secret API key. Also enable API access for each domain in Porkbun's control panel. See Porkbun setup. |
| Vultr | An API token authorized to manage the relevant DNS zones. If API access is restricted by source IP, allow HFS's outgoing IP address. See Vultr DNS management. |
For OVHcloud, grant the keys permission to perform these operations for each zone HFS will validate (replace example.com with your zone):
POST /domain/zone/example.com/record
DELETE /domain/zone/example.com/record/*
POST /domain/zone/example.com/refresh
HFS signs requests, synchronizes with OVHcloud's clock and refreshes the zone after creating or removing records. Keys must belong to the selected region.
Other providers
Plugins can add further providers, which appear as separate entries in the same selector. You can also delegate the validation name to a supported provider as described below.
Keep API tokens private. HFS stores them in its configuration file, so protect that file and its backups. Leaving a saved credential field blank keeps the current value. If a token expires or is revoked, replace it before the next renewal.
Wildcards and multiple names
A wildcard covers one level of subdomains: *.example.com covers files.example.com, but not deep.files.example.com or example.com itself.
HFS automatically adds the name without *. to the certificate:
| You enter | HFS requests |
|---|---|
*.example.com |
*.example.com and example.com |
*.files.example.com |
*.files.example.com and files.example.com |
In the second example, enter example.com separately if you also want it included.
You can combine ordinary names and wildcards in one request for one certificate. If any name is a wildcard, use DNS validation for the request. HFS currently uses one DNS provider/account for the whole request, so that account must be able to validate every name, directly or through delegation. A mixed wildcard/IP request cannot use DNS validation.
Optional: delegate just the validation name
If your usual DNS provider is unsupported, you may be able to keep using it and send only certificate validation to a supported provider.
For example, suppose example.com uses an unsupported provider, while you also control other-domain.net through a supported provider. In the DNS control panel for example.com, create:
_acme-challenge.example.com CNAME example.validation.other-domain.net
Configure HFS with credentials for the provider hosting other-domain.net. HFS follows the CNAME and creates its temporary TXT record at example.validation.other-domain.net.
This changes where certificate validation happens; it does not move your website or your domain's other DNS records. Keep the CNAME for future renewals. Some DNS panels expect the relative name _acme-challenge instead of the full name on the left.
The same validation name serves example.com and *.example.com. Other names, such as files.example.com, need their own validation name (_acme-challenge.files.example.com) if you want to delegate them too.
If validation fails
- HTTP cannot reach HFS: check public port 80, the domain's DNS records, router forwarding, firewall and any reverse proxy. Alternatively, choose DNS validation.
- DNS API request fails: check that you selected the service actually hosting the DNS zone, and that the token is valid and has permission to create and delete its records.
- DNS propagation times out: check the public DNS records and any validation CNAME. HFS normally waits up to five minutes for its TXT value to appear; the IONOS integration allows fifteen minutes.
- Provider unavailable or incompatible: update HFS or reconfigure the provider as indicated. HFS does not silently choose a different provider or discard the current certificate.
- TXT cleanup fails: HFS reports a warning. Check the validation name in your provider's control panel and remove only the stale challenge value, preserving any other values that are still needed.
For manually supplied and self-signed certificates, see HTTPS.