ACME-PYTHON(1) acme-python ACME-PYTHON(1)

acme-python - acme-python Documentation

Contents:

ACME Identifier Validation Challenges.

ACME challenge.
Deserialize ACME object from valid JSON object.
josepy.errors.UnrecognizedTypeError -- if type of the ACME object has not been registered.
Unrecognized challenge.

ACME specification defines a generic framework for challenges and defines some standard challenges that are implemented in this module. However, other implementations (including peers) might define additional challenge types, which should be ignored if unrecognized.

jobj -- Original JSON decoded object.
Get JSON serializable object.
Serializable JSON object representing ACME typed object. validate() will almost certainly not work, due to reasons explained in josepy.interfaces.IJSONSerializable.
dict
Deserialize ACME object from valid JSON object.
josepy.errors.UnrecognizedTypeError -- if type of the ACME object has not been registered.
Response to Challenges based on Key Authorization.
key_authorization (str) --
Verify the key authorization.
  • chall (KeyAuthorization) -- Challenge that corresponds to this response.
  • account_public_key (JWK) --
True iff verification of the key authorization was successful.
bool
See josepy.JSONDeserializable.to_partial_json()
Challenge based on Key Authorization.
  • response_cls -- Subclass of KeyAuthorizationChallengeResponse that will be used to generate response.
  • typ (str) -- type of the challenge
Generate Key Authorization.
account_key (JWK) --
Generate response to the challenge.
account_key (JWK) --
Response (initialized response_cls) to the challenge.
KeyAuthorizationChallengeResponse
Generate validation for the challenge.

Subclasses must implement this method, but they are likely to return completely different data structures, depending on what's necessary to complete the challenge. Interpretation of that return value must be known to the caller.

account_key (JWK) --
Challenge-specific validation.
Generate response and validation.

Convenience function that return results of response and validation.

account_key (JWK) --
tuple
ACME dns-01 challenge response.
Simple verify.

This method no longer checks DNS records and is a simple wrapper around KeyAuthorizationChallengeResponse.verify.

  • chall (challenges.DNS01) -- Corresponding challenge.
  • domain (str) -- Domain name being verified.
  • account_public_key (JWK) -- Public key for the key pair being authorized.
True iff verification of the key authorization was successful.
bool
ACME dns-01 challenge.
alias of acme.challenges.DNS01Response
Label clients prepend to the domain name being validated.
Domain name for TXT validation record.
name (str) -- Domain name being validated.
str
ACME http-01 challenge response.
Verification port as defined by the protocol.

You can override it (e.g. for testing) by passing port to simple_verify.

Whitespace characters which should be ignored at the end of the body.
Simple verify.
  • chall (challenges.SimpleHTTP) -- Corresponding challenge.
  • domain (str) -- Domain name being verified.
  • account_public_key (JWK) -- Public key for the key pair being authorized.
  • port (int) -- Port used in the validation.
True iff validation with the files currently served by the HTTP server is successful.
bool
ACME http-01 challenge.
alias of acme.challenges.HTTP01Response
URI root path for the server provisioned resource.
Path (starting with '/') for provisioned resource.
Create an URI to the provisioned resource.

Forms an URI to the HTTPS server provisioned resource (containing token).

domain (str) -- Domain name being verified.
str
ACME tls-alpn-01 challenge response.
Verification port as defined by the protocol.

You can override it (e.g. for testing) by passing port to simple_verify.

Hash value stored in challenge certificate
Generate tls-alpn-01 certificate.
  • domain (str) -- Domain verified by the challenge.
  • key (OpenSSL.crypto.PKey) -- Optional private key used in certificate generation. If not provided (None), then fresh key will be generated.
  • bits (int) -- Number of bits for newly generated key.
tuple of OpenSSL.crypto.X509 and OpenSSL.crypto.PKey
Probe tls-alpn-01 challenge certificate.
  • domain (str) -- domain being validated, required.
  • host (str) -- IP address used to probe the certificate.
  • port (int) -- Port used to probe the certificate.
Verify tls-alpn-01 challenge certificate.
  • domain (str) -- Domain name being validated.
  • cert (OpensSSL.crypto.X509) -- Challenge certificate.
