# Challenges

ACME Identifier Validation Challenges.

class `acme.challenges.``Challenge`(**kwargs)

  Bases: `josepy.json_util.TypedJSONObjectWithFields`

  ACME challenge.

class `acme.challenges.``ChallengeResponse`(**kwargs)

  Bases: `josepy.json_util.TypedJSONObjectWithFields`

  ACME challenge response.

class `acme.challenges.``UnrecognizedChallenge`(jobj)

  Bases: `acme.challenges.Challenge`

  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.

class `acme.challenges.``_TokenChallenge`(**kwargs)

  Bases: `acme.challenges.Challenge`

  Challenge with token.

  Variables: | token (bytes) –

  `TOKEN_SIZE` = 16.0

    Minimum size of the `token` in bytes.

  `good_token`

    Is `token` good?

    Todo

    acme-spec wants “It MUST NOT contain any non-ASCII characters”, but it should also warrant that it doesn’t contain “..” or “/”…

class `acme.challenges.``KeyAuthorizationChallengeResponse`(*args, **kwargs)

  Bases: `acme.challenges.ChallengeResponse`

  Response to Challenges based on Key Authorization.

  Parameters: | key_authorization (unicode) –

  `verify`(chall, account_public_key)

    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

  `_dump_authorization_key`(dump)

    Set if keyAuthorization is dumped in the JSON representation of this ChallengeResponse. NB: This method is declared as private because it will eventually be removed. :param bool dump: True to dump the keyAuthorization, False otherwise

class `acme.challenges.``KeyAuthorizationChallenge`(**kwargs)

  Bases: `acme.challenges._TokenChallenge`

  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)

    Generate Key Authorization.

    Parameters: | account_key (JWK) –
    Rtype unicode: |

  `response`(account_key)

    Generate response to the challenge.

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

  `validation`(account_key, **kwargs)

    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, *args, **kwargs)

    Generate response and validation.

    Convenience function that return results of `response` and `validation`.

    Parameters: | account_key (JWK) –
    Return type: | tuple

class `acme.challenges.``DNS01Response`(*args, **kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallengeResponse`

  ACME dns-01 challenge response.

  `simple_verify`(chall, domain, account_public_key)

    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)

  Bases: `acme.challenges.KeyAuthorizationChallenge`

  ACME dns-01 challenge.

  `response_cls`

    alias of `DNS01Response`

  `LABEL` = '_acme-challenge'

    Label clients prepend to the domain name being validated.

  `validation`(account_key, **unused_kwargs)

    Generate validation.

    Parameters: | account_key (JWK) –
    Return type: | unicode

  `validation_domain_name`(name)

    Domain name for TXT validation record.

    Parameters: | name (unicode) – Domain name being validated.

class `acme.challenges.``HTTP01Response`(*args, **kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallengeResponse`

  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, domain, account_public_key, port=None)

    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)

  Bases: `acme.challenges.KeyAuthorizationChallenge`

  ACME http-01 challenge.

  `response_cls`

    alias of `HTTP01Response`

  `URI_ROOT_PATH` = '.well-known/acme-challenge'

    URI root path for the server provisioned resource.

  `path`

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

    Return type: | string

  `uri`(domain)

    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, **unused_kwargs)

    Generate validation.

    Parameters: | account_key (JWK) –
    Return type: | unicode

class `acme.challenges.``TLSSNI01Response`(*args, **kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallengeResponse`

  ACME tls-sni-01 challenge response.

  `DOMAIN_SUFFIX` = b'.acme.invalid'

    Domain name suffix.

  `PORT` = 443

    Verification port as defined by the protocol.

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

  `z`

    `z` value used for verification.

    Rtype bytes: |

  `z_domain`

    Domain name used for verification, generated from `z`.

    Rtype bytes: |

  `gen_cert`(key=None, bits=2048)

    Generate tls-sni-01 certificate.

    Parameters:

    - 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, **kwargs)

    Probe tls-sni-01 challenge certificate.

    Parameters: | domain (unicode) –

  `verify_cert`(cert)

    Verify tls-sni-01 challenge certificate.

    Parameters: | cert (OpensSSL.crypto.X509) – Challenge certificate.
    Returns: | Whether the certificate was successfully verified.
    Return type: | bool

  `simple_verify`(chall, domain, account_public_key, cert=None, **kwargs)

    Simple verify.

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

    Parameters:

    - chall (challenges.TLSSNI01) – 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`.
    - port (int) – Port used to probe the certificate.

    Returns: | `True` iff client’s control of the domain has been verified.
    Return type: | bool

class `acme.challenges.``TLSSNI01`(*args, **kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallenge`

  ACME tls-sni-01 challenge.

  `response_cls`

    alias of `TLSSNI01Response`

  `validation`(account_key, **kwargs)

    Generate validation.

    Parameters:

    - account_key (JWK) –
    - 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`

class `acme.challenges.``TLSALPN01Response`(*args, **kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallengeResponse`

  ACME TLS-ALPN-01 challenge response.

  This class only allows initiating a TLS-ALPN-01 challenge returned from the CA. Full support for responding to TLS-ALPN-01 challenges by generating and serving the expected response certificate is not currently provided.

class `acme.challenges.``TLSALPN01`(**kwargs)

  Bases: `acme.challenges.KeyAuthorizationChallenge`

  ACME tls-alpn-01 challenge.

  This class simply allows parsing the TLS-ALPN-01 challenge returned from the CA. Full TLS-ALPN-01 support is not currently provided.

  `response_cls`

    alias of `TLSALPN01Response`

  `validation`(account_key, **kwargs)

    Generate validation for the challenge.

class `acme.challenges.``DNS`(**kwargs)

  Bases: `acme.challenges._TokenChallenge`

  ACME “dns” challenge.

  `LABEL` = '_acme-challenge'

    Label clients prepend to the domain name being validated.

  `gen_validation`(account_key, alg=RS256, **kwargs)

    Generate validation.

    Parameters:

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

    Returns: | This challenge wrapped in `JWS`
    Return type: | JWS

  `check_validation`(validation, account_public_key)

    Check validation.

    Parameters:

    - validation (JWS) –
    - account_public_key (JWK) –

    Return type: | bool

  `gen_response`(account_key, **kwargs)

    Generate response.

    Parameters:

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

    Return type: | DNSResponse

  `validation_domain_name`(name)

    Domain name for TXT validation record.

    Parameters: | name (unicode) – Domain name being validated.

class `acme.challenges.``DNSResponse`(**kwargs)

  Bases: `acme.challenges.ChallengeResponse`

  ACME “dns” challenge response.

  Parameters: | validation (JWS) –

  `check_validation`(chall, account_public_key)

    Check validation.

    Parameters:

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

    Return type: | bool