Client¶

The main ACME client class.

AcmeClient¶

class acmeow.AcmeClient[source]¶

Bases: object

ACME protocol client for automated certificate management.

Implements the ACME protocol (RFC 8555) for obtaining SSL/TLS certificates from ACME-compliant certificate authorities like Let’s Encrypt.

Parameters:

server_url (str) – ACME server directory URL.
email (str) – Account email address.
storage_path (Path | str) – Directory for storing account and certificate data.
proxy_url (str | None) – URL to the proxy. Default None.
verify_ssl (bool) – Whether to verify SSL certificates. Default True.
timeout (int) – Request timeout in seconds. Default 30.
retry_config (RetryConfig | None) – Retry configuration for transient failures.

Example

>>> client = AcmeClient(
...     server_url="https://acme-staging-v02.api.letsencrypt.org/directory",
...     email="admin@example.com",
...     storage_path=Path("./acme_data"),
... )
>>> client.create_account()
>>> order = client.create_order([Identifier.dns("example.com")])
>>> # Complete challenges...
>>> client.finalize_order(KeyType.EC256)
>>> cert, key = client.get_certificate()

Raises:

AcmeConfigurationError – If configuration is invalid.
AcmeNetworkError – If server communication fails.

__init__(server_url, email, storage_path, proxy_url=None, verify_ssl=True, timeout=30, retry_config=None)[source]¶

Parameters:

server_url (str)
email (str)
storage_path (Path | str)
proxy_url (str | None)
verify_ssl (bool)
timeout (int)
retry_config (RetryConfig | None)

Return type:

None

property server_url: str¶: ACME server directory URL.

property email: str¶: Account email address.

property account: Account | None¶: Current account, or None if not created.

property order: Order | None¶: Current order, or None if not created.

set_dns_config(config)[source]¶

Set DNS verification configuration.

When configured, DNS propagation is verified before notifying the ACME server during DNS-01 challenges.

Parameters:: config (DnsConfig) – DNS verification configuration.
Return type:: None

set_external_account_binding(kid, hmac_key)[source]¶

Set External Account Binding (EAB) credentials.

Some ACME servers require EAB to link the ACME account to an existing account in an external system.

Parameters:

kid (str) – Key identifier from the CA.
hmac_key (str) – Base64url-encoded HMAC key from the CA.

Return type:

None

create_account(terms_agreed=True)[source]¶

Create or retrieve an ACME account.

Creates a new account if one doesn’t exist, or retrieves the existing account if already registered.

Parameters:

terms_agreed (bool) – Whether the user agrees to the CA’s terms of service. Must be True to create an account.

Return type:

Account

Returns:

The Account object.

Raises:

AcmeAuthenticationError – If account creation fails.
AcmeConfigurationError – If terms not agreed.

create_order(identifiers, save=True)[source]¶

Create a new certificate order.

Parameters:

identifiers (list[Identifier]) – List of identifiers (domains/IPs) for the certificate.
save (bool) – Whether to save order state for recovery. Default True.

Return type:

Order

Returns:

The Order object.

Raises:

AcmeOrderError – If order creation fails.
AcmeAuthenticationError – If not authenticated.

load_order()[source]¶

Load a previously saved order.

Attempts to load and resume an incomplete order that was saved to disk. Useful for recovering from interruptions.

Return type:: Order | None
Returns:: The Order if found and still valid, None otherwise.

complete_challenges(handler, challenge_type=ChallengeType.DNS, propagation_delay=0, verify_dns=True, dns_timeout=300, parallel=False, max_workers=None)[source]¶

Complete all pending challenges using the provided handler.

This method sets up challenge responses, optionally verifies DNS propagation (for DNS-01), notifies the ACME server, and waits for validation to complete.

Parameters:

handler (ChallengeHandler) – Challenge handler for deploying/cleaning up responses.
challenge_type (ChallengeType) – Type of challenge to complete. Default DNS-01.
propagation_delay (int) – Seconds to wait after setup before notifying server. If handler has propagation_delay attribute, that value is used.
verify_dns (bool) – Whether to verify DNS propagation before notifying server. Only applies to DNS-01 challenges. Default True.
dns_timeout (int) – Maximum time to wait for DNS propagation in seconds. Default 300 (5 minutes).
parallel (bool) – Whether to set up and clean up challenges in parallel. Default False. Server notification and polling remain sequential.
max_workers (int | None) – Maximum number of parallel workers. Default None (auto). Only used when parallel=True.

Raises:

AcmeAuthorizationError – If challenge validation fails.
AcmeOrderError – If no order exists.
AcmeDnsError – If DNS propagation verification fails.

Return type:

None

finalize_order(key_type=KeyType.EC256, common_name=None, csr=None)[source]¶

Finalize the order by submitting a CSR.

Either generates a private key and CSR internally, or uses an externally provided CSR. When using an external CSR, the caller is responsible for managing the corresponding private key.

Parameters:

key_type (KeyType) – Key type for the certificate. Default EC256. Ignored when csr is provided.
common_name (str | None) – Common name override (defaults to first identifier). Ignored when csr is provided.
csr (bytes | str | None) – Externally generated CSR in PEM (str/bytes) or DER (bytes) format. When provided, no private key is generated or saved.

Raises:

AcmeOrderError – If finalization fails.
AcmeConfigurationError – If the provided CSR cannot be parsed.

Return type:

None

get_certificate(preferred_chain=None)[source]¶

Download the issued certificate.

Parameters:: preferred_chain (str | None) – Preferred certificate chain issuer CN. If the server provides multiple chains, select the one whose issuer CN contains this string. Default None (use default chain).
Return type:: tuple[str, str | None]
Returns:: Tuple of (certificate_pem, private_key_pem). The certificate includes the full chain. The private key is None when an external CSR was used during finalization (the caller already holds the key).
Raises:: AcmeCertificateError – If certificate download fails.

deactivate_account()[source]¶

Deactivate the current ACME account.

This permanently deactivates the account. Once deactivated, the account cannot be used for any further operations and cannot be reactivated.

Per RFC 8555 Section 7.3.7.

Raises:: AcmeAuthenticationError – If not authenticated or deactivation fails.
Return type:: None

update_account(email=None)[source]¶

Update the account contact information.

Updates the account’s contact email address with the ACME server.

Per RFC 8555 Section 7.3.2.

Parameters:: email (str | None) – New email address for the account. If None, keeps the current email.
Return type:: Account
Returns:: Updated Account object.
Raises:: AcmeAuthenticationError – If not authenticated or update fails.

key_rollover()[source]¶

Roll over the account key to a new key.

Generates a new account key and updates the ACME server to use it. The old key is replaced and can no longer be used.

Per RFC 8555 Section 7.3.5.

Raises:

AcmeAuthenticationError – If not authenticated or rollover fails.
AcmeNetworkError – If key-change URL is not available.

Return type:

None

revoke_certificate(certificate, reason=None)[source]¶

Revoke a certificate.

Revokes the specified certificate with the ACME server.

Per RFC 8555 Section 7.6.

Parameters:

certificate (str | bytes) – PEM-encoded certificate string or DER-encoded bytes.
reason (RevocationReason | None) – Optional revocation reason code.

Raises:

AcmeAuthenticationError – If not authenticated.
AcmeCertificateError – If revocation fails.
AcmeNetworkError – If revokeCert URL is not available.

Return type:

None

close()[source]¶

Close the client and release resources.

Return type:: None

__enter__()[source]¶

Context manager entry.

Return type:: AcmeClient

__exit__(*args)[source]¶

Context manager exit.

Return type:: None
Parameters:: args (object)