Whether the certificate was successfully verified.
bool
Simple verify.

Verify validation using account_public_key, optionally probe tls-alpn-01 certificate and check using verify_cert.

  • chall (.challenges.TLSALPN01) -- Corresponding challenge.
  • domain (str) -- Domain name being validated.
  • account_public_key (JWK) --
  • cert (OpenSSL.crypto.X509) -- Optional certificate. If not provided (None) certificate will be retrieved using probe_cert.
  • host (string) -- IP address used to probe the certificate.
  • port (int) -- Port used to probe the certificate.
True if and only if client's control of the domain has been verified.
bool
ACME tls-alpn-01 challenge.
alias of acme.challenges.TLSALPN01Response
Generate validation.
  • account_key (JWK) --
  • domain (str) -- Domain verified by the challenge.
  • cert_key (OpenSSL.crypto.PKey) -- Optional private key used in certificate generation. If not provided (None), then fresh key will be generated.
tuple of OpenSSL.crypto.X509 and OpenSSL.crypto.PKey
Check if TLS-ALPN-01 challenge is supported on this machine. This implies that a recent version of OpenSSL is installed (>= 1.0.2), or a recent cryptography version shipped with the OpenSSL library is installed.
True if TLS-ALPN-01 is supported on this machine, False otherwise.
bool
ACME "dns" challenge.
Label clients prepend to the domain name being validated.
Generate validation.
  • account_key (.JWK) -- Private account key.
  • alg (.JWA) --
This challenge wrapped in JWS
.JWS
Check validation.
  • validation (JWS) --
  • account_public_key (JWK) --
bool
Generate response.
  • account_key (.JWK) -- Private account key.
  • alg (.JWA) --
DNSResponse
Domain name for TXT validation record.
name (str) -- Domain name being validated.
ACME "dns" challenge response.
validation (JWS) --
Check validation.
  • chall (challenges.DNS) --
  • account_public_key (JWK) --
bool

Internal class delegating to a module, and displaying warnings when attributes related to deprecated attributes in the acme.client module.

ACME client base object.
  • directory (messages.Directory) --
  • net (.ClientNetwork) -- Client network.
  • acme_version (int) -- ACME protocol version. 1 or 2.
Update registration.
  • regr (messages.RegistrationResource) -- Registration Resource.
  • update (messages.Registration) -- Updated body of the resource. If not provided, body will be taken from regr.
Updated Registration Resource.
RegistrationResource
Deactivate registration.
regr (messages.RegistrationResource) -- The Registration Resource to be deactivated.
The Registration resource that was deactivated.
RegistrationResource
Deactivate authorization.
authzr (messages.AuthorizationResource) -- The Authorization resource to be deactivated.
The Authorization resource that was deactivated.
AuthorizationResource
Answer challenge.
  • challb (ChallengeBody) -- Challenge Resource body.
  • response (challenges.ChallengeResponse) -- Corresponding Challenge response
Challenge Resource with updated body.
ChallengeResource
.UnexpectedUpdate --
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

  • response (requests.Response) -- Response from poll.
  • default (int) -- Default value (in seconds), used when Retry-After header is not present or invalid.
Time point when next poll should be performed.
datetime.datetime
ACME client for a v1 API.

Deprecated since version 1.18.0: Use ClientV2 instead.

  • 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 and verify_ssl.
Register.
new_reg (.NewRegistration) --
Registration Resource.
RegistrationResource
Query server about registration.
regr (messages.RegistrationResource) -- Existing Registration Resource.
Agree to the terms-of-service.

Agree to the terms-of-service in a Registration Resource.

regr (RegistrationResource) -- Registration Resource.
Updated Registration Resource.
RegistrationResource
Request challenges.
  • identifier (.messages.Identifier) -- Identifier to be challenged.
  • new_authzr_uri (str) -- Deprecated. Do not use.
Authorization Resource.
AuthorizationResource
errors.WildcardUnsupportedError -- if a wildcard is requested
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.

  • domain (str) -- Domain name to be challenged.
  • new_authzr_uri (str) -- Deprecated. Do not use.
