acmez

README

acmez - ACME client library for Go

ACMEz ("ack-measy" or "acme-zee", whichever you prefer) is a fully-compliant RFC 8555 (ACME) implementation in pure Go. It is lightweight, has an elegant Go API, and its retry logic is highly robust against external errors. ACMEz is suitable for large-scale enterprise deployments.

NOTE: This module is for getting certificates, not managing certificates. Most users probably want certificate management (keeping certificates renewed) rather than to interface directly with ACME. Developers who want to use certificates in their long-running Go programs should use CertMagic instead; or, if their program is not written in Go, Caddy can be used to manage certificates (even without running an HTTP or TLS server).

This module has two primary packages:

• acmez is a high-level wrapper for getting certificates. It implements the ACME order flow described in RFC 8555 including challenge solving using pluggable solvers.
• acme is a low-level RFC 8555 implementation that provides the fundamental ACME operations, mainly useful if you have advanced or niche requirements.

In other words, the acmez package is porcelain while the acme package is plumbing (to use git's terminology).

Features

• Simple, elegant Go API
• Thoroughly documented with spec citations
• Robust to external errors
• Structured error values ("problems" as defined in RFC 7807)
• Smart retries (resilient against network and server hiccups)
• Challenge plasticity (randomized challenges, and will retry others if one fails)
• Context cancellation (suitable for high-frequency config changes or reloads)
• Highly flexible and customizable
• External Account Binding (EAB) support
• Tested with multiple ACME CAs (more than just Let's Encrypt)
• Supports niche aspects of RFC 8555 (such as alt cert chains and account key rollover)
• Efficient solving of large SAN lists (e.g. for slow DNS record propagation)
• Utility functions for solving challenges
  • Device attestation challenges
  • RFC 8737 (tls-alpn-01 challenge)

Examples

See the examples folder for tutorials on how to use either package. Most users should follow the porcelain guide to get started.

Challenge solvers

The acmez package is "bring-your-own-solver." It provides helper utilities for http-01, dns-01, and tls-alpn-01 challenges, but does not actually solve them for you. You must write or use an implementation of acmez.Solver in order to get certificates. How this is done depends on your environment/situation.

However, you can find a general-purpose dns-01 solver in CertMagic, which uses libdns packages to integrate with numerous DNS providers. You can use it like this:

// minimal example using Cloudflare
solver := &certmagic.DNS01Solver{
	DNSProvider: &cloudflare.Provider{APIToken: "topsecret"},
}
client := acmez.Client{
	ChallengeSolvers: map[string]acmez.Solver{
		acme.ChallengeTypeDNS01: solver,
	},
	// ...
}

If you're implementing a tls-alpn-01 solver, the acmez package can help. It has the constant ACMETLS1Protocol which you can use to identify challenge handshakes by inspecting the ClientHello's ALPN extension. Simply complete the handshake using a certificate from the acmez.TLSALPN01ChallengeCert() function to solve the challenge.

History

In 2014, the ISRG was finishing the development of its automated CA infrastructure: the first of its kind to become publicly-trusted, under the name Let's Encrypt, which used a young protocol called ACME to automate domain validation and certificate issuance.

Meanwhile, a project called Caddy was being developed which would be the first and only web server to use HTTPS automatically and by default. To make that possible, another project called lego was commissioned by the Caddy project to become of the first-ever ACME client libraries, and the first client written in Go. It was made by Sebastian Erhart (xenolf), and on day 1 of Let's Encrypt's public beta, Caddy used lego to obtain its first certificate automatically at startup, making Caddy and lego the first-ever integrated ACME client.

Since then, Caddy has seen use in production longer than any other ACME client integration, and is well-known for being one of the most robust and reliable HTTPS implementations available today.

A few years later, Caddy's novel auto-HTTPS logic was extracted into a library called CertMagic to be usable by any Go program. Caddy would continue to use CertMagic, which implemented the certificate automation and management logic on top of the low-level certificate obtain logic that lego provided.

Soon thereafter, the lego project shifted maintainership and the goals and vision of the project diverged from those of Caddy's use case of managing tens of thousands of certificates per instance. Eventually, the original Caddy author announced work on a new ACME client library in Go that satisfied Caddy's harsh requirements for large-scale enterprise deployments, lean builds, and simple API. This work exceeded expectations and finally came to fruition in 2020 as ACMEz. It is much more lightweight with zero core dependencies, has a simple and elegant code base, and is thoroughly documented and easy to build upon.

---

(c) 2020 Matthew Holt

Documentation

Overview

Package acmez implements the higher-level flow of the ACME specification, RFC 8555: https://tools.ietf.org/html/rfc8555, specifically the sequence in Section 7.1 (page 21).

It makes it easy to obtain certificates with various challenge types using pluggable challenge solvers, and provides some handy utilities for implementing solvers and using the certificates. It DOES NOT manage certificates, it only gets them from the ACME server.

NOTE: This package's primary purpose is to get a certificate, not manage it. Most users actually want to *manage* certificates over the lifetime of long-running programs such as HTTPS or TLS servers, and should use CertMagic instead: https://github.com/caddyserver/certmagic.

COMPATIBILITY: Exported identifiers that are related to draft specifications are subject to change or removal without a major version bump.

Index

• Constants
• func TLSALPN01ChallengeCert(challenge acme.Challenge) (*tls.Certificate, error)
• type CSRSource
• type Client
  • func (c *Client) ObtainCertificate(ctx context.Context, account acme.Account, certPrivateKey crypto.Signer, ...) ([]acme.Certificate, error)
  • func (c *Client) ObtainCertificateUsingCSR(ctx context.Context, account acme.Account, csr *x509.CertificateRequest) ([]acme.Certificate, error)
  • func (c *Client) ObtainCertificateUsingCSRSource(ctx context.Context, account acme.Account, identifiers []acme.Identifier, ...) ([]acme.Certificate, error)
• type Payloader
• type Solver
• type Waiter

Constants

const ACMETLS1Protocol = "acme-tls/1"

ACMETLS1Protocol is the ALPN value for the TLS-ALPN challenge handshake. See RFC 8737 §6.2.

Functions

func TLSALPN01ChallengeCert

func TLSALPN01ChallengeCert(challenge acme.Challenge) (*tls.Certificate, error)

TLSALPN01ChallengeCert creates a certificate that can be used for handshakes while solving the tls-alpn-01 challenge. See RFC 8737 §3.

Types

type CSRSource

type CSRSource interface {
	CSR(context.Context) (*x509.CertificateRequest, error)
}

CSRSource is an interface that provides users of this package the ability to provide a CSR as part of the ACME flow. This allows the final CSR to be provided just before the Order is finalized.

type Client

type Client struct {
	*acme.Client

	// Map of solvers keyed by name of the challenge type.
	ChallengeSolvers map[string]Solver
}

Client is a high-level API for ACME operations. It wraps a lower-level ACME client with useful functions to make common flows easier, especially for the issuance of certificates.

func (*Client) ObtainCertificate

func (c *Client) ObtainCertificate(ctx context.Context, account acme.Account, certPrivateKey crypto.Signer, sans []string) ([]acme.Certificate, error)

ObtainCertificate is the same as ObtainCertificateUsingCSR, except it is a slight wrapper that generates the CSR for you. Doing so requires the private key you will be using for the certificate (different from the account private key). It obtains a certificate for the given SANs (domain names) using the provided account.

func (*Client) ObtainCertificateUsingCSR

func (c *Client) ObtainCertificateUsingCSR(ctx context.Context, account acme.Account, csr *x509.CertificateRequest) ([]acme.Certificate, error)

ObtainCertificateUsingCSR obtains all resulting certificate chains using the given CSR, which must be completely and properly filled out (particularly its DNSNames and Raw fields - this usually involves creating a template CSR, then calling x509.CreateCertificateRequest, then x509.ParseCertificateRequest on the output). The Subject CommonName is NOT considered.

It implements every single part of the ACME flow described in RFC 8555 §7.1 with the exception of "Create account" because this method signature does not have a way to return the updated account object. The account's status MUST be "valid" in order to succeed.

As far as SANs go, this method currently only supports DNSNames, IPAddresses, Permanent Identifiers and Hardware Module Names on the CSR.

func (*Client) ObtainCertificateUsingCSRSource

func (c *Client) ObtainCertificateUsingCSRSource(ctx context.Context, account acme.Account, identifiers []acme.Identifier, source CSRSource) ([]acme.Certificate, error)

ObtainCertificateUsingCSRSource obtains all resulting certificate chains using the given ACME Identifiers and the CSRSource. The CSRSource can be used to create and sign a final CSR to be submitted to the ACME server just before finalization. The CSR must be completely and properly filled out, because the provided ACME Identifiers will be validated against the Identifiers that can be extracted from the CSR. This package currently supports the DNS, IP address, Permanent Identifier and Hardware Module Name identifiers. The Subject CommonName is NOT considered.

The CSR's Raw field containing the DER encoded signed certificate request must also be set. This usually involves creating a template CSR, then calling x509.CreateCertificateRequest, then x509.ParseCertificateRequest on the output.

The method implements every single part of the ACME flow described in RFC 8555 §7.1 with the exception of "Create account" because this method signature does not have a way to return the updated account object. The account's status MUST be "valid" in order to succeed.

type Payloader

type Payloader interface {
	Payload(context.Context, acme.Challenge) (any, error)
}

Payloader is an optional interface for Solvers to implement. Its purpose is to return the payload sent to the CA when responding to a challenge. This interface is applicable when responding to "device-attest-01" challenges

If implemented, it will be called after Present() and if a Waiter is implemented it will be called after Wait(), just before the challenge is initiated with the server.

Implementations MUST honor context cancellation.

type Solver

type Solver interface {
	// Present is called just before a challenge is initiated.
	// The implementation MUST prepare anything that is necessary
	// for completing the challenge; for example, provisioning
	// an HTTP resource, TLS certificate, or a DNS record.
	//
	// It MUST return quickly. If presenting the challenge token
	// will take time, then the implementation MUST do the
	// minimum amount of work required in this method, and
	// SHOULD additionally implement the Waiter interface.
	// For example, a DNS challenge solver might make a quick
	// HTTP request to a provider's API to create a new DNS
	// record, but it might be several minutes or hours before
	// the DNS record propagates. The API request should be
	// done in Present(), and waiting for propagation should
	// be done in Wait().
	Present(context.Context, acme.Challenge) error

	// CleanUp is called after a challenge is finished, whether
	// successful or not. It MUST free/remove any resources it
	// allocated/created during Present. It SHOULD NOT require
	// that Present ran successfully. It MUST return quickly.
	CleanUp(context.Context, acme.Challenge) error
}

Solver is a type that can solve ACME challenges. All implementations MUST honor context cancellation.

type Waiter

type Waiter interface {
	Wait(context.Context, acme.Challenge) error
}

Waiter is an optional interface for Solvers to implement. Its primary purpose is to help ensure the challenge can be solved before the server gives up trying to verify the challenge.

If implemented, it will be called after Present() but just before the challenge is initiated with the server. It blocks until the challenge is ready to be solved. (For example, waiting on a DNS record to propagate.) This allows challenges to succeed that would normally fail because they take too long to set up (i.e. the ACME server would give up polling DNS or the client would timeout its polling). By separating Present() from Wait(), it allows the slow part of all solvers to begin up front, rather than waiting on each solver one at a time.

It MUST NOT do anything exclusive of Present() that is required for the challenge to succeed. In other words, if Present() is called but Wait() is not, then the challenge should still be able to succeed assuming infinite time.

Implementations MUST honor context cancellation.