ACME integration with Certificate Manager

Automatic Certificate Management Environment, usually referred to as ACME, is a simple client/server protocol based on HTTP. The client represents the applicant for a certificate (e.g., a web server operator), and the server (Trust Protection Foundation) represents the CA. ACME enables Certificate Manager to verify that the applicant owns some number of domains, and then enables the applicant to request certificates for those domains.

IMPORTANT  Palo Alto Networks's implementation of the ACME protocol was designed and tested for use with the following clients: certbot, win-acme, and acme.sh. If you're using a different client, you might encounter limitations. For example, your alternate ACME client might use portions of the ACME protocol that aren't supported by Palo Alto Networks's integration with the certbot and win-acme clients.

To learn more about certbot, visit https://datatracker.ietf.org/wg/acme/about/.

To learn more about win-acme, visit https://www.win-acme.com/manual/getting-started.

To learn more about acme.sh, visit https://github.com/acmesh-official/acme.sh.

About the ACME protocol

The Automatic Certificate Management Environment (ACME) protocol is a communications protocol for automating interactions between certificate authorities and their users' web servers, allowing the automated deployment of public key infrastructure at very low cost. It was designed by the Internet Security Research Group (ISRG).

Palo Alto Networks Trust Protection Foundation supports some features from the ACME v2 protocol.

NOTE  Starting in 26.2, the ACME Server no longer supports ACME v1. ACME v1 is an old draft version of the ACME protocol. The ACME Server now supports only ACME v2 (RFC 8555), which all current ACME clients use, such as certbot and win-acme. After you upgrade, ACME clients that use the ACME v1 endpoints (/vacme/v1/) can't request or renew certificates. Before you upgrade, check your ACME clients. If a client uses ACME v1, update it or set it up to use the ACME v2 directory URL.ACME v1 protocol .

ACME v2 is not backwards-compatible with ACME v1. The version 2 specification details support for wildcard domains, allowing for multiple subdomains to be covered by a single TLS certificate (support for this feature is slated for a future Palo Alto Networks Trust Protection Foundation release).

To learn more, visit https://letsencrypt.org/docs/acme-protocol-updates/ and https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment.

About Palo Alto Networks Support for ACME v2

In this release of Palo Alto Networks Trust Protection Foundation, we support the following:

  • http-01 and dns-01 challenges

  • DNS TXT verification of domain control

  • Wildcard certificate issuance

  • All required (MUST / REQUIRED / SHALL) components of the ACME v2 specification (RFC8555)

  • Certificate enrollment with multiple domains

  • Elliptic curve key algorithm for account or certificate

  • Account deactivation

  • Certificate revocation through ACME.

This release does not support:

  • KeyChange endpoint

About using the win-acme client

A windows-native ACMEv2 client that is supported by Certificate Manager is win-acme, which is a client that is simple, making it easy to start with, but it is also powerful enough for almost any use case. Lear more about it at https://www.win-acme.com.

You can use the win-acme client, but please be aware of the following limitations:

  • Your Trust Protection Foundation cluster must use a supported Windows operating system. For win-acme, you must be using Windows Server 2016 or later.

  • FIPS compliance should NOT be enabled on the Palo Alto Networks server.

  • In the win-acme settings JSON file, the DefaultBaseUri field should be set to the Certificate Manager ACME server using this pattern:
    https://<server_url>/vacme/v2/<tpp_sub_folder>/.

  • The win-acme client only supports revocation for the reason Unspecified.

  • The win-acme client sends revocation requests to Certificate Manager using the account key.

About using the acme.sh client

Acme.sh is a fully compliant ACME v2 client that supports ECDSA and wildcard certs, making it a powerful tool for managing certificates. See github.com/acmesh-official/acme.sh.

Acme.sh supports both HTTP-01 and DNS-01 validation types. Here are examples from how to use them:

# Issue a certificate using HTTP-01 validation
acme.sh --issue --webroot /var/www/html/ -d www.test.org

# Issue a certificate using DNS-01 validation
acme.sh --issue --dns dns_nsupdate --dnssleep 3 -d *.test.org

For the most accurate and current information, see the official documentation at github.com/acmesh-official/acme.sh.