API Reference¶

aioacme.LETS_ENCRYPT_STAGING_DIRECTORY = 'https://acme-staging-v02.api.letsencrypt.org/directory'¶: The Let’s Encrypt staging directory URL.

aioacme.LETS_ENCRYPT_DIRECTORY = 'https://acme-v02.api.letsencrypt.org/directory'¶: The Let’s Encrypt directory URL.

aioacme.ZEROSSL_DIRECTORY = 'https://acme.zerossl.com/v2/DV90'¶: ZeroSSL directory URL.

class aioacme.Client(*, account_key: RSAPrivateKey | EllipticCurvePrivateKey | Ed25519PrivateKey, directory_url: str = LETS_ENCRYPT_STAGING_DIRECTORY, account_uri: str | None = None, external_account_binding: ExternalAccountBinding | None = None, ssl: SSLContext | bool = True)¶

Create new ACME client.

By using this library you agree to the terms of service of the ACME server you are using.

Parameters:

account_key – private key for account.
directory_url – URL to get directory.
account_uri – optional account URI, if not provided, it would be fetched on first request.
ssl – SSL context.

account_key: RSAPrivateKey | EllipticCurvePrivateKey | Ed25519PrivateKey¶

directory_url: Final[str]¶

account_uri: str | None¶

external_account_binding: ExternalAccountBinding | None¶

async get_terms_of_service() → str | None¶

async get_account() → Account¶

Get account info.

Registers new account if it doesn’t exist.

async update_account(*, contact: Sequence[str] | None = None, status: Literal[AccountStatus.deactivated] | None = None) → Account¶

Update account info.

Parameters:

contact – list of contacts.
status – new account status, accepts only AccountStatus.deactivated.

async new_order(identifiers: Sequence[Identifier], *, not_before: datetime | None = None, not_after: datetime | None = None) → Order¶

Create new certificate order.

Parameters:

identifiers – list of identifiers (domains or ips).
not_before – the requested value of the notBefore field in the certificate.
not_after – the requested value of the notAfter field in the certificate.

async get_order(order_uri: str) → Order¶

Get existing order.

Parameters:: order_uri – order URI.

async get_authorization(authorization_uri: str) → Authorization¶

Get existing authorization.

Parameters:: authorization_uri – authorization URI.

get_dns_challenge_domain(domain: str) → str¶

Generate domain for DNS challenge.

Parameters:: domain – domain.

get_dns_challenge_validation(token: str) → str¶

Generate TXT record value for DNS challenge.

Parameters:: token – challenge token.

async answer_challenge(url: str) → Challenge¶

Respond to the challenge.

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.1

Parameters:: url – challenge url.

async deactivate_authorization(uri: str) → Authorization¶

Deactivate authorization.

https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.2

Parameters:: uri – authorization URI.

async finalize_order(finalize: str, csr: CertificateSigningRequest) → Order¶

Finalize the order by submitting the CSR to issue certificate.

Parameters:

finalize – finalize uri.
csr – CSR.

async get_certificate(certificate: str) → bytes¶

Download ready certificate in PEM format.

Parameters:: certificate – certificate URL.

async revoke_certificate(certificate: Certificate, key: RSAPrivateKey | EllipticCurvePrivateKey | Ed25519PrivateKey | None = None, reason: RevocationReason = RevocationReason.unspecified) → None¶

Revoke certificate.

https://datatracker.ietf.org/doc/html/rfc8555#section-7.6

Parameters:

certificate – certificate.
key – private key, if you want to revoke certificate without account key.
reason – reason.

async change_key(new_account_key: RSAPrivateKey | EllipticCurvePrivateKey | Ed25519PrivateKey) → None¶

Change private key for current account. Further requests will be signed with this new key.

https://datatracker.ietf.org/doc/html/rfc8555#section-7.6

Parameters:: new_account_key – new private key.

async close() → None¶

async __aenter__() → Self¶

async __aexit__(exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) → None¶

class aioacme.AccountStatus¶

Bases: Enum

Account status.

valid = 'valid'¶: Account is active.

deactivated = 'deactivated'¶: Client requested deactivation of the account.

revoked = 'revoked'¶: Server revoked the account.

class aioacme.Account¶

Account object.

uri: str¶

status: AccountStatus¶

contact: Sequence[str] | None¶

terms_of_service_agreed: bool | None¶

orders: str | None¶: A URL from which a list of orders submitted by this account can be fetched

initial_ip: str | None¶

created_at: datetime, <CustomEncoder: serialize=None, deserialize=Some(Py(0x72c01de704c0))>] | None¶

class aioacme.IdentifierType¶

Bases: Enum

Identifier type.

dns = 'dns'¶

ip = 'ip'¶

class aioacme.Identifier¶

Identifier object.

value: str¶

type: IdentifierType¶

class aioacme.Error¶

Error object.

type: str¶: A URI reference to a document with more information about the error.

detail: str¶: A short description of the error.

identifier: Identifier | None¶

subproblems: Sequence[Error] | None¶

class aioacme.OrderStatus¶

