acme-client

The http-01 challenge is the simplest ACME challenge type to implement and is recommended as a default choice. It works by proving domain ownership through a specific file served over HTTP.

How it works

1. The ACME authority provides a token.
2. You must serve a file at the following URL: http://$YOUR_DOMAIN/.well-known/acme-challenge/$TOKEN.
3. The file content must consist of the token and a thumbprint of your account key.
4. The ACME authority verifies the challenge by sending HTTP requests to that URL.

Note on redirects: HTTP redirects are followed during verification. While the ACME spec focuses on HTTP, Let's Encrypt allows redirecting to HTTPS.

When to use http-01

• Use it when: You want the simplest implementation and have access to port 80.
• Avoid it when:
  • You need to issue wildcard certificates (which require DNS-based challenges).
  • Port 80 is unavailable on your server.
  • You have multiple web servers that cannot all respond with the correct token simultaneously.

The dns-01 challenge is used to prove ownership of a domain by serving a specific payload within a TXT DNS record.

Key characteristics:

• Wildcard Support: It is the only challenge type capable of issuing ACME wildcard certificates.
• Mechanism: The client generates a base64url encoded SHA256 digest (using a token from the ACME authority and your account key thumbprint). This payload must be placed in a TXT record at the DNS name _acme-challenge.$YOUR_DOMAIN.
• Delegation: The ACME authority follows CNAME and NS records, allowing you to delegate the challenge response to a different DNS zone.
• Requirements: Your DNS provider must offer an API that allows for the automated addition and removal of TXT records.

Trade-offs:

• Pros: Enables wildcard certificates; works even if ports 80 and 443 are unavailable.
• Cons: Slower than other challenge types due to DNS propagation delays; requires DNS API automation.

The tls-alpn-01 challenge type requires proving domain ownership by serving a specially crafted certificate over HTTPS using the acme-tls/1 ALPN protocol.

Because this challenge requires responding with self-signed certificates containing a specific id-pe-acmeIdentifier extension, it cannot be implemented purely in Node.js. You must use a proxy (such as Nginx or HAProxy) in front of your Node.js service to inspect the SSL ALPN protocol and route traffic accordingly.

Architecture Pattern: To avoid serving self-signed certificates to actual users, you must split HTTPS traffic into two distinct Node.js backends:

1. ALPN Responder: A backend that only serves the challenge response certificates.
2. HTTPS Server: A backend that serves the valid certificates retrieved from the ACME provider to end-users.

Traffic Flow:

• If the ALPN protocol is acme-tls/1 $\rightarrow$ Route to the Node.js ALPN responder.
• Otherwise $\rightarrow$ Route to the standard Node.js HTTPS server.

Nginx or HAProxy (0.0.0.0:443)
    *inspect requests SSL ALPN protocol*
        If ALPN == acme-tls/1
            -> Node.js ALPN responder (127.0.0.1:4444)
        Else
            -> Node.js HTTPS server (127.0.0.1:4443)

The AcmeClient class is the primary interface for interacting with an ACME server. It provides methods to manage account lifecycle (creation, updates, key rotation), retrieve server information (Terms of Service, Account URL), and manage certificate orders (creation, retrieval, and finalization).

Core Methods

Account Management

• getTermsOfServiceUrl(): Returns a Promise<(string|null)> containing the URL to the ACME server's Terms of Service.
• getAccountUrl(): Returns the string URL of the current ACME account.
• createAccount([data]): Returns a Promise<object> to create a new account. Accepts optional data.
• updateAccount([data]): Returns a Promise<object> to update an existing account. Accepts optional data.
• updateAccountKey(newAccountKey, [data]): Returns a Promise<object> to rotate the account key. Takes the newAccountKey and optional data.

Order Management

• createOrder(data): Returns a Promise<object> to initiate a new certificate order. Requires data defining the order requirements.
• getOrder(order): Returns a Promise<object> to retrieve details for a specific order.
• finalizeOrder(order, csr): Returns a Promise<object> to finalize an order using a Certificate Signing Request (csr).

// Example conceptual usage of AcmeClient methods
const client = new AcmeClient(opts);

// Account operations
const tosUrl = await client.getTermsOfServiceUrl();
const account = await client.createAccount();

// Order operations
const order = await client.createOrder(orderData);
const finalizedOrder = await client.finalizeOrder(order, csr);