# Client

ACME client API.

class `acme.client.``ClientBase`(directory, net, acme_version)

  Bases: `object`

  ACME client base object.

  Variables:

  - directory (messages.Directory) –
  - net (ClientNetwork) – Client network.
  - acme_version (int) – ACME protocol version. 1 or 2.

  `_post`(*args, **kwargs)

    Wrapper around self.net.post that adds the acme_version.

  `update_registration`(regr, update=None)

    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)

    Deactivate registration.

    Parameters: | regr (messages.RegistrationResource) – The Registration Resource to be deactivated.
    Returns: | The Registration resource that was deactivated.
    Return type: | `RegistrationResource`

  `answer_challenge`(challb, response)

    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, default)

    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`

  `_revoke`(cert, rsn, url)

    Revoke certificate.

    Parameters:

    - cert (ComparableX509) – `OpenSSL.crypto.X509` wrapped in `ComparableX509`
    - rsn (int) – Reason code for certificate revocation.
    - url (str) – ACME URL to post to

    Raises: | .ClientError – If revocation is unsuccessful.

class `acme.client.``Client`(directory, key, alg=RS256, verify_ssl=True, net=None)

  Bases: `acme.client.ClientBase`

  ACME client for a v1 API.

  Todo

  Clean up raised error types hierarchy, document, and handle (wrap) instances of `DeserializationError` raised in `from_json()`.

  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=None)

    Register.

    Parameters: | new_reg (NewRegistration) –
    Returns: | Registration Resource.
    Return type: | `RegistrationResource`

  `query_registration`(regr)

    Query server about registration.

    Parameters: | messages.RegistrationResource – Existing Registration Resource.

  `agree_to_tos`(regr)

    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, new_authzr_uri=None)

    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, new_authzr_uri=None)

    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, authzrs)

    Request issuance.

    Parameters:

    - csr (`OpenSSL.crypto.X509Req` wrapped in `ComparableX509`) – CSR
    - authzrs – `list` of `AuthorizationResource`

    Returns: | Issued certificate
    Return type: | `messages.CertificateResource`

  `poll`(authzr)

    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, authzrs, mintime=5, max_attempts=10)

    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

  `_get_cert`(uri)

    Returns certificate from URI.

    Parameters: | uri (str) – URI of certificate
    Returns: | tuple of the form (response, `josepy.util.ComparableX509`)
    Return type: | tuple

  `check_cert`(certr)

    Check for new cert.

    Parameters: | certr (`CertificateResource`) – Certificate Resource
    Returns: | Updated Certificate Resource.
    Return type: | `CertificateResource`

  `refresh`(certr)

    Refresh certificate.

    Parameters: | certr (`CertificateResource`) – Certificate Resource
    Returns: | Updated Certificate Resource.
    Return type: | `CertificateResource`

  `fetch_chain`(certr, max_length=10)

    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, rsn)

    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, net)

  Bases: `acme.client.ClientBase`

  ACME client for a v2 API.

  Variables:

  - directory (messages.Directory) –
  - net (ClientNetwork) – Client network.

  `new_account`(new_account)

    Register.

    Parameters: | new_account (NewRegistration) –
    Raises: | .ConflictError – in case the account already exists
    Returns: | Registration Resource.
    Return type: | `RegistrationResource`

  `query_registration`(regr)

    Query server about registration.

    Parameters: | messages.RegistrationResource – Existing Registration Resource.

  `update_registration`(regr, update=None)

    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)

    Request a new Order object from the server.

    Parameters: | csr_pem (str) – A CSR in PEM format.
    Returns: | The newly created order.
    Return type: | OrderResource

  `poll`(authzr)

    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, deadline=None)

    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, deadline)

    Poll Order Resource for status.

  `finalize_order`(orderr, deadline)

    Finalize an order and obtain a certificate.

    Parameters:

    - orderr (messages.OrderResource) – order to finalize
    - deadline (datetime.datetime) – when to stop polling and timeout

    Returns: | finalized order
    Return type: | messages.OrderResource

  `revoke`(cert, rsn)

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

    Checks if ACME server requires External Account Binding authentication.

  `_post_as_get`(*args, **kwargs)

    Send GET request using the POST-as-GET protocol if needed. The request will be first issued using POST-as-GET for ACME v2. If the ACME CA servers do not support this yet and return an error, request will be retried using GET. For ACME v1, only GET request will be tried, as POST-as-GET is not supported. :param args: :param kwargs: :return:

class `acme.client.``BackwardsCompatibleClientV2`(net, key, server)

  Bases: `object`

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

  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, check_tos_cb=None)

    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)

    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 (str) – 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, deadline)

    Finalize an order and obtain a certificate.

    Parameters:

    - orderr (messages.OrderResource) – order to finalize
    - deadline (datetime.datetime) – when to stop polling and timeout

    Returns: | finalized order
    Return type: | messages.OrderResource

  `revoke`(cert, rsn)

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

    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, account=None, alg=RS256, verify_ssl=True, user_agent='acme-python', timeout=45, source_address=None)

  Bases: `object`

  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) – Algoritm 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.

  `_wrap_in_jws`(obj, nonce, url, acme_version)

    Wrap `JSONDeSerializable` object in JWS.

    Todo

    Implement `acmePath`.

    Parameters:

    - obj (josepy.JSONDeSerializable) –
    - url (str) – The URL to which this object will be POSTed
    - nonce (bytes) –

    Return type: | `josepy.JWS`

  classmethod `_check_response`(response, content_type=None)

    Check response content and its type.

    Note

    Checking is not strict: wrong server response `Content-Type` HTTP header is ignored if response is an expected JSON object (c.f. Boulder #56).

    Parameters: | content_type (str) – Expected Content-Type response header. If JSON is expected and not present in server response, this function will raise an error. Otherwise, wrong Content-Type is ignored, but logged.

    Raises:

    - .messages.Error – If server response body carries HTTP Problem (draft-ietf-appsawg-http-problem-00).
    - .ClientError – In case of other networking errors.

  `_send_request`(method, url, *args, **kwargs)

    Send HTTP request.

    Makes sure that `verify_ssl` is respected. Logs request and response (with headers). For allowed parameters please see `requests.request`.

    Parameters:

    - method (str) – method for the new `requests.Request` object
    - url (str) – URL for the new `requests.Request` object

    Raises: | requests.exceptions.RequestException – in case of any problems
    Returns: | HTTP Response
    Return type: | `requests.Response`

  `head`(*args, **kwargs)

    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, content_type='application/json', **kwargs)

    Send GET request and check response.

  `post`(*args, **kwargs)

    POST object wrapped in `JWS` and check response.

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