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.

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:

  • Linux ACME clients:

  • Windows ACME client:

    • lego

    • WinCertes: this open source client is developed and maintained by EverTrust, therefore officially supported

    • Horizon CLI

  • Kubernetes: cert-manager

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.