Challenges¶

ACME Identifier Validation Challenges.

class acme.challenges.Challenge(**kwargs: Any)[source]¶

ACME challenge.

TYPES: Dict[str, Type[Challenge]] = {'dns': <class 'acme.challenges.DNS'>, 'dns-01': <class 'acme.challenges.DNS01'>, 'http-01': <class 'acme.challenges.HTTP01'>, 'tls-alpn-01': <class 'acme.challenges.TLSALPN01'>}¶: Types registered for JSON deserialization

classmethod from_json(jobj: Mapping[str, Any]) → Union[GenericChallenge, UnrecognizedChallenge][source]¶

Deserialize ACME object from valid JSON object.

Raises: josepy.errors.UnrecognizedTypeError – if type of the ACME object has not been registered.

class acme.challenges.ChallengeResponse(**kwargs: Any)[source]¶

ACME challenge response.

TYPES: Dict[str, Type[ChallengeResponse]] = {'dns': <class 'acme.challenges.DNSResponse'>, 'dns-01': <class 'acme.challenges.DNS01Response'>, 'http-01': <class 'acme.challenges.HTTP01Response'>, 'tls-alpn-01': <class 'acme.challenges.TLSALPN01Response'>}¶: Types registered for JSON deserialization

to_partial_json() → Dict[str, Any][source]¶

Get JSON serializable object.

Returns: Serializable JSON object representing ACME typed object. validate() will almost certainly not work, due to reasons explained in josepy.interfaces.IJSONSerializable.
Return type: dict

class acme.challenges.UnrecognizedChallenge(jobj: Mapping[str, Any])[source]¶

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.

Variables: jobj – Original JSON decoded object.

to_partial_json() → Dict[str, Any][source]¶

Get JSON serializable object.

Returns: Serializable JSON object representing ACME typed object. validate() will almost certainly not work, due to reasons explained in josepy.interfaces.IJSONSerializable.
Return type: dict

classmethod from_json(jobj: Mapping[str, Any]) → UnrecognizedChallenge[source]¶

Deserialize ACME object from valid JSON object.

Raises: josepy.errors.UnrecognizedTypeError – if type of the ACME object has not been registered.

class acme.challenges.KeyAuthorizationChallengeResponse(**kwargs: Any)[source]¶

Response to Challenges based on Key Authorization.

Parameters: key_authorization (str) –

verify(chall: KeyAuthorizationChallenge, account_public_key: JWK) → bool[source]¶

Verify the key authorization.

Parameters

chall (KeyAuthorization) – Challenge that corresponds to this response.
account_public_key (JWK) –

Returns

True iff verification of the key authorization was successful.

Return type

bool

to_partial_json() → Dict[str, Any][source]¶

Get JSON serializable object.

Returns: Serializable JSON object representing ACME typed object. validate() will almost certainly not work, due to reasons explained in josepy.interfaces.IJSONSerializable.
Return type: dict

class acme.challenges.KeyAuthorizationChallenge(**kwargs: Any)[source]¶

Challenge based on Key Authorization.

Parameters

response_cls – Subclass of KeyAuthorizationChallengeResponse that will be used to generate response.
typ (str) – type of the challenge

typ: str = NotImplemented¶: Type of the object. Subclasses must override.

key_authorization(account_key: JWK) → str[source]¶

Generate Key Authorization.

Parameters: account_key (JWK) –
Rtype str

response(account_key: JWK) → KeyAuthorizationChallengeResponse[source]¶

Generate response to the challenge.

Parameters: account_key (JWK) –
Returns: Response (initialized response_cls) to the challenge.
Return type: KeyAuthorizationChallengeResponse

abstract validation(account_key: JWK, **kwargs: Any) → Any[source]¶

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.

Parameters: account_key (JWK) –
Returns: Challenge-specific validation.

response_and_validation(account_key: JWK, *args: Any, **kwargs: Any) → Tuple[KeyAuthorizationChallengeResponse, Any][source]¶

Generate response and validation.

Convenience function that return results of response and validation.

Parameters: account_key (JWK) –
Return type: tuple

class acme.challenges.DNS01Response(**kwargs: Any)[source]¶

ACME dns-01 challenge response.

typ: str = 'dns-01'¶: Type of the object. Subclasses must override.

simple_verify(chall: DNS01, domain: str, account_public_key: JWK) → bool[source]¶

Simple verify.

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

Parameters

chall (challenges.DNS01) – Corresponding challenge.
domain (str) – Domain name being verified.
account_public_key (JWK) – Public key for the key pair being authorized.

Returns

True iff verification of the key authorization was successful.

Return type

bool

class acme.challenges.DNS01(**kwargs: Any)[source]¶

ACME dns-01 challenge.

response_cls¶: alias of DNS01Response

typ: str = 'dns-01'¶: Type of the object. Subclasses must override.

LABEL = '_acme-challenge'¶: Label clients prepend to the domain name being validated.

validation(account_key: JWK, **unused_kwargs: Any) → str[source]¶

Generate validation.

Parameters: account_key (JWK) –
Return type: str

validation_domain_name(name: str) → str[source]¶

