Client¶
ACME client API.
-
class
acme.client.
ClientBase
(directory, net, acme_version)[source]¶ Bases:
object
ACME client base object.
Variables: - directory (messages.Directory) –
- net (ClientNetwork) – Client network.
- acme_version (int) – ACME protocol version. 1 or 2.
-
update_registration
(regr, update=None)[source]¶ 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:
-
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: - challb (
ChallengeBody
) – Challenge Resource body. - response (
challenges.ChallengeResponse
) – Corresponding Challenge response
Returns: Challenge Resource with updated body.
Return type: Raises: .UnexpectedUpdate –
- challb (
-
classmethod
retry_after
(response, default)[source]¶ Compute next
poll
time based on responseRetry-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
- response (requests.Response) – Response from
-
poll
(authzr)[source]¶ Poll Authorization Resource for status.
Parameters: authzr ( AuthorizationResource
) – Authorization ResourceReturns: Updated Authorization Resource and HTTP response. Return type: ( AuthorizationResource
,requests.Response
)
-
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 infrom_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
andverify_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: 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. Seerequest_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: Raises: errors.WildcardUnsupportedError – if a wildcard is requested
-
request_issuance
(csr, authzrs)[source]¶ Request issuance.
Parameters: - csr (
OpenSSL.crypto.X509Req
wrapped inComparableX509
) – CSR - authzrs –
list
ofAuthorizationResource
Returns: Issued certificate
Return type: - csr (
-
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 callsrequest_issuance
.Parameters: - csr (ComparableX509) – CSR (
OpenSSL.crypto.X509Req
wrapped inComparableX509
) - authzrs –
list
ofAuthorizationResource
- 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-emptywaiting
is raised.
Returns: (cert, updated_authzrs)
tuple
wherecert
is the issued certificate (messages.CertificateResource
), andupdated_authzrs
is atuple
consisting of updated Authorization Resources (AuthorizationResource
) as present in the responses from server, and in the same order as the inputauthzrs
.Return type: tuple
Raises: PollError – in case of timeout or if some authorization was marked by the CA as invalid
- csr (ComparableX509) – CSR (
-
_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 ResourceReturns: Updated Certificate Resource. Return type: CertificateResource
-
refresh
(certr)[source]¶ Refresh certificate.
Parameters: certr ( CertificateResource
) – Certificate ResourceReturns: 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
isNone
.Return type: list
ofOpenSSL.crypto.X509
wrapped inComparableX509
-
class
acme.client.
ClientV2
(directory, net)[source]¶ Bases:
acme.client.ClientBase
ACME client for a v2 API.
Variables: - directory (messages.Directory) –
- net (ClientNetwork) – Client network.
-
new_account
(new_account)[source]¶ Register.
Parameters: new_account (NewRegistration) – Returns: Registration Resource. Return type: RegistrationResource
-
update_registration
(regr, update=None)[source]¶ 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:
-
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_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: - orderr (messages.OrderResource) – order to finalize
- deadline (datetime.datetime) – when to stop polling and timeout
Returns: finalized order
Return type:
Poll Order Resource for status.
-
finalize_order
(orderr, deadline)[source]¶ 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:
-
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: - orderr (messages.OrderResource) – order to finalize
- deadline (datetime.datetime) – when to stop polling and timeout
Returns: finalized order
Return type:
-
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 seerequests.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
- method (str) – method for the new
-
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.
-