Client

Internal class delegating to a module, and displaying warnings when attributes related to deprecated attributes in the acme.client module.

class acme.client.ClientBase(directory: acme.messages.Directory, net: acme.client.ClientNetwork, acme_version: int)[source]

ACME client base object.

Deprecated since version 1.30.0: Use ClientV2 instead.

Variables
update_registration(regr: acme.messages.RegistrationResource, update: Optional[acme.messages.Registration] = None) acme.messages.RegistrationResource[source]

Update registration.

Parameters
Returns

Updated Registration Resource.

Return type

RegistrationResource

deactivate_registration(regr: acme.messages.RegistrationResource) acme.messages.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: acme.messages.AuthorizationResource) acme.messages.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: acme.messages.ChallengeBody, response: acme.challenges.ChallengeResponse) acme.messages.ChallengeResource[source]

Answer challenge.

Parameters
Returns

Challenge Resource with updated body.

Return type

ChallengeResource

Raises

UnexpectedUpdate

classmethod retry_after(response: requests.models.Response, default: int) datetime.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.Client(directory: acme.messages.Directory, key: josepy.jwk.JWK, alg: josepy.jwa.JWASignature = RS256, verify_ssl: bool = True, net: Optional[acme.client.ClientNetwork] = None)[source]

ACME client for a v1 API.

Deprecated since version 1.18.0: Use ClientV2 instead.

Variables
  • directory (messages.Directory) –

  • keyjosepy.JWK (private)

  • algjosepy.JWASignature

  • verify_ssl (bool) – Verify SSL certificates?

  • net (ClientNetwork) – Client network. Useful for testing. If not supplied, it will be initialized using key, alg and verify_ssl.

register(new_reg: Optional[acme.messages.NewRegistration] = None) acme.messages.RegistrationResource[source]

Register.

Parameters

new_reg (NewRegistration) –

Returns

Registration Resource.

Return type

RegistrationResource

