ACME protocol implementation in Python

Warnings

• breaking Major architectural shift in version 5.0.0 (aligned with Certbot 5.0.0) removed `acme.crypto_util.SSLSocket`, `acme.crypto_util.probe_sni`, and TLS-ALPN related challenge classes (`acme.challenges.TLSALPN01Response`, `acme.challenges.TLSALPN01`, `acme.standalone.TLSServer`, `acme.standalone.TLSALPN01Server`). This also removed final `pyopenssl` x509 and PKey objects usage within `acme`'s core cryptography, favoring `cryptography` library objects.
  Fix: Migrate any code using these removed classes/functions to their `cryptography` equivalents or alternative ACME challenge methods. Review the `certbot` changelog for detailed migration paths. For TLS-ALPN, re-evaluate if still necessary as its support was deprecated and then removed.
• deprecated The function `acme.crypto_util.make_self_signed_cert` was deprecated in Certbot 5.1.0 and is slated for removal. This indicates a shift away from generating self-signed certificates directly within the `acme` library.
  Fix: Avoid using `acme.crypto_util.make_self_signed_cert`. If self-signed certificates are required, use `cryptography`'s API directly or an external tool.
• breaking Version 2.0.0 (aligned with Certbot 2.0.0) removed support for pre-RFC 8555 ACME versions and related deprecated messaging constructs like `acme.messages.OLD_ERROR_PREFIX`. It also removed the `source_address` argument from `acme.client.ClientNetwork` and several deprecated attributes from `acme.messages.Directory` and `acme.messages.Authorization`.
  Fix: Ensure all ACME interactions adhere to RFC 8555. Update any references to `OLD_ERROR_PREFIX` or the removed `Directory` and `Authorization` attributes. The `source_address` removal requires alternative methods for binding to specific local IPs if needed.
• gotcha The `acme` library's cryptographic requirements are tightly coupled with `certbot`'s and have increased over time. As of Certbot 3.2.0, `acme` requires `cryptography>=43.0.0` and `pyOpenSSL>=25.0.0`.
  Fix: Ensure your environment meets these minimum dependency versions to avoid runtime errors, especially when upgrading `acme` or `certbot`.

Install

• pip install acme Install stable version

Imports

• ClientV2

  from acme import client

• messages

  from acme import messages

• challenges

  from acme import challenges

• josepy

  import josepy as jose

• crypto_util

  from acme import crypto_util

  While developed with Certbot, crypto_util is part of the acme package itself.

Quickstart

This quickstart demonstrates the absolute minimum to initialize the `acme` client and register an account with an ACME server (like Let's Encrypt staging). Note that `acme` is a low-level library; most users will prefer a higher-level client like Certbot for end-to-end certificate management. This example creates an RSA account key, sets up the network client, fetches the directory, and attempts to register a new ACME account, handling potential conflicts if the account already exists. It uses the Let's Encrypt staging environment by default.

import os
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.backends import default_backend

from acme import client
from acme import messages
import josepy as jose

# This is the staging ACME URL for Let's Encrypt
DIRECTORY_URL = os.environ.get('ACME_DIRECTORY_URL', 'https://acme-staging-v02.api.letsencrypt.org/directory')

def run_acme_client():
    # 1. Create a new ACME account private key
    acc_key_pem = rsa.generate_private_key(
        public_exponent=65537, key_size=2048, backend=default_backend()
    )
    acc_key = jose.JWK.from_pem(acc_key_pem.private_bytes(
        encoding=jose.serialization.Encoding.PEM,
        format=jose.serialization.PrivateFormat.PKCS8,
        encryption_algorithm=jose.serialization.NoEncryption()
    ))

    # 2. Initialize the client network
    net = client.ClientNetwork(acc_key, user_agent="my-acme-client/1.0")

    # 3. Get the ACME directory object
    directory = messages.Directory.from_json(net.get(DIRECTORY_URL).json())

    # 4. Create the ACME client
    acme_client = client.ClientV2(directory, net=net)

    # 5. Register a new account (or load existing)
    #   email_contact is optional for staging/testing
    new_reg = messages.NewRegistration(
        terms_of_service_agreed=True, 
        contact=('mailto:test@example.com',) if 'test@example.com' in os.environ.get('ACME_EMAIL', '') else None
    )
    
    try:
        regr = acme_client.new_account(new_reg)
        print(f"Account created/loaded: {regr.uri}")
    except client.errors.ConflictError as e:
        # Account already exists, retrieve it
        print(f"Account already exists, retrieving: {e.uri}")
        regr = acme_client.query_registration(messages.RegistrationResource(uri=e.uri, body=new_reg))

    print("ACME client initialized and account registered.")
    return acme_client, regr

if __name__ == "__main__":
    acme_client_instance, account_resource = run_acme_client()