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