Domain name for TXT validation record.

Parameters: name (str) – Domain name being validated.
Return type: str

class acme.challenges.HTTP01Response(**kwargs: Any)[source]¶

ACME http-01 challenge response.

typ: str = 'http-01'¶: Type of the object. Subclasses must override.

PORT = 80¶

Verification port as defined by the protocol.

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

WHITESPACE_CUTSET = '\n\r\t '¶: Whitespace characters which should be ignored at the end of the body.

simple_verify(chall: HTTP01, domain: str, account_public_key: JWK, port: Optional[int] = None, timeout: int = 30) → bool[source]¶

Simple verify.

Parameters

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.
timeout (int) – Timeout in seconds.

Returns

True iff validation with the files currently served by the HTTP server is successful.

Return type

bool

class acme.challenges.HTTP01(**kwargs: Any)[source]¶

ACME http-01 challenge.

response_cls¶: alias of HTTP01Response

typ: str = 'http-01'¶: Type of the object. Subclasses must override.

URI_ROOT_PATH = '.well-known/acme-challenge'¶: URI root path for the server provisioned resource.

property path: str¶

Path (starting with ‘/’) for provisioned resource.

Return type: str

uri(domain: str) → str[source]¶

Create an URI to the provisioned resource.

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

Parameters: domain (str) – Domain name being verified.
Return type: str

validation(account_key: JWK, **unused_kwargs: Any) → str[source]¶

Generate validation.

Parameters: account_key (JWK) –
Return type: str

class acme.challenges.TLSALPN01Response(**kwargs: Any)[source]¶

ACME tls-alpn-01 challenge response.

typ: str = 'tls-alpn-01'¶: Type of the object. Subclasses must override.

PORT = 443¶

Verification port as defined by the protocol.

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

property h: bytes¶: Hash value stored in challenge certificate

gen_cert(domain: str, key: Optional[PKey] = None, bits: int = 2048) → Tuple[X509, PKey][source]¶

Generate tls-alpn-01 certificate.

Parameters

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.

Return type

tuple of OpenSSL.crypto.X509 and OpenSSL.crypto.PKey

probe_cert(domain: str, host: Optional[str] = None, port: Optional[int] = None) → X509[source]¶

Probe tls-alpn-01 challenge certificate.

Parameters

domain (str) – domain being validated, required.
host (str) – IP address used to probe the certificate.
port (int) – Port used to probe the certificate.

verify_cert(domain: str, cert: X509) → bool[source]¶

Verify tls-alpn-01 challenge certificate.

Parameters

domain (str) – Domain name being validated.
cert (OpensSSL.crypto.X509) – Challenge certificate.

Returns

Whether the certificate was successfully verified.

Return type

bool

simple_verify(chall: TLSALPN01, domain: str, account_public_key: JWK, cert: Optional[X509] = None, host: Optional[str] = None, port: Optional[int] = None) → bool[source]¶

Simple verify.

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

Parameters

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.

Returns

True if and only if client’s control of the domain has been verified.

Return type

bool

class acme.challenges.TLSALPN01(**kwargs: Any)[source]¶

ACME tls-alpn-01 challenge.

response_cls¶: alias of TLSALPN01Response

typ: str = 'tls-alpn-01'¶: Type of the object. Subclasses must override.

validation(account_key: JWK, **kwargs: Any) → Tuple[X509, PKey][source]¶

Generate validation.

Parameters

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.

Return type

tuple of OpenSSL.crypto.X509 and OpenSSL.crypto.PKey

static is_supported() → bool[source]¶

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.

Returns: True if TLS-ALPN-01 is supported on this machine, False otherwise.
Return type: bool

class acme.challenges.DNS(**kwargs: Any)[source]¶

ACME “dns” challenge.

typ: str = 'dns'¶: Type of the object. Subclasses must override.

LABEL = '_acme-challenge'¶: Label clients prepend to the domain name being validated.

gen_validation(account_key: JWK, alg: JWASignature = RS256, **kwargs: Any) → JWS[source]¶

Generate validation.

Parameters

account_key (.JWK) – Private account key.
alg (.JWA) –

Returns

This challenge wrapped in JWS

Return type

.JWS

check_validation(validation: JWS, account_public_key: JWK) → bool[source]¶

Check validation.

Parameters

validation (JWS) –
account_public_key (JWK) –

Return type

bool

gen_response(account_key: JWK, **kwargs: Any) → DNSResponse[source]¶

Generate response.

Parameters

account_key (.JWK) – Private account key.
alg (.JWA) –

Return type

DNSResponse

validation_domain_name(name: str) → str[source]¶

Domain name for TXT validation record.

Parameters: name (str) – Domain name being validated.

class acme.challenges.DNSResponse(**kwargs: Any)[source]¶

ACME “dns” challenge response.

Parameters: validation (JWS) –

typ: str = 'dns'¶: Type of the object. Subclasses must override.

check_validation(chall: DNS, account_public_key: JWK) → bool[source]¶

Check validation.

Parameters

chall (challenges.DNS) –
account_public_key (JWK) –

Return type

bool