Client¶
Internal class delegating to a module, and displaying warnings when attributes related to deprecated attributes in the acme.client module.
- class acme.client.ClientBase(directory: acme.messages.Directory, net: acme.client.ClientNetwork, acme_version: int)[source]¶
ACME client base object.
Deprecated since version 1.30.0: Use
ClientV2
instead.- Variables:
directory (messages.Directory) –
net (.ClientNetwork) – Client network.
acme_version (int) – ACME protocol version. 1 or 2.
- update_registration(regr: acme.messages.RegistrationResource, update: Optional[acme.messages.Registration] = None) acme.messages.RegistrationResource [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: acme.messages.RegistrationResource) acme.messages.RegistrationResource [source]¶
Deactivate registration.
- Parameters:
regr (messages.RegistrationResource) – The Registration Resource to be deactivated.
- Returns:
The Registration resource that was deactivated.
- Return type:
- deactivate_authorization(authzr: acme.messages.AuthorizationResource) acme.messages.AuthorizationResource [source]¶
Deactivate authorization.
- Parameters:
authzr (messages.AuthorizationResource) – The Authorization resource to be deactivated.
- Returns:
The Authorization resource that was deactivated.
- Return type:
- answer_challenge(challb: acme.messages.ChallengeBody, response: acme.challenges.ChallengeResponse) acme.messages.ChallengeResource [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 –
- classmethod retry_after(response: requests.models.Response, default: int) datetime.datetime [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
- class acme.client.Client(directory: acme.messages.Directory, key: josepy.jwk.JWK, alg: josepy.jwa.JWASignature = RS256, verify_ssl: bool = True, net: Optional[acme.client.ClientNetwork] = None)[source]¶
ACME client for a v1 API.
Deprecated since version 1.18.0: Use
ClientV2
instead.- 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: Optional[acme.messages.NewRegistration] = None) acme.messages.RegistrationResource [source]¶
Register.
- Parameters:
new_reg (.NewRegistration) –
- Returns:
Registration Resource.
- Return type:
- query_registration(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource [source]¶
Query server about registration.
- Parameters:
regr (messages.RegistrationResource) – Existing Registration Resource.
- agree_to_tos(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource [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:
- request_challenges(identifier: acme.messages.Identifier, new_authzr_uri: Optional[str] = None) acme.messages.AuthorizationResource [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: str, new_authzr_uri: Optional[str] = None) acme.messages.AuthorizationResource [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: josepy.util.ComparableX509, authzrs: Iterable[acme.messages.AuthorizationResource]) acme.messages.CertificateResource [source]¶
Request issuance.
- Parameters:
csr (
OpenSSL.crypto.X509Req
wrapped inComparableX509
) – CSRauthzrs –
list
ofAuthorizationResource
- Returns:
Issued certificate
- Return type:
- poll(authzr: acme.messages.AuthorizationResource) Tuple[acme.messages.AuthorizationResource, requests.models.Response] [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: josepy.util.ComparableX509, authzrs: Iterable[acme.messages.AuthorizationResource], mintime: int = 5, max_attempts: int = 10) Tuple[acme.messages.CertificateResource, Tuple[acme.messages.AuthorizationResource, ...]] [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
- check_cert(certr: acme.messages.CertificateResource) acme.messages.CertificateResource [source]¶
Check for new cert.
- Parameters:
certr (
CertificateResource
) – Certificate Resource- Returns:
Updated Certificate Resource.
- Return type:
- refresh(certr: acme.messages.CertificateResource) acme.messages.CertificateResource [source]¶
Refresh certificate.
- Parameters:
certr (
CertificateResource
) – Certificate Resource- Returns:
Updated Certificate Resource.
- Return type:
- fetch_chain(certr: acme.messages.CertificateResource, max_length: int = 10) List[josepy.util.ComparableX509] [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: acme.messages.Directory, net: acme.client.ClientNetwork)[source]¶
ACME client for a v2 API.
- Variables:
directory (messages.Directory) –
net (.ClientNetwork) – Client network.
- new_account(new_account: acme.messages.NewRegistration) acme.messages.RegistrationResource [source]¶
Register.
- Parameters:
new_account (.NewRegistration) –
- Raises:
.ConflictError – in case the account already exists
- Returns:
Registration Resource.
- Return type:
- query_registration(regr: acme.messages.RegistrationResource) acme.messages.RegistrationResource [source]¶
Query server about registration.
- Parameters:
regr (messages.RegistrationResource) – Existing Registration Resource.
- update_registration(regr: acme.messages.RegistrationResource, update: Optional[acme.messages.Registration] = None) acme.messages.RegistrationResource [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: bytes) acme.messages.OrderResource [source]¶
Request a new Order object from the server.
- Parameters:
csr_pem (bytes) – A CSR in PEM format.
- Returns:
The newly created order.
- Return type:
- poll(authzr: acme.messages.AuthorizationResource) Tuple[acme.messages.AuthorizationResource, requests.models.Response] [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: acme.messages.OrderResource, deadline: Optional[datetime.datetime] = None) acme.messages.OrderResource [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_authorizations(orderr: acme.messages.OrderResource, deadline: datetime.datetime) acme.messages.OrderResource [source]¶
Poll Order Resource for status.
- finalize_order(orderr: acme.messages.OrderResource, deadline: datetime.datetime, fetch_alternative_chains: bool = False) acme.messages.OrderResource [source]¶
Finalize an order and obtain a certificate.
- Parameters:
orderr (messages.OrderResource) – order to finalize
deadline (datetime.datetime) – when to stop polling and timeout
fetch_alternative_chains (bool) – whether to also fetch alternative certificate chains
- Returns:
finalized order
- Return type:
- class acme.client.BackwardsCompatibleClientV2(net: acme.client.ClientNetwork, key: josepy.jwk.JWK, server: str)[source]¶
ACME client wrapper that tends towards V2-style calls, but supports V1 servers.
Deprecated since version 1.18.0: Use
ClientV2
instead.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: acme.messages.NewRegistration, check_tos_cb: Optional[Callable[[str], None]] = None) acme.messages.RegistrationResource [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: bytes) acme.messages.OrderResource [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 (bytes) – A CSR in PEM format.
- Returns:
The newly created order.
- Return type:
- Raises:
errors.WildcardUnsupportedError – if a wildcard domain is requested but unsupported by the ACME version
- finalize_order(orderr: acme.messages.OrderResource, deadline: datetime.datetime, fetch_alternative_chains: bool = False) acme.messages.OrderResource [source]¶
Finalize an order and obtain a certificate.
- Parameters:
orderr (messages.OrderResource) – order to finalize
deadline (datetime.datetime) – when to stop polling and timeout
fetch_alternative_chains (bool) – whether to also fetch alternative certificate chains
- Returns:
finalized order
- Return type:
- class acme.client.ClientNetwork(key: josepy.jwk.JWK, account: Optional[acme.messages.RegistrationResource] = None, alg: josepy.jwa.JWASignature = RS256, verify_ssl: bool = True, user_agent: str = 'acme-python', timeout: int = 45, source_address: Optional[Union[str, Tuple[str, int]]] = None)[source]¶
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) – Algorithm 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. (deprecated since 1.30.0)
- head(*args: Any, **kwargs: Any) requests.models.Response [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.