# 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)

  ACME client base object.

  Variables

    - directory (messages.Directory) –

    - net (ClientNetwork) – Client network.

    - acme_version (int) – ACME protocol version. 1 or 2.

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

    Update registration.

    Parameters

      - regr (messages.RegistrationResource) – Registration Resource.

      - update (messages.Registration) – Updated body of the resource. If not provided, body will be taken from `regr`.

    Returns

      Updated Registration Resource.

    Return type

      `RegistrationResource`

  deactivate_registration(regr: acme.messages.RegistrationResource) → acme.messages.RegistrationResource

    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

    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: requests.models.Response) → acme.messages.ChallengeResource

    Answer challenge.

    Parameters

      - challb (`ChallengeBody`) – Challenge Resource body.

      - response (`challenges.ChallengeResponse`) – Corresponding Challenge response

    Returns

      Challenge Resource with updated body.

    Return type

      `ChallengeResource`

    Raises

      UnexpectedUpdate –

  classmethod retry_after(response: requests.models.Response, default: int) → datetime.datetime

    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)

  ACME client for a v1 API.

  Deprecated since version 1.18.0: Use `ClientV2` instead.

  Variables

    - directory (messages.Directory) –

    - key – `josepy.JWK` (private)

    - alg – `josepy.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

    Register.

    Parameters

      new_reg (NewRegistration) –

    Returns

      Registration Resource.

    Return type

      `RegistrationResource`

  query_registration(regr: acme.messages.RegistrationResource) → acme.messages.RegistrationResource

    Query server about registration.

    Parameters

      regr (messages.RegistrationResource) – Existing Registration Resource.

  agree_to_tos(regr: acme.messages.RegistrationResource) → acme.messages.RegistrationResource

    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

    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

    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

    Request issuance.

    Parameters

      - csr (`OpenSSL.crypto.X509Req` wrapped in `ComparableX509`) – CSR

      - authzrs – `list` of `AuthorizationResource`

    Returns

      Issued certificate

    Return type

      `messages.CertificateResource`

  poll(authzr: acme.messages.AuthorizationResource) → Tuple[acme.messages.AuthorizationResource, requests.models.Response]

    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, ...]]

    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`)

      - authzrs – `list` 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

    Check for new cert.

    Parameters

      certr (`CertificateResource`) – Certificate Resource

    Returns

      Updated Certificate Resource.

    Return type

      `CertificateResource`

  refresh(certr: acme.messages.CertificateResource) → acme.messages.CertificateResource

    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]

    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

    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)

  ACME client for a v2 API.

  Variables

    - directory (messages.Directory) –

    - net (ClientNetwork) – Client network.

  new_account(new_account: acme.messages.NewRegistration) → acme.messages.RegistrationResource

    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

    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

    Update registration.

    Parameters

      - regr (messages.RegistrationResource) – Registration Resource.

      - update (messages.Registration) – Updated body of the resource. If not provided, body will be taken from `regr`.

    Returns

      Updated Registration Resource.

    Return type

      `RegistrationResource`

  new_order(csr_pem: bytes) → acme.messages.OrderResource

    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]

    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

    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: acme.messages.OrderResource, deadline: datetime.datetime) → acme.messages.OrderResource

    Poll Order Resource for status.

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

    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

  revoke(cert: josepy.util.ComparableX509, rsn: int) → None

    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

    Checks if ACME server requires External Account Binding authentication.

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

  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

    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

    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

    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

  revoke(cert: josepy.util.ComparableX509, rsn: int) → None

    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

    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)

  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.

  head(*args: Any, **kwargs: Any) → requests.models.Response

    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

    Send GET request and check response.

  post(*args: Any, **kwargs: Any) → requests.models.Response

    POST object wrapped in `JWS` and check response.

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