ACME External Introduction

This section details how to configure the ACME protocol to be managed by Horizon but enrolled on an external ACME endpoint.

The certificate are not enrolled on Horizon but managed thanks to automatic import by third parties such as the Horizon Client.

External ACME enrollment allows to configure:

  • Enrollment (will be performed by the third party);

  • Renewal (will be performed by the third party, depending on the Horizon defined renewal period);

  • Revocation (will be performed by Horizon).

ACME validation modes will be detailed later on. As of today, only http-01 validation is supported.

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 External 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:

As of today, only http-01 validation is supported.

  • http-01: For each requested identifier, the ACME repository 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, the ACME repository 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; (not yet supported)

  • dns-01: For each requested identifier, the ACME repository 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. (not yet supported)

Therefore, validation modes have the following constraints:

  • http-01 and tls-alpn-01:

    • The ACME Repository 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).

Supported third parties

The following third party ACME directories have been tested with horizon-cli and Horizon:

Most third party vendors only support keyCompromise as revocation reason. Revocation with another reason will be rejected or ignored.

  • Let’s encrypt

  • ZeroSSL

  • SSL.com