Bases: Enum

Order status.

pending = 'pending'¶: The order is waiting for the client to satisfy authorizations challenges.

ready = 'ready'¶: All authorizations have been satisfied, the order is ready to finalize.

processing = 'processing'¶: The server is issuing the certificate.

valid = 'valid'¶: The certificate has been issued.

invalid = 'invalid'¶: The order has expired or one of its authorizations has failed.

class aioacme.Order¶

Order object.

uri: str¶: URI

identifiers: Sequence[Identifier]¶: An array of identifier objects that the order pertains to.

authorizations: Sequence[str]¶: For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued, including unexpired authorizations that the client has completed in the past for identifiers specified in the order. The authorizations required are dictated by server policy; there may not be a 1:1 relationship between the order identifiers and the authorizations required. For final orders (in the “valid” or “invalid” state), the authorizations that were completed. Each entry is a URL from which an authorization can be fetched.

status: OrderStatus¶: The status of this order.

expires: datetime | None¶: The timestamp after which the server will consider this order invalid. This field is REQUIRED for objects with “pending” or “valid” in the status field.

finalize: str¶: A URL that a CSR must be POSTed to once all of the order’s authorizations are satisfied to finalize the order. The result of a successful finalization will be the population of the certificate URL for the order.

not_before: datetime | None¶: The requested value of the notBefore field in the certificate.

not_after: datetime | None¶: The requested value of the notAfter field in the certificate.

error: Error | None¶: The error that occurred while processing the order, if any.

certificate: str | None¶: A URL for the certificate that has been issued in response to this order.

class aioacme.ChallengeType¶

Bases: Enum

Challenge type.

dns01 = 'dns-01'¶

dnsaccount01 = 'dns-account-01'¶

http01 = 'http-01'¶

tlsalpn01 = 'tls-alpn-01'¶

class aioacme.ChallengeStatus¶

Bases: Enum

Challenge status.

pending = 'pending'¶: The challenge is waiting to be validated.

processing = 'processing'¶: The challenge is in the process of being validated.

valid = 'valid'¶: The challenge has been successfully validated.

invalid = 'invalid'¶: The challenge has not been successfully validated.

class aioacme.Challenge¶

Challenge object.

type: ChallengeType¶: The type of challenge encoded in the object.

url: str¶: The URL to which a response can be posted.

status: ChallengeStatus¶: The status of this challenge.

validated: datetime | None¶: The time at which the server validated this challenge, encoded in the format specified in [RFC3339]. This field is REQUIRED if the “status” field is “valid”.

error: Error | None¶: Error that occurred while the server was validating the challenge, if any. Multiple errors can be indicated by using subproblems Section 6.7.1. A challenge object with an error MUST have status equal to “invalid”.

token: str¶: A random value that uniquely identifies the challenge. This value MUST have at least 128 bits of entropy. It MUST NOT contain any characters outside the base64url alphabet and MUST NOT include base64 padding characters (“=”).

class aioacme.AuthorizationStatus¶

Bases: Enum

Authorization status.

pending = 'pending'¶: The authorization is waiting to be validated.

valid = 'valid'¶: The authorization has been successfully validated.

invalid = 'invalid'¶: The authorization has not been successfully validated.

expired = 'expired'¶: The authorization has expired.

deactivated = 'deactivated'¶: The client has deactivated the authorization.

class aioacme.Authorization¶

Authorization object.

uri: str¶: URI

identifier: Identifier¶: The identifier that the account is authorized to represent.

status: AuthorizationStatus¶: The status of this authorization.

expires: datetime | None¶: The timestamp after which the server will consider this authorization invalid, encoded in the format specified in [RFC3339]. This field is REQUIRED for objects with “valid” in the “status” field.

challenges: Sequence[Challenge]¶: For pending authorizations, the challenges that the client can fulfill in order to prove possession of the identifier. For valid authorizations, the challenge that was validated. For invalid authorizations, the challenge that was attempted and failed. Each array entry is an object with parameters required to validate the challenge. A client should attempt to fulfill one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid.

wildcard: bool¶: This field MUST be present and true for authorizations created as a result of a newOrder request containing a DNS identifier with a value that was a wildcard domain name. For other authorizations, it MUST be absent.

class aioacme.RevocationReason¶

Bases: Enum

Reason to revoke certificate.

unspecified = 0¶

key_compromise = 1¶

ca_compromise = 2¶

affiliation_changed = 3¶

superseded = 4¶

cessation_of_operation = 5¶

certificate_hold = 6¶

remove_from_crl = 8¶

privilege_withdrawn = 9¶

aa_compromise = 10¶

class aioacme.ExternalAccountBinding¶

External Account Binding credentials.

kid: str¶: Key ID.

mac_key: bytes | str¶: MAC key (str if it’s base64 encoded).

exception aioacme.AcmeError¶

error: Error¶

exception aioacme.RateLimitedError¶

Bases: AcmeError

Raised on a urn:ietf:params:acme:error:rateLimited error.

See RFC 8555 Section 6.6.

retry_after: datetime | None¶