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 ACME validation 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.

ACME Profile

This section details how to configure an ACME Profile.

Prerequisites

On Horizon side, you need to set up:

How to configure ACME Profile

1. Log in to Horizon Administration Interface.

2. Access ACME Profile from the drawer or card: Protocols > ACME.

3. Click on Add ACME profile.

4. Fill in the mandatory fields.

General

  • Name* (string input):
    Enter a meaningful connector name. It must be unique for each profile. Horizon uses the name to identify the profile. As the name will be part of a URL, it is advisable to use only lower case letters and dashes.

  • Enabled* (boolean):
    Indicates whether the profile is enabled or not. The default value is set to true.

  • PKI Connector (select):
    Select a PKI connector previously created.

  • Max certificate per holder (int):
    If specified, defines the maximum number of active certificates for a given Holder. If the number of active certificates exceeds this parameter, then the oldest certificate(s) above the limit will be automatically revoked.

Validations

  • Validation Methods (select):
    Select the authorized ACME validation method(s) on the considered profile (HTTP-01 and/or TLS-ALPN-01 and/or DNS-01).

  • HTTP_01 validation port (int):
    HTTP port to perform the http-01 validation. The default value is set to 80.

  • TLS-ALPN_01 validation port (int):
    HTTPS port to perform the tls-alpn-01 validation. The default value is set to 443.

  • Challenge verification attempts* (int):
    Specify the number of time Horizon should try to validate an ACME challenge. Th default value is set to 3.

  • Challenge verification retry delay* (finite duration):
    Specify the time duration Horizon should wait between two consecutive validations for the same challenge. The default value is set to 3 seconds.

  • Proxy (select):
    Specify an HTTP proxy to use when performing http-01 or tls-alpn-01 validations.

  • Timeout* (finite duration):
    Specify the time duration Horizon should wait when performing http-01, tls-alpn-01 or dns-01 validations.

Requests management

  • Authorized short name (boolean):
    Specify if using short name is authorized when requesting certificate. If set to yes, one verifiable FQDN must be requested for each specified short name. The default value is set to false.

  • Authorized empty contact (boolean):
    Specify if an ACME account can be registered without specifying a contact email address. Default to false.

  • Default contacts mail (string input multiple):
    Specify a list of default contact email addresses when registering an ACME account with no specified contact email address.

  • Max DNS name (int):
    If specified, enforce the maximum number of requested DNS name(s).

Meta

  • Is required terms of service (boolean):
    Specify if explicitly agreeing to the terms of service is required when registering an ACME account. The default value is set to false.

  • Terms of service (string input):
    Specify an URL identifying the current terms of service.

  • Website (string input):
    Specify an HTTP or HTTPS URL locating a website providing more information about the ACME server.

  • CAA Identities (string input):
    The hostnames that the ACME server recognizes as referring to itself for the purposes of CAA record validation as defined in RFC6844.

Self Permissions

  • Revoke (boolean):
    Specify whether the certificate’s owner is authorized to revoke the certificate with no validation workflow. Set to false by default.

  • Request Revoke (boolean):
    Specify whether the certificate’s owner is authorized to request the revocation of the certificate. Set to false by default.

  • Update (boolean): Specify whether the certificate’s owner is authorized to update the certificate with no validation workflow. The default value is set to false.

  • Request Update (boolean):
    Specify whether the certificate’s owner is authorized to request certificate’s update. The default value is set to false.

You can further configure the profile using the Common configuration for profile and Notification tabs.

5. Click on the save button.

You can edit Edit ACME Profile, duplicate Edit ACME Profile or delete Delete ACME Profile the ACME Profile.

You won’t be able to delete an ACME Profile if it is referenced somewhere else.

ACME client usages

This section details how to use the most common Linux and Windows ACME clients.

Linux ACME clients

This section details how to use the acme.sh and certbot ACME clients.

Overview

Certbot is able to run on any recent UNIX-like operating system equipped with Python 2.7 or 3.4+, while acme.sh can also run on any recent Linux distribution running either bash, dash or sh.

They both fully support the latest ACMEv2 protocol including its main latest feature: wildcard certificates (*.example.com).

Both clients supports different modes for obtaining a certificate and in some cases automatically installing it.

The following tables lists the different modes for each clients:

Modes certbot acme.sh Notes

apache

Y

Y

Obtains and automatically installs a certificate using the running Apache server. (For acme.sh, this mode will only obtain a certificate without installing it)

nginx

Y

Y

Obtains and automatically installs a certificate using the running NGINX server. (For acme.sh, this mode will only obtain a certificate without installing it)

webroot

Y

Y

Obtains a certificate by writing to the webroot directory of an already running web server

standalone