query_registration(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource[source]

Query server about registration.

Parameters

regr (messages.RegistrationResource) – Existing Registration Resource.

agree_to_tos(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource[source]

Agree to the terms-of-service.

Agree to the terms-of-service in a Registration Resource.

Parameters

regr (RegistrationResource) – Registration Resource.

Returns

Updated Registration Resource.

Return type

RegistrationResource

request_challenges(identifier: acme.messages.Identifier, new_authzr_uri: Optional[str] = None) acme.messages.AuthorizationResource[source]

Request challenges.

Parameters
  • identifier (messages.Identifier) – Identifier to be challenged.

  • new_authzr_uri (str) – Deprecated. Do not use.

Returns

Authorization Resource.

Return type

AuthorizationResource

Raises

errors.WildcardUnsupportedError – if a wildcard is requested

request_domain_challenges(domain: str, new_authzr_uri: Optional[str] = None) acme.messages.AuthorizationResource[source]

Request challenges for domain names.

This is simply a convenience function that wraps around request_challenges, but works with domain names instead of generic identifiers. See request_challenges for more documentation.

Parameters
  • domain (str) – Domain name to be challenged.

  • new_authzr_uri (str) – Deprecated. Do not use.

Returns

Authorization Resource.

Return type

AuthorizationResource

Raises

errors.WildcardUnsupportedError – if a wildcard is requested

request_issuance(csr: josepy.util.ComparableX509, authzrs: Iterable[acme.messages.AuthorizationResource]) acme.messages.CertificateResource[source]

Request issuance.

Parameters
Returns

Issued certificate

Return type

messages.CertificateResource

poll(authzr: acme.messages.AuthorizationResource) Tuple[acme.messages.AuthorizationResource, requests.models.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_request_issuance(csr: josepy.util.ComparableX509, authzrs: Iterable[acme.messages.AuthorizationResource], mintime: int = 5, max_attempts: int = 10) Tuple[acme.messages.CertificateResource, Tuple[acme.messages.AuthorizationResource, ...]][source]

Poll and request issuance.

This function polls all provided Authorization Resource URIs until all challenges are valid, respecting Retry-After HTTP headers, and then calls request_issuance.

Parameters
  • csr (ComparableX509) – CSR (OpenSSL.crypto.X509Req wrapped in ComparableX509)

  • authzrslist of AuthorizationResource

  • mintime (int) – Minimum time before next attempt, used if Retry-After is not present in the response.

  • max_attempts (int) – Maximum number of attempts (per authorization) before PollError with non-empty waiting is raised.

Returns

(cert, updated_authzrs) tuple where cert is the issued certificate (messages.CertificateResource), and updated_authzrs is a tuple consisting of updated Authorization Resources (AuthorizationResource) as present in the responses from server, and in the same order as the input authzrs.

Return type

tuple

Raises

PollError – in case of timeout or if some authorization was marked by the CA as invalid

check_cert(certr: acme.messages.CertificateResource) acme.messages.CertificateResource[source]

Check for new cert.

Parameters

certr (CertificateResource) – Certificate Resource

Returns

Updated Certificate Resource.

Return type

CertificateResource

refresh(certr: acme.messages.CertificateResource) acme.messages.CertificateResource[source]

Refresh certificate.

Parameters

certr (CertificateResource) – Certificate Resource

Returns

Updated Certificate Resource.

Return type

CertificateResource

fetch_chain(certr: acme.messages.CertificateResource, max_length: int = 10) List[josepy.util.ComparableX509][source]

Fetch chain for certificate.

Parameters
  • certr (CertificateResource) – Certificate Resource

  • max_length (int) – Maximum allowed length of the chain. Note that each element in the certificate requires new HTTP GET request, and the length of the chain is controlled by the ACME CA.

Raises

errors.Error – if recursion exceeds max_length

Returns

Certificate chain for the Certificate Resource. It is a list ordered so that the first element is a signer of the certificate from Certificate Resource. Will be empty if cert_chain_uri is None.

Return type

list of OpenSSL.crypto.X509 wrapped in ComparableX509

revoke(cert: josepy.util.ComparableX509, rsn: int) None[source]

Revoke certificate.

Parameters
  • cert (ComparableX509) – OpenSSL.crypto.X509 wrapped in ComparableX509

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

Raises

ClientError – If revocation is unsuccessful.

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

ACME client for a v2 API.

Variables
new_account(new_account: acme.messages.NewRegistration) acme.messages.RegistrationResource[source]

Register.

Parameters

new_account (NewRegistration) –

Raises

ConflictError – in case the account already exists

Returns

Registration Resource.

Return type

RegistrationResource

query_registration(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource[source]

Query server about registration.

Parameters

regr (messages.RegistrationResource) – Existing Registration Resource.

update_registration(regr: acme.messages.RegistrationResource, update: Optional[acme.messages.Registration] = None) acme.messages.RegistrationResource[source]

Update registration.

Parameters
Returns

Updated Registration Resource.

Return type

RegistrationResource

new_order(csr_pem: bytes) acme.messages.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: acme.messages.AuthorizationResource) Tuple[acme.messages.AuthorizationResource, requests.models.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: acme.messages.OrderResource, deadline: Optional[datetime.datetime] = None) acme.messages.OrderResource[source]

Poll authorizations and finalize the order.

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

Parameters
Returns

finalized order

Return type

messages.OrderResource

poll_authorizations(orderr: acme.messages.OrderResource, deadline: datetime.datetime) acme.messages.OrderResource[source]

Poll Order Resource for status.

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

Finalize an order and obtain a certificate.

Parameters
Returns

finalized order

Return type

messages.OrderResource

revoke(cert: josepy.util.ComparableX509, rsn: int) None[source]

Revoke certificate.

Parameters
  • cert (ComparableX509) – OpenSSL.crypto.X509 wrapped in ComparableX509

  • 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.

class acme.client.BackwardsCompatibleClientV2(net: acme.client.ClientNetwork, key: josepy.jwk.JWK, server: str)[source]

ACME client wrapper that tends towards V2-style calls, but supports V1 servers.

Deprecated since version 1.18.0: Use ClientV2 instead.

Note

While this class handles the majority of the differences between versions of the ACME protocol, if you need to support an ACME server based on version 3 or older of the IETF ACME draft that uses combinations in authorizations (or lack thereof) to signal that the client needs to complete something other than any single challenge in the authorization to make it valid, the user of this class needs to understand and handle these differences themselves. This does not apply to either of Let’s Encrypt’s endpoints where successfully completing any challenge in an authorization will make it valid.

Variables
  • acme_version (int) – 1 or 2, corresponding to the Let’s Encrypt endpoint

  • client (ClientBase) – either Client or ClientV2

new_account_and_tos(regr: acme.messages.NewRegistration, check_tos_cb: Optional[Callable[[str], None]] = None) acme.messages.RegistrationResource[source]

Combined register and agree_tos for V1, new_account for V2

Parameters
  • regr (NewRegistration) –

  • check_tos_cb (callable) – callback that raises an error if the check does not work

new_order(csr_pem: bytes) acme.messages.OrderResource[source]

Request a new Order object from the server.

If using ACMEv1, returns a dummy OrderResource with only the authorizations field filled in.

Parameters

csr_pem (bytes) – A CSR in PEM format.

Returns

The newly created order.

Return type

OrderResource

Raises

errors.WildcardUnsupportedError – if a wildcard domain is requested but unsupported by the ACME version

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

Finalize an order and obtain a certificate.

Parameters
Returns

finalized order

Return type

messages.OrderResource

revoke(cert: josepy.util.ComparableX509, rsn: int) None[source]

Revoke certificate.

Parameters
  • cert (ComparableX509) – OpenSSL.crypto.X509 wrapped in ComparableX509

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

Raises

ClientError – If revocation is unsuccessful.

external_account_required() bool[source]

Checks if the server requires an external account for ACMEv2 servers.

Always return False for ACMEv1 servers, as it doesn’t use External Account Binding.

class acme.client.ClientNetwork(key: josepy.jwk.JWK, account: Optional[acme.messages.RegistrationResource] = None, alg: josepy.jwa.JWASignature = RS256, verify_ssl: bool = True, user_agent: str = 'acme-python', timeout: int = 45, source_address: Optional[Union[str, Tuple[str, int]]] = None)[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

  • account (messages.RegistrationResource) – Account object. Required if you are planning to use .post() with acme_version=2 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 (float) – Timeout for requests.

  • source_address (str or tuple(str, int)) – Optional source address to bind to when making requests. (deprecated since 1.30.0)

head(*args: Any, **kwargs: Any) requests.models.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) requests.models.Response[source]

Send GET request and check response.

post(*args: Any, **kwargs: Any) requests.models.Response[source]

POST object wrapped in JWS and check response.

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