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
• Helpers for RFC 8737 (tls-alpn-01 challenge)

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 an implementation of acmez.Solver in order to get certificates. How this is done depends on the environment in which you're using this code.

This is not a command line utility either. The goal is to not add more external tooling to already-complex infrastructure: ACME and TLS should be built-in to servers rather than tacked on as an afterthought.

Examples

See the examples folder for tutorials on how to use either package.

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 exceeded Caddy's harsh requirements for large-scale enterprise deployments, lean builds, and simple API. This work finally came to fruition in 2020 as ACMEz.

---

(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 main function is to get a certificate, not manage it. Most users will want to *manage* certificates over the lifetime of a long-running program such as a HTTPS or TLS server, and should use CertMagic instead: https://github.com/caddyserver/certmagic.

Index

• Constants
• func TLSALPN01ChallengeCert(challenge acme.Challenge) (*tls.Certificate, error)
• 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)
• 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 Client

type Client struct {
	*acme.Client

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

	// An optional logger. Default: no logs
	Logger *zap.Logger
}

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 udpated account object. The account's status MUST be "valid" in order to succeed.

As far as SANs go, this method currently only supports DNSNames on the csr.

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.