# Challenges

ACME Identifier Validation Challenges.

class acme.challenges.Challenge(**kwargs: Any)

  ACME challenge.

  classmethod from_json(jobj: Mapping[str, Any]) → acme.challenges.Challenge

    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)

  ACME challenge response.

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

  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]

    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]) → acme.challenges.UnrecognizedChallenge

    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)

  Response to Challenges based on Key Authorization.

  Parameters

    key_authorization (unicode) –

  verify(chall: acme.challenges.KeyAuthorizationChallenge, account_public_key: josepy.jwk.JWK) → bool

    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]

    See josepy.JSONDeserializable.to_partial_json()

class acme.challenges.KeyAuthorizationChallenge(**kwargs: Any)

  Challenge based on Key Authorization.

  Parameters

    - response_cls – Subclass of `KeyAuthorizationChallengeResponse` that will be used to generate `response`.

    - typ (str) – type of the challenge

  key_authorization(account_key: josepy.jwk.JWK) → str

    Generate Key Authorization.

    Parameters

      account_key (JWK) –

    Rtype unicode

  response(account_key: josepy.jwk.JWK) → acme.challenges.KeyAuthorizationChallengeResponse

    Generate response to the challenge.

    Parameters

      account_key (JWK) –

    Returns

      Response (initialized `response_cls`) to the challenge.

    Return type

      KeyAuthorizationChallengeResponse

  abstract validation(account_key: josepy.jwk.JWK, **kwargs: Any) → Any

    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: josepy.jwk.JWK, *args: Any, **kwargs: Any) → Tuple[acme.challenges.KeyAuthorizationChallengeResponse, Any]

    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)

  ACME dns-01 challenge response.

  simple_verify(chall: acme.challenges.DNS01, domain: str, account_public_key: josepy.jwk.JWK) → bool

    Simple verify.

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

    Parameters

      - chall (challenges.DNS01) – Corresponding challenge.

      - domain (unicode) – 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)

  ACME dns-01 challenge.

  response_cls

    alias of `acme.challenges.DNS01Response`

  LABEL = '_acme-challenge'

    Label clients prepend to the domain name being validated.

  validation(account_key: josepy.jwk.JWK, **unused_kwargs: Any) → str

    Generate validation.

    Parameters

      account_key (JWK) –

    Return type

      unicode

  validation_domain_name(name: str) → str

    Domain name for TXT validation record.

    Parameters

      name (unicode) – Domain name being validated.

class acme.challenges.HTTP01Response(**kwargs: Any)

  ACME http-01 challenge response.

  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: acme.challenges.HTTP01, domain: str, account_public_key: josepy.jwk.JWK, port: Optional[int] = None) → bool

    Simple verify.

    Parameters

      - chall (challenges.SimpleHTTP) – Corresponding challenge.

      - domain (unicode) – Domain name being verified.

      - account_public_key (JWK) – Public key for the key pair being authorized.

      - port (int) – Port used in the validation.

    Returns

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

    Return type

      bool

class acme.challenges.HTTP01(**kwargs: Any)

  ACME http-01 challenge.

  response_cls

    alias of `acme.challenges.HTTP01Response`

  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

      string

  uri(domain: str) → str

    Create an URI to the provisioned resource.

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

    Parameters

      domain (unicode) – Domain name being verified.

    Return type

      string

  validation(account_key: josepy.jwk.JWK, **unused_kwargs: Any) → str

    Generate validation.

    Parameters

      account_key (JWK) –

    Return type

      unicode

class acme.challenges.TLSALPN01Response(**kwargs: Any)

  ACME tls-alpn-01 challenge response.

  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[OpenSSL.crypto.PKey] = None, bits: int = 2048) → Tuple[OpenSSL.crypto.X509, OpenSSL.crypto.PKey]

    Generate tls-alpn-01 certificate.

    Parameters

      - domain (unicode) – 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) → OpenSSL.crypto.X509

    Probe tls-alpn-01 challenge certificate.

    Parameters

      - domain (unicode) – domain being validated, required.

      - host (string) – IP address used to probe the certificate.

      - port (int) – Port used to probe the certificate.

  verify_cert(domain: str, cert: OpenSSL.crypto.X509) → bool

    Verify tls-alpn-01 challenge certificate.

    Parameters

      - domain (unicode) – Domain name being validated.

      - cert (OpensSSL.crypto.X509) – Challenge certificate.

    Returns

      Whether the certificate was successfully verified.

    Return type

      bool

  simple_verify(chall: acme.challenges.TLSALPN01, domain: str, account_public_key: josepy.jwk.JWK, cert: Optional[OpenSSL.crypto.X509] = None, host: Optional[str] = None, port: Optional[int] = None) → bool

    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)

  ACME tls-alpn-01 challenge.

  response_cls

    alias of `acme.challenges.TLSALPN01Response`

  validation(account_key: josepy.jwk.JWK, **kwargs: Any) → Tuple[OpenSSL.crypto.X509, OpenSSL.crypto.PKey]

    Generate validation.

    Parameters

      - account_key (JWK) –

      - domain (unicode) – 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

    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)

  ACME “dns” challenge.

  LABEL = '_acme-challenge'

    Label clients prepend to the domain name being validated.

  gen_validation(account_key: josepy.jwk.JWK, alg: josepy.jwa.JWASignature = RS256, **kwargs: Any) → josepy.jws.JWS

    Generate validation.

    Parameters

      - account_key (JWK) – Private account key.

      - alg (JWA) –

    Returns

      This challenge wrapped in `JWS`

    Return type

      JWS

  check_validation(validation: josepy.jws.JWS, account_public_key: josepy.jwk.JWK) → bool

    Check validation.

    Parameters

      - validation (JWS) –

      - account_public_key (JWK) –

    Return type

      bool

  gen_response(account_key: josepy.jwk.JWK, **kwargs: Any) → acme.challenges.DNSResponse

    Generate response.

    Parameters

      - account_key (JWK) – Private account key.

      - alg (JWA) –

    Return type

      DNSResponse

  validation_domain_name(name: str) → str

    Domain name for TXT validation record.

    Parameters

      name (unicode) – Domain name being validated.

class acme.challenges.DNSResponse(**kwargs: Any)

  ACME “dns” challenge response.

  Parameters

    validation (JWS) –

  check_validation(chall: acme.challenges.DNS, account_public_key: josepy.jwk.JWK) → bool

    Check validation.

    Parameters

      - chall (challenges.DNS) –

      - account_public_key (JWK) –

    Return type

      bool