# Client

ACME client API.

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

  Bases: `object`

  ACME client.

  Todo

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

  Variables:

  - directory (messages.Directory) –
  - key – `JWK` (private)
  - alg – `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`
    Raises: | .UnexpectedUpdate –

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

  `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) – `new-authorization` URI. If omitted, will default to value found in `directory`.

    Returns: | Authorization Resource.
    Return type: | `AuthorizationResource`

  `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.
    Returns: | Authorization Resource.
    Return type: | `AuthorizationResource`

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

  `poll`(authzr)

    Poll Authorization Resource for status.

    Parameters: | authzr (`AuthorizationResource`) – Authorization Resource
    Returns: | Updated Authorization Resource and HTTP response.
    Return type: | (`AuthorizationResource`, `requests.Response`)

  `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_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, `acme.jose.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)

    Revoke certificate.

    Parameters: | cert (ComparableX509) – `OpenSSL.crypto.X509` wrapped in `ComparableX509`
    Raises: | .ClientError – If revocation is unsuccessful.

class `acme.client.``ClientNetwork`(key, alg=RS256, verify_ssl=True, user_agent='acme-python')

  Bases: `object`

  Client network.

  `_wrap_in_jws`(obj, nonce)

    Wrap `JSONDeSerializable` object in JWS.

    Todo

    Implement `acmePath`.

    Parameters:

    - obj (JSONDeSerializable) –
    - nonce (bytes) –

    Return type: | `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`(url, obj, content_type='application/json', **kwargs)

    POST object wrapped in `JWS` and check response.