Client

ACME client API.

class acme.client.ClientBase(directory, net, acme_version)[source]

Bases: object

ACME client base object.

Variables:
_post(*args, **kwargs)[source]

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

update_registration(regr, update=None)[source]

Update registration.

Parameters:
Returns:

Updated Registration Resource.

Return type:

RegistrationResource

deactivate_registration(regr)[source]

Deactivate registration.

Parameters:regr (messages.RegistrationResource) – The Registration Resource to be deactivated.
Returns:The Registration resource that was deactivated.
Return type:RegistrationResource
query_registration(regr)[source]

Query server about registration.

Parameters:messages.RegistrationResource – Existing Registration Resource.
answer_challenge(challb, response)[source]

Answer challenge.

Parameters:
Returns:

Challenge Resource with updated body.

Return type:

ChallengeResource

Raises:

UnexpectedUpdate

classmethod retry_after(response, default)[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

_revoke(cert, rsn, url)[source]

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)[source]

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) –
  • 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=None)[source]

Register.

Parameters:new_reg (NewRegistration) –
Returns:Registration Resource.
Return type:RegistrationResource
agree_to_tos(regr)[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, new_authzr_uri=None)[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, new_authzr_uri=None)[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, authzrs)[source]

Request issuance.

Parameters:
Returns:

Issued certificate

Return type:

messages.CertificateResource

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

_get_cert(uri)[source]

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)[source]

Check for new cert.

Parameters:certr (CertificateResource) – Certificate Resource
Returns:Updated Certificate Resource.
Return type:CertificateResource
refresh(certr)[source]

Refresh certificate.

Parameters:certr (CertificateResource) – Certificate Resource
Returns:Updated Certificate Resource.
Return type:CertificateResource
fetch_chain(certr, max_length=10)[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, rsn)[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, net)[source]

Bases: acme.client.ClientBase

ACME client for a v2 API.

Variables:
new_account(new_account)[source]

Register.

Parameters:new_account (NewRegistration) –
Raises:ConflictError – in case the account already exists
Returns:Registration Resource.
Return type:RegistrationResource
query_registration(regr)[source]

Query server about registration.

Parameters:messages.RegistrationResource – Existing Registration Resource.
update_registration(regr, update=None)[source]

Update registration.

Parameters:
Returns:

Updated Registration Resource.

Return type:

RegistrationResource

new_order(csr_pem)[source]

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

Poll Order Resource for status.

finalize_order(orderr, deadline)[source]

Finalize an order and obtain a certificate.

Parameters:
Returns:

finalized order

Return type:

messages.OrderResource

revoke(cert, rsn)[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()[source]

Checks if ACME server requires External Account Binding authentication.

_post_as_get(*args, **kwargs)[source]

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)[source]

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)[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)[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 (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)[source]

Finalize an order and obtain a certificate.

Parameters:
Returns:

finalized order

Return type:

messages.OrderResource

revoke(cert, rsn)[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()[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, account=None, alg=RS256, verify_ssl=True, user_agent='acme-python', timeout=45, source_address=None)[source]

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)[source]

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)[source]

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)[source]

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

Send GET request and check response.

post(*args, **kwargs)[source]

POST object wrapped in JWS and check response.

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