ACME Protocol¶

What is ACME?¶

ACME (Automatic Certificate Management Environment) is an industry-standard protocol defined in RFC 8555 for automating certificate issuance and renewal. Originally developed for Let's Encrypt, ACME is now widely supported by certificate management tools including Certbot, acme.sh, Caddy, Traefik, and many others.

Zaita provides a private ACME server implementation that allows you to use standard ACME clients to obtain certificates from your organisation's internal PKI. This gives you the automation benefits of ACME while maintaining complete control over your certificate authority and issuance policies.

ACME vs Courier¶

Both ACME and Couriers enable automated certificate provisioning, but they serve different use cases and operate in fundamentally different ways.

Aspect	ACME	Courier
Protocol	Industry standard (RFC 8555)	Zaita proprietary
Client	Any ACME-compatible client	Zaita Courier binary
Key generation	Always client-side	Client-side or platform-side
Authentication	JWS/JWK signatures + optional EAB	Machine Account (federated or credential-based)
Domain authorisation	Pre-configured domain bindings	Policy-based
Challenge-response	Not required (binding-based)	Not applicable
Integration	Native support in many web servers and orchestrators	Script-based via hooks

Use ACME when:

You are deploying certificates to systems that already have ACME client support (Caddy, Traefik, Nginx with Certbot, Kubernetes cert-manager)
You want to use existing ACME tooling and automation workflows
Your team is already familiar with ACME certificate management
You need to integrate with third-party systems that expect an ACME endpoint

Use Couriers when:

You need platform-side key generation with encrypted delivery
You require advanced lifecycle hooks (on-success, on-failure scripts)
You want to route traffic through a Bridge for network-restricted environments
You need detailed audit logging and job status tracking in the platform UI

How It Works¶

The Zaita ACME implementation follows RFC 8555 with one significant difference: domain ownership is verified through pre-configured account bindings rather than challenge-response validation. This eliminates the need for HTTP-01, DNS-01, or TLS-ALPN-01 challenges.

Certificate Issuance Flow¶

┌─────────────────┐                    ┌─────────────────┐
│   ACME Client   │                    │  Zaita Platform │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │  1. GET /directory                   │
         │─────────────────────────────────────>│
         │<─────────────────────────────────────│
         │                                      │
         │  2. POST /new-account (with EAB)     │
         │─────────────────────────────────────>│
         │<─────────────────────────────────────│
         │                                      │
         │  3. POST /new-order                  │
         │─────────────────────────────────────>│
         │      (authorisations auto-validated) │
         │<─────────────────────────────────────│
         │                                      │
         │  4. POST /finalize (with CSR)        │
         │─────────────────────────────────────>│
         │<─────────────────────────────────────│
         │                                      │
         │  5. Poll order until valid           │
         │─────────────────────────────────────>│
         │<─────────────────────────────────────│
         │                                      │
         │  6. GET certificate chain            │
         │─────────────────────────────────────>│
         │<─────────────────────────────────────│
         │                                      │

Directory — The client retrieves the ACME directory to discover endpoint URLs.
Account registration — The client creates an account using External Account Binding (EAB) credentials provided by an administrator.
Order creation — The client submits the desired certificate identifiers (domain names). Authorisations are immediately granted based on the account's domain bindings.
Finalize — The client generates a key pair locally, creates a CSR, and submits it to the platform.
Polling — The client polls the order status while the platform signs the CSR.
Certificate download — Once the order is valid, the client retrieves the full certificate chain.

Client-Side Key Generation¶

ACME clients always generate key pairs locally. The private key never leaves the system where the certificate will be used. This is inherent to the ACME protocol — clients submit a Certificate Signing Request (CSR), and the CA returns a signed certificate.

This is in contrast to Couriers, which can optionally request platform-side key generation when local generation is not practical.

Domain Authorisation¶

Traditional public ACME servers verify domain ownership through challenge-response validation — proving you control a domain by placing a file on a web server (HTTP-01), creating a DNS record (DNS-01), or responding on a TLS port (TLS-ALPN-01).

Zaita's ACME implementation takes a different approach suited to enterprise environments:

An administrator pre-configures domain bindings on each ACME account
Each binding specifies a domain the account is permitted to obtain certificates for
Bindings can allow exact matches, wildcard certificates, or any subdomain
When an order is created, authorisations are granted instantly if the account has appropriate bindings

This model provides several benefits:

No infrastructure changes — No need to expose HTTP endpoints or modify DNS records
Instant issuance — No waiting for challenge validation
Centralised control — Administrators explicitly grant certificate permissions
Auditability — All domain bindings are tracked in the platform

External Account Binding (EAB)¶

To register an ACME account with the Zaita platform, clients must provide External Account Binding credentials. EAB ties the ACME account to a pre-provisioned record in the platform, ensuring only authorised clients can register.

An administrator creates an ACME account in the platform and generates EAB credentials:

Key ID (kid) — A unique identifier for the account
HMAC Key — A shared secret used to sign the account registration request

The ACME client includes these credentials when calling the /new-account endpoint. Once the account is activated, the EAB credentials are marked as used and cannot be reused.

Multi-Tenancy¶

Each tenant in Zaita can have multiple ACME server configurations. Each configuration:

Has its own unique URL namespace (/acme/{server-uuid}/...)
Can use a different intermediate certificate for signing
Has independent validity period and algorithm settings
Maintains its own account space

This allows you to run separate ACME endpoints for different environments (development, staging, production) or different parts of your organisation.

Supported ACME Clients¶

Any RFC 8555-compliant ACME client should work with the Zaita ACME server. Commonly used clients include:

Client	Platform	Notes
Certbot	Linux, macOS, Windows	Official Let's Encrypt client; widely used
acme.sh	Linux, macOS	Pure shell implementation; no dependencies
Caddy	All platforms	Web server with built-in ACME support
Traefik	All platforms	Reverse proxy with native ACME
cert-manager	Kubernetes	Certificate management for Kubernetes
Lego	All platforms	Go-based ACME client library and CLI
win-acme	Windows	Windows-focused with IIS integration

Next Steps¶

Setting Up ACME — Create an ACME server configuration and register your first account
Managing ACME Servers — Configure server settings, validity periods, and algorithms
Managing Accounts — Create accounts, configure domain bindings, and manage EAB credentials
Best Practices — Security recommendations and operational guidance