Client¶
ACME client API.
-
class
acme.client.
Client
(directory, key, alg=RS256, verify_ssl=True, net=None)[source]¶ Bases:
object
ACME client.
Todo
Clean up raised error types hierarchy, document, and handle (wrap) instances of
DeserializationError
raised infrom_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
andverify_ssl
.
-
register
(new_reg=None)[source]¶ Register.
Parameters: new_reg (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:
-
query_registration
(regr)[source]¶ Query server about registration.
Parameters: messages.RegistrationResource – Existing Registration Resource.
-
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) –
new-authorization
URI. If omitted, will default to value found indirectory
.
Returns: Authorization Resource.
Return type:
-
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. Returns: Authorization Resource. Return type: AuthorizationResource
-
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
)
-
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, acme.jose.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
-
revoke
(cert)[source]¶ Revoke certificate.
Parameters: cert (ComparableX509) – OpenSSL.crypto.X509
wrapped inComparableX509
Raises: .ClientError – If revocation is unsuccessful.
-
class
acme.client.
ClientNetwork
(key, alg=RS256, verify_ssl=True, user_agent='acme-python')[source]¶ Bases:
object
Client network.
-
_wrap_in_jws
(obj, nonce)[source]¶ Wrap
JSONDeSerializable
object in JWS.Todo
Implement
acmePath
.Parameters: - obj (JSONDeSerializable) –
- nonce (bytes) –
Return type:
-
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.
-