Skip to main content

ACME Ownership Verification Methods (CNAME / DNS API / HTTP-01 / TLS-ALPN-01)

When cert-ctrl issues or renews a certificate (Let’s Encrypt / ZeroSSL), it must prove you control the domain (or IP) using an ACME “challenge”.

In our system, a certificate can be verified using one of these methods:

  • CNAME delegation (DNS-01): one-time CNAME on your domain; we manage TXT on our own domain.
  • DNS API (DNS-01): you provide DNS provider credentials; we create/delete TXT in your DNS zone.
  • HTTP-01: a cert-ctrl agent serves a token at http://<domain>/.well-known/acme-challenge/<token>.
  • TLS-ALPN-01: a cert-ctrl agent terminates TLS on port 443 with ALPN acme-tls/1 using a one-off validation certificate.

Note: Wildcard certificates (*.example.com) require DNS-01 (CNAME or DNS API). HTTP-01 and TLS-ALPN-01 can’t validate wildcards.

1) CNAME Delegation (DNS-01) — recommended​

What you do​

Create one CNAME record (one-time setup):

Name:   _acme-challenge.example.com
Type:   CNAME
Target: <public-id>.acme.cjj365.cc

public-id is shown in the cert-ctrl UI when you add the certificate.

What cert-ctrl does​

  • The CA asks for a DNS-01 challenge token.
  • cert-ctrl creates a temporary TXT record under our zone:
    • <public-id>.acme.cjj365.cc TXT <challenge-token>
  • The CA resolves _acme-challenge.example.com, follows the CNAME, and reads the TXT.
  • After validation, cert-ctrl removes the TXT record. Your CNAME stays forever for renewals.

Why it’s preferred​

  • Works with any DNS provider (only needs CNAME support).
  • No DNS API keys from users.
  • Easy revocation: delete the CNAME.

For the full detailed walkthrough, see: DNS-01 Challenge: CNAME Delegation Explained

2) DNS API (DNS-01) — direct TXT in your zone​

When to use​

Use DNS API mode when:

  • You can’t use CNAME delegation, or
  • You prefer cert-ctrl to manage TXT records in your DNS zone.

What you configure​

You provide:

  • dns_provider_id (e.g. cloudflare, ali, dnspod_tencentcloud)
  • A provider secret (token / key), and sometimes extra provider variables (like zone id)

The supported provider list is driven by the server-side DNS provider catalog.

How it works in cert-ctrl​

  • cert-ctrl calls your DNS provider API to create a TXT record:
    • _acme-challenge.<domain> TXT <challenge-token>
  • The CA queries that TXT record to validate.
  • cert-ctrl deletes the TXT record after validation.

Security guidance​

  • Use the least-privileged DNS token possible (only DNS record operations for the required zone).
  • Treat DNS API credentials like root access to your domain.

3) HTTP-01 — agent serves a well-known URL​

When to use​

Use HTTP-01 when you can’t do DNS-01 (no CNAME and no DNS API), and your domain can reach a cert-ctrl agent over public port 80.

What must be true​

  • A/AAAA (or load balancer) for the domain must route to the machine running the cert-ctrl agent.
  • Port 80 must be reachable from the Internet.
  • No CDN/proxy behavior that changes the response body.

How it works in our system​

  1. cert-ctrl generates a token and its expected response body (keyAuthorization).
  2. bbserver sends an instruction over the tunnel to your selected device:
    • start serving /.well-known/acme-challenge/<token>
  3. bbserver performs a preflight probe (HTTP GET) to confirm it’s reachable and the body matches exactly.
  4. The ACME CA performs the real validation.
  5. cert-ctrl tells the agent to stop serving the challenge.

What you configure​

HTTP-01 verification requires:

  • challenge_device_id: which device/agent will serve the challenge
  • challenge_listen: where the agent should listen (must include bind and port)

If your agent listens on a non-80 port, you must forward 80 → agent_port at the network edge.

4) TLS-ALPN-01 — agent terminates ALPN acme-tls/1 on 443​

When to use​

TLS-ALPN-01 is useful when:

  • Port 80 is blocked, but
  • You can expose public port 443 to the cert-ctrl agent.

What must be true​

  • The domain routes to the agent on 443 (or you forward 443 → agent_port).
  • The connection must be raw TLS pass-through (some CDNs / reverse proxies break this).

How it works in our system​

  1. cert-ctrl generates a one-off TLS certificate whose SAN matches the domain and which proves the challenge (acme-tls/1).
  2. bbserver sends that certificate/key to your selected device.
  3. The agent temporarily serves TLS on the configured listener.
  4. bbserver runs a preflight probe: connects to the domain, performs TLS handshake, and checks ALPN selected is acme-tls/1.
  5. The ACME CA performs the real validation on 443.
  6. cert-ctrl stops the temporary TLS listener.

What you configure​

TLS-ALPN-01 verification requires:

  • challenge_device_id
  • challenge_listen (must include port; a bind is recommended)

Choosing the right method​

MethodBest forNeeds DNS API keys?Needs agent + open ports?
CNAME (DNS-01)Most domains, simplest opsNoNo
DNS API (DNS-01)Direct TXT control in your zoneYesNo
HTTP-01No DNS control, port 80 reachableNoYes (80)
TLS-ALPN-01Port 80 blocked, port 443 reachableNoYes (443)

Quick troubleshooting​

  • CNAME: dig CNAME _acme-challenge.example.com should return <public-id>.acme.cjj365.cc.
  • DNS API: check token scope/zone id; allow propagation time.
  • HTTP-01: curl http://example.com/.well-known/acme-challenge/<token> must return exact body (no redirects, no HTML).
  • TLS-ALPN-01: ensure 443 is TCP pass-through to the agent; proxies that terminate TLS may prevent ALPN acme-tls/1.