ACME Introduction

This section details how to configure and consume the ACME protocol.

Horizon implements an ACME service respecting the RFC 8555 and more specifically the following lifecycle workflows:

  • Enrollment;

  • Renewal (which is equivalent to an enrollment);

  • Revocation.

The ACME module in Horizon

The ACME configuration is organized around four types of objects, available from the drawer or card Protocols  ACME in the Horizon Administration Interface:

Object

Role

ACME Profile

Defines how Horizon serves the ACME protocol: the PKI connector used for issuance, the authorized validation methods and the constraints applied to the requests.

EAB Policy

Defines a named, reusable set of constraints applied to the attached EAB accounts.

EAB Account

Credentials (MAC Key ID and MAC Key) handed over to ACME clients, and required to register an ACME account when the profile’s Require External Account Binding (EAB) option is enabled.

ACME Account

Accounts registered by ACME clients on the ACME profiles, which can be audited and managed from the Administration Interface.

The ACME protocol exchanges are carried by ACME accounts, registered by ACME clients on an ACME profile as described in RFC 8555, section 7.3. When the profile’s Require External Account Binding (EAB) option is enabled, the registration must be bound to an EAB account, as described in RFC 8555, section 7.3.4: binding an ACME account to an EAB allows Horizon to restrict who can create ACME accounts, and to enforce additional constraints on the requests carried by the bound accounts.

Managing certificate lifecycle through the ACME protocol involves up to three components:

  • Horizon as the ACME endpoint;

  • An asset executing an ACME client or directly integrating the ACME protocol;

  • When the ACME validation method is ' dns-01 ', DNS server(s).

ACME validation modes will be detailed later on.

The protocol paradigm can be described as follows: 'if the asset can prove it has authority on the DNS names (called identifiers in ACME) it is requesting for, the certificate should be automatically enrolled / renewed', which is basically equivalent to a Domain Validation.

The following schema is a simplified workflow of an ACME enrollment: ACME Enrollment Diagram The protocol is based on the notion of challenge and offers three validation modes to actually verify challenges and prove that the asset owns authority on the requested DNS name(s), i.e. ACME identifiers:

  • http-01: For each requested identifier, Horizon will validate the challenge by connecting back in HTTP on the configured http-01 validation port (TCP/80 by default) and retrieve the response to the challenge;

  • tls-alpn-01: For each requested identifier, Horizon will validate the challenge by connecting back in HTTPS on the configured tls-alpn-01 validation port (TCP/443 by default) and extract the response to the challenge from an ALPN extension in the asset / client HTTPS response;

  • dns-01: For each requested identifier, Horizon will validate the challenge through a DNS request and look for a specific TXT entry containing the response corresponding to the challenge for the considered identifier.

Therefore, validation modes have the following constraints:

  • http-01 and tls-alpn-01:

    • Horizon must be able to access the asset on the validation port;

    • The validation port must be available and opened on the asset;

  • dns-01: the ACME client must be configured with DNS credentials owning the permission to create TXT records on the requested domain(s).

For http-01 and tls_alpn-01 validation modes, it is possible to configure an HTTP proxy to proxify the ACME validation tentative(s). Using an HTTP proxy is useful when http-01 and/or tls-alpn-01 validation need to be performed on asset(s) hosted within a DMZ where incoming network streams must be limited. In this scenario, an HTTP proxy is configured to relay ACME validations coming from the Horizon nodes within the DMZ and a unique incoming stream needs to be open to allow communication from Horizon node to the HTTP proxy.

The choice of the validation mode to use mainly depends on the architecture. Here are the EverTrust recommendations:

  • If the requester is not the asset, prefer the dns-01 validation mode;

  • If the requester is the asset:

    • If the asset is reachable from Horizon nodes, prefer the http-01;

    • If the asset is not reachable from Horizon nodes, prefer the dns-01;

  • tls-alpn-01 is the most complicated validation mode to implement and therefore should only be used when no other validation mode is an option.

Qualified ACME clients

EverTrust qualifies the following ACME clients for any release of the Horizon product:

If an ACME client is not listed above, it does not necessarily mean that the client will not work with Horizon, only that the client is not included in the list of clients tested in Horizon’s continuous integration test cases.