Authorization Resource.
AuthorizationResource
errors.WildcardUnsupportedError -- if a wildcard is requested
Request issuance.
  • csr (OpenSSL.crypto.X509Req wrapped in ComparableX509) -- CSR
  • authzrs -- list of AuthorizationResource
Issued certificate
messages.CertificateResource
Poll Authorization Resource for status.
authzr (AuthorizationResource) -- Authorization Resource
Updated Authorization Resource and HTTP response.
(AuthorizationResource, requests.Response)
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.

  • 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.
(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.
tuple
PollError -- in case of timeout or if some authorization was marked by the CA as invalid
Check for new cert.
certr (CertificateResource) -- Certificate Resource
Updated Certificate Resource.
CertificateResource
Refresh certificate.
certr (CertificateResource) -- Certificate Resource
Updated Certificate Resource.
CertificateResource
Fetch chain for certificate.
  • 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.
errors.Error -- if recursion exceeds max_length
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.
list of OpenSSL.crypto.X509 wrapped in ComparableX509
Revoke certificate.
  • cert (.ComparableX509) -- OpenSSL.crypto.X509 wrapped in ComparableX509
  • rsn (int) -- Reason code for certificate revocation.
.ClientError -- If revocation is unsuccessful.
ACME client for a v2 API.
  • directory (messages.Directory) --
  • net (.ClientNetwork) -- Client network.
Register.
new_account (.NewRegistration) --
.ConflictError -- in case the account already exists
Registration Resource.
RegistrationResource
Query server about registration.
regr (messages.RegistrationResource) -- Existing Registration Resource.
Update registration.
  • regr (messages.RegistrationResource) -- Registration Resource.
  • update (messages.Registration) -- Updated body of the resource. If not provided, body will be taken from regr.
Updated Registration Resource.
RegistrationResource
Request a new Order object from the server.
csr_pem (bytes) -- A CSR in PEM format.
The newly created order.
OrderResource
Poll Authorization Resource for status.
authzr (AuthorizationResource) -- Authorization Resource
Updated Authorization Resource and HTTP response.
(AuthorizationResource, requests.Response)
Poll authorizations and finalize the order.

If no deadline is provided, this method will timeout after 90 seconds.

  • orderr (messages.OrderResource) -- order to finalize
  • deadline (datetime.datetime) -- when to stop polling and timeout
finalized order
messages.OrderResource
Finalize an order and obtain a certificate.
  • 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
finalized order
messages.OrderResource
Revoke certificate.
  • cert (.ComparableX509) -- OpenSSL.crypto.X509 wrapped in ComparableX509
  • rsn (int) -- Reason code for certificate revocation.
.ClientError -- If revocation is unsuccessful.
Checks if ACME server requires External Account Binding authentication.
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.
  • acme_version (int) -- 1 or 2, corresponding to the Let's Encrypt endpoint
  • client (.ClientBase) -- either Client or ClientV2
Combined register and agree_tos for V1, new_account for V2
  • regr (.NewRegistration) --
  • check_tos_cb (callable) -- callback that raises an error if the check does not work
Request a new Order object from the server.

If using ACMEv1, returns a dummy OrderResource with only the authorizations field filled in.

csr_pem (bytes) -- A CSR in PEM format.
The newly created order.
OrderResource
errors.WildcardUnsupportedError -- if a wildcard domain is requested but unsupported by the ACME version
Finalize an order and obtain a certificate.
  • 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
finalized order
messages.OrderResource
Revoke certificate.
  • cert (.ComparableX509) -- OpenSSL.crypto.X509 wrapped in ComparableX509
  • rsn (int) -- Reason code for certificate revocation.
.ClientError -- If revocation is unsuccessful.
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.

Wrapper around requests that signs POSTs for authentication.

Also adds user agent, and handles Content-Type.

Initialize.
  • 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.
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.

POST object wrapped in JWS and check response.

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

ACME errors.

Generic ACME error.
JSON schema ACME object validation error.
Unexpected update error.
Server response nonce error.
Missing nonce error.

According to the specification an "ACME server MUST include an Replay-Nonce header field in each successful response to a POST it provides to a client (...)".

~.response (requests.Response) -- HTTP Response
Generic error when polling for authorization fails.

This might be caused by either timeout (exhausted will be non-empty) or by some authorization being invalid.

  • exhausted -- Set of AuthorizationResource that didn't finish within max allowed attempts.
  • updated -- Mapping from original AuthorizationResource to the most recently updated one
Was the error caused by timeout?
Error for authorization failures. Contains a list of authorization resources, each of which is invalid and should have an error field.
Error for when polling an authorization or an order times out.
Error sent by the server after requesting issuance of a certificate.
Error for when the server returns a 409 (Conflict) HTTP status.

In the version of ACME implemented by Boulder, this is used to find an account if you only have the private key, but don't know the account URL.

Also used in V2 of the ACME client for the same purpose.

Error for when a wildcard is requested but is unsupported by ACME CA.

ACME JSON fields.

Fixed field.
Decode a value, optionally with context JSON object.
Encode a value, optionally with context JSON object.
RFC3339 field encoder/decoder.

Handles decoding/encoding between RFC3339 strings and aware (not naive) datetime.datetime objects (e.g. datetime.datetime.now(pytz.utc)).

Default decoder.

Recursively deserialize into immutable types ( josepy.util.frozendict instead of dict(), tuple() instead of list()).

Resource MITM field.
Decode a value, optionally with context JSON object.
Generates a type-friendly Fixed field.
Generates a type-friendly Resource field.

The acme.jose module was moved to its own package "josepy". Please refer to its documentation there.

ACME protocol messages.

Check if argument is an ACME error.
ACME identifier.
  • typ (IdentifierType) --
  • value (str) --
ACME error.

https://datatracker.ietf.org/doc/html/rfc7807

  • typ (str) --
  • title (str) --
  • detail (str) --
  • identifier (Identifier) --
  • subproblems (tuple) -- An array of ACME Errors which may be present when the CA returns multiple errors related to the same request, tuple of Error.
Create an Error instance with an ACME Error code.
An ACME error code, like 'dnssec'.
kwargs to pass to Error.
Hardcoded error description based on its type.
Description if standard ACME error or None.
str
ACME error code.

Basically self.typ without the ERROR_PREFIX.

error code if standard ACME code or None.
str
Represents a class with a resource_type class parameter of type string.
Directory.
Directory Meta.
URL for the CA TOS
Partially serialize.

Following the example, partial serialization means the following:

assert isinstance(Bar().to_partial_json()[0], Foo)
assert isinstance(Bar().to_partial_json()[1], Foo)
# in particular...
assert Bar().to_partial_json() != ['foo', 'foo']
josepy.errors.SerializationError -- in case of any serialization error.
Partially serializable object.
Deserialize a decoded JSON document.
jobj -- Python object, composed of only other basic data types, as decoded from JSON document. Not necessarily dict (as decoded from "JSON object" document).
josepy.errors.DeserializationError -- if decoding was unsuccessful, e.g. in case of unparseable X509 certificate, or wrong padding in JOSE base64 encoded string, etc.
ACME Resource.
body (acme.messages.ResourceBody) -- Resource body.
ACME Resource with URI.
uri (str) -- Location of the resource.
Registration Resource Body.
  • key (jose.JWK) -- Public key.
  • contact (tuple) -- Contact information following ACME spec, tuple of str.
  • agreement (str) --
Create registration resource from contact details.

The contact keyword being passed to a Registration object is meaningful, so this function represents empty iterables in its kwargs by passing on an empty tuple.

Modify josepy.JSONDeserializable.to_partial_json()
Modify josepy.JSONObjectWithFields.fields_to_partial_json()
All phones found in the contact field.
All emails found in the contact field.
Registration Resource.
  • body (acme.messages.Registration) --
  • new_authzr_uri (str) -- Deprecated. Do not use.
  • terms_of_service (str) -- URL for the CA TOS.
Challenge Resource Body.
  • acme.challenges.Challenge -- Wrapped challenge. Conveniently, all challenge fields are proxied, i.e. you can call challb.x to get challb.chall.x contents.
  • status (acme.messages.Status) --
  • validated (datetime.datetime) --
  • error (messages.Error) --
Encode a single field.
name (str) -- Name of the field to be encoded.
  • errors.SerializationError -- if field cannot be serialized
  • errors.Error -- if field could not be found
Partially serialize.

Following the example, partial serialization means the following:

assert isinstance(Bar().to_partial_json()[0], Foo)
assert isinstance(Bar().to_partial_json()[1], Foo)
# in particular...
assert Bar().to_partial_json() != ['foo', 'foo']
josepy.errors.SerializationError -- in case of any serialization error.
Partially serializable object.
The URL of this challenge.
Challenge Resource.
  • body (acme.messages.ChallengeBody) --
  • authzr_uri (str) -- URI found in the 'up' Link header.
The URL of the challenge body.
Authorization Resource Body.
  • identifier (acme.messages.Identifier) --
  • challenges (list) -- list of ChallengeBody
  • combinations (tuple) -- Challenge combinations (tuple of tuple of int, as opposed to list of list from the spec).
  • status (acme.messages.Status) --
  • expires (datetime.datetime) --
Authorization Resource.
  • body (acme.messages.Authorization) --
  • new_cert_uri (str) -- Deprecated. Do not use.
ACME new-cert request.
csr (jose.ComparableX509) -- OpenSSL.crypto.X509Req wrapped in ComparableX509
Certificate Resource.
  • body (josepy.util.ComparableX509) -- OpenSSL.crypto.X509 wrapped in ComparableX509
  • cert_chain_uri (str) -- URI found in the 'up' Link header
  • authzrs (tuple) -- tuple of AuthorizationResource.
Revocation message.
certificate (jose.ComparableX509) -- OpenSSL.crypto.X509 wrapped in jose.ComparableX509
Order Resource Body.
  • identifiers (list of Identifier) -- List of identifiers for the certificate.
  • status (acme.messages.Status) --
  • authorizations (list of str) -- URLs of authorizations.
  • certificate (str) -- URL to download certificate as a fullchain PEM.
  • finalize (str) -- URL to POST to to request issuance once all authorizations have "valid" status.
  • expires (datetime.datetime) -- When the order expires.
  • error (Error) -- Any error that occurred during finalization, if applicable.
Order Resource.
  • body (acme.messages.Order) --
  • csr_pem (bytes) -- The CSR this Order will be finalized with.
  • authorizations (list of acme.messages.AuthorizationResource) -- Fully-fetched AuthorizationResource objects.
  • fullchain_pem (str) -- The fetched contents of the certificate URL produced once the order was finalized, if it's present.
  • alternative_fullchains_pem (list of str) -- The fetched contents of alternative certificate chain URLs produced once the order was finalized, if present and requested during finalization.

Support for standalone client challenge solvers.

Generic TLS Server.
Called by constructor to bind the socket.

May be overridden.

ACME server common settings mixin.
Base class for a pair of IPv6 and IPv4 servers that tries to do everything it's asked for both servers, but where failures in one server don't affect the other.

If two servers are instantiated, they will serve on the same port.

Wraps socketserver.TCPServer.serve_forever
Wraps socketserver.TCPServer.socket.getsockname
Wraps socketserver.TCPServer.shutdown, socketserver.TCPServer.server_close, and threading.Thread.join
HTTP01Server Wrapper. Tries everything for both. Failures for one don't affect the other.
HTTP01 challenge handler.

Adheres to the stdlib's socketserver.BaseRequestHandler interface.

simple_http_resources (set) -- A set of HTTP01Resource objects. TODO: better name?
Alias for field number 0
Alias for field number 1
Alias for field number 2
The default timeout this server should apply to requests. :return: timeout to apply :rtype: int
Handle request.
Handle index page.
Handler 404 Not Found errors.
Handle HTTP01 provisioned resources.
Partially initialize this handler.

This is useful because socketserver.BaseServer takes uninitialized handler and initializes it with the current request.

ACME protocol implementation.

This module is an implementation of the ACME protocol.

  • Index
  • Module Index
  • Search Page

Let's Encrypt Project

2022, Let's Encrypt Project

May 4, 2022 0