Y

Y

Uses a "standalone" web server managed by Certbot or acme.sh. This mode is useful on system with no web servers or if using the running web server is not desired

DNS

Y

Y

This mode automates obtaining a certificate by modifying a DNS record to prove the control over a domain

tls-alpn

N

Y

Uses a TLS server to validate the control over a domain

Requesting a certificate

Both clients must be started using administrative privileges (sudo), except for acme.sh when using the webroot or DNS modes.

Each client requires only a few parameters to request a certificate.

acme.sh parameters:

Parameter Description

-issue

Obtain or renew a certificate, but does not install it

-w [VALUE]

Path of the server’s webroot folder

-d [VALUE]

The domain(s) to enroll.

certbot parameters:

Parameter Description

certonly

Obtain or renew a certificate, but does not install it

–webroot

Place files in a server’s webroot folder for authentication

-w [VALUE]

Path of the server’s webroot folder

-d [VALUE]

The domain(s) to enroll.

Requesting a certificate for Apache using certbot:

(sudo) certbot run --apache --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: apache.evertrust.fr>

Where:

  • --apache: Enables the Apache mode

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate for nginx using certbot:

(sudo) certbot run --nginx --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: nginx.evertrust.fr>

Where:

  • --nginx: Enables the nginx mode

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate for nginx using acme.sh:

(sudo) acme.sh --issue --nginx --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <DNS name, example: nginx.evertrust.fr>

Where:

  • --issue: Specifies that this is a certificate request

  • --nginx: Enables the nginx mode

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested DNS name (can be specified several times)

Requesting a certificate in standalone mode using certbot:

(sudo) certbot certonly --standalone --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: apache.evertrust.fr>

Where:

  • --standalone: Enables the standalone mode, i.e. certbot will start a local web server to server the response

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate in standalone mode using acme.sh:

(sudo) acme.sh --issue --standalone --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <DNS name, example: apache.evertrust.fr>

Where:

  • --issue: Specifies that this is a certificate request

  • --standalone: Enables the standalone mode, i.e. acme.sh will start a local web server to server the response

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested DNS name (can be specified several times)

Revoking a certificate

Revoking a certificate using certbot:

(sudo) certbot revoke --cert-path <path of the certificate to revoke> --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory>

Where:

  • --cert-path: Specifies the path of the certificate to revoke

  • --server: Horizon ACME profile endpoint

Revoking a certificate using acme.sh:

(sudo) acme.sh --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --revoke -d <DNS name, example: apache.evertrust.fr>

Where:

  • --server: Horizon ACME profile endpoint

  • -d: DNS name of the certificate to revoke

Windows ACME clients

This section details how to use the WinCertes ACME client.

Overview

WinCertes is a simple and efficient CLI-based client made to run on any Windows Server ( > Windows Server 2008 R2 SP1 (64 bits)) and running .NET 4.6.1 or higher.

The client fully supports ACMEv2 including its latest feature, along with the support of wildcard certificates (*.example.com).

WinCertes eases certificate installation and renewal by automatically binding them to the appropriate web site on IIS and by creating a Scheduled Task that will check the expiration date of the certificates and trigger a renewal if necessary.

WinCertes offers the possibility to launch a PowerShell script upon the successful retrieval of a certificate. This feature enables advanced deployment on Exchange or multi-servers for instance.

The client supports two validation modes for validating the identity of the certificate requester:

  1. HTTP challenge validation

    • With the ability to support the running IIS web server or to use an embedded standalone web server for easier configuration.

  2. DNS challenge validation

    • Support for Windows DNS Server

    • Support for acme-dns

Requesting a certificate

To request a certificate using WinCertes, the Windows command line (cmd.exe) must be run as Administrator.

Then WinCertes requires only a few parameters to request a certificate:

Parameter Description

-d [VALUE]

The domain(s) to enroll

-w

toggle the local web server use and sets its ROOT directory (default c:\inetpub\wwwroot).
Activates HTTP validation mode.

-b [VALUE]

The name of the IIS web site to bind the certificate to

-p

Used to make WinCertes create a Scheduled Task to handle certificate renewal

There are many more options to customize the requests to specific needs.

Requesting a certificate for IIS using WinCertes:

(as administrator) wincertes -s <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -w -b <IIS Site Name, example: "Default Web Site"> -p -e <contact email address, example: [email protected]> -d <DNS name, example: iis.evertrust.fr>

Where:

  • -s: Horizon ACME profile endpoint

  • -w: Enables standalone mode, i.e. WinCertes will start a local web server to serve the response

  • -b: IIS Web Site name

  • -p: Registers a scheduled task to enable certificate automated renewal

  • -e: Contact email address