Client

ACME client API.

class acme.client.ClientV2(directory: Directory, net: ClientNetwork)[source]

ACME client for a v2 API.

Variables:
new_account(new_account: NewRegistration) → RegistrationResource[source]

Register.

Parameters:

new_account (.NewRegistration)

Raises:

.ConflictError – in case the account already exists

Returns:

Registration Resource.

Return type:

RegistrationResource

query_registration(regr: RegistrationResource) → RegistrationResource[source]

Query server about registration.

Parameters:

regr (messages.RegistrationResource) – Existing Registration Resource.

update_registration(regr: RegistrationResource, update: Registration | None = None) → RegistrationResource[source]

Update registration.

Parameters:
Returns:

Updated Registration Resource.

Return type:

RegistrationResource

new_order(csr_pem: bytes, profile: str | None = None) → OrderResource[source]

Request a new Order object from the server.

Parameters:

csr_pem (bytes) – A CSR in PEM format.

Returns:

The newly created order.

Return type:

OrderResource

poll(authzr: AuthorizationResource) → tuple[AuthorizationResource, Response][source]

Poll Authorization Resource for status.

Parameters:

authzr (AuthorizationResource) – Authorization Resource

Returns:

Updated Authorization Resource and HTTP response.

Return type:

(AuthorizationResource, requests.Response)

poll_and_finalize(orderr: OrderResource, deadline: datetime | None = None) → OrderResource[source]

Poll authorizations and finalize the order.

If no deadline is provided, this method will timeout after 90 seconds.

Parameters:

  • orderr (messages.OrderResource) – order to finalize

  • deadline (datetime.datetime) – when to stop polling and timeout

Returns:

finalized order

Return type:

messages.OrderResource

poll_authorizations(orderr: OrderResource, deadline: datetime) → OrderResource[source]

Poll Order Resource for status.

begin_finalization(orderr: OrderResource) → OrderResource[source]

Start the process of finalizing an order.

Parameters:

  • orderr (messages.OrderResource) – order to finalize

  • deadline (datetime.datetime) – when to stop polling and timeout

Returns:

updated order

Return type:

messages.OrderResource

Raises:

.messages.Error – If server indicates order is not yet in ready state, it will return a 403 (Forbidden) error with a problem document/error code of type “orderNotReady”

poll_finalization(orderr: OrderResource, deadline: datetime, fetch_alternative_chains: bool = False) → OrderResource[source]

Poll an order that has been finalized for its status. If it becomes valid, obtain the certificate.

If a finalization request previously returned orderNotReady, poll until ready, send a new finalization request, and continue polling until valid as above.

Returns:

finalized order (with certificate)

Return type:

messages.OrderResource

finalize_order(orderr: OrderResource, deadline: datetime, fetch_alternative_chains: bool = False) → OrderResource[source]

Finalize an order and obtain a certificate.

Parameters:

  • orderr (messages.OrderResource) – order to finalize

  • deadline (datetime.datetime) – when to stop polling and timeout

  • fetch_alternative_chains (bool) – whether to also fetch alternative certificate chains

Returns:

finalized order

Return type:

messages.OrderResource

renewal_time(cert_pem: bytes) → tuple[datetime | None, datetime][source]

Return an appropriate time to attempt renewal of the certificate, and the next time to ask the ACME server for renewal info.

If the certificate has already expired, renewal info isn’t checked. Instead, the certificate’s notAfter time is returned and the certificate should be immediately renewed.

If the ACME directory has a “renewalInfo” field, the response will be based on a fetch of the renewal info resource for the certificate (https://www.ietf.org/archive/id/draft-ietf-acme-ari-08.html).

If there is no “renewalInfo” field, this function will return a tuple of None, and the next time to ask the ACME server for renewal info.

This function may make other network calls in the future (e.g., OCSP or CRL).

Parameters:

cert_pem (bytes) – cert as pem file

Returns:

Tuple of time to attempt renewal, next time to ask for renewal info

Raises:

errors.ARIError – If an error occurs fetching ARI from the server. Explicit exception chaining is used so the original error can be accessed through the __cause__ attribute on the ARIError if desired.

revoke(cert: Certificate, rsn: int) → None[source]

Revoke certificate.

Parameters:

  • cert (x509.Certificate) – x509.Certificate

  • rsn (int) – Reason code for certificate revocation.

Raises:

.ClientError – If revocation is unsuccessful.

external_account_required() → bool[source]

Checks if ACME server requires External Account Binding authentication.

classmethod get_directory(url: str, net: ClientNetwork) → Directory[source]

Retrieves the ACME directory (RFC 8555 section 7.1.1) from the ACME server. :param str url: the URL where the ACME directory is available :param ClientNetwork net: the ClientNetwork to use to make the request

Returns:

the ACME directory object

Return type:

messages.Directory

deactivate_registration(regr: RegistrationResource) → RegistrationResource[source]

Deactivate registration.

Parameters:

regr (messages.RegistrationResource) – The Registration Resource to be deactivated.

Returns:

The Registration resource that was deactivated.

Return type:

RegistrationResource

deactivate_authorization(authzr: AuthorizationResource) → AuthorizationResource[source]

Deactivate authorization.

Parameters:

authzr (messages.AuthorizationResource) – The Authorization resource to be deactivated.

Returns:

The Authorization resource that was deactivated.

Return type:

AuthorizationResource

answer_challenge(challb: ChallengeBody, response: ChallengeResponse) → ChallengeResource[source]

Answer challenge.

Parameters:
Returns:

Challenge Resource with updated body.

Return type:

ChallengeResource

Raises:

.UnexpectedUpdate –

classmethod retry_after(response: Response, default: int) → datetime[source]

Compute next poll time based on response Retry-After header.

Handles integers and various datestring formats per https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.37

Parameters:

  • response (requests.Response) – Response from poll.

  • default (int) – Default value (in seconds), used when Retry-After header is not present or invalid.

Returns:

Time point when next poll should be performed.

Return type:

datetime.datetime

class acme.client.ClientNetwork(key: JWK | None = None, account: RegistrationResource | None = None, alg: JWASignature = RS256, verify_ssl: bool = True, user_agent: str = 'acme-python', timeout: int = 45)[source]

Wrapper around requests that signs POSTs for authentication.

Also adds user agent, and handles Content-Type.

REPLAY_NONCE_HEADER = 'Replay-Nonce'

Initialize.

Parameters:

  • key (josepy.JWK) – Account private key. Required to use .post().

  • account (messages.RegistrationResource) – Account object. Required if you are planning to use .post() for anything other than creating a new account; may be set later after registering.

  • alg (josepy.JWASignature) – Algorithm to use in signing JWS.

  • verify_ssl (bool) – Whether to verify certificates on SSL connections.

  • user_agent (str) – String to send as User-Agent header.

  • timeout (int) – Timeout for requests.

head(*args: Any, **kwargs: Any) → Response[source]

Send HEAD request without checking the response.

Note, that _check_response is not called, as it is expected that status code other than successfully 2xx will be returned, or messages2.Error will be raised by the server.

get(url: str, content_type: str = 'application/json', **kwargs: Any) → Response[source]

Send GET request and check response.

post(*args: Any, **kwargs: Any) → Response[source]

POST object wrapped in JWS and check response.

If the server responded with a badNonce error, the request will be retried once.