# `certbot.auth_handler`

ACME AuthHandler.

class `certbot.auth_handler.``AuthHandler`(auth, acme_client, account, pref_challs)

  Bases: `object`

  ACME Authorization Handler for a client.

  Variables:

  - auth – Authenticator capable of solving `Challenge` types
  - acme_client (acme.client.BackwardsCompatibleClientV2) – ACME client API.
  - account – Client’s Account
  - pref_challs (list) – sorted user specified preferred challenges type strings with the most preferred challenge listed first

  `handle_authorizations`(orderr, best_effort=False, max_retries=30)

    Retrieve all authorizations, perform all challenges required to validate these authorizations, then poll and wait for the authorization to be checked. :param acme.messages.OrderResource orderr: must have authorizations filled in :param bool best_effort: if True, not all authorizations need to be validated (eg. renew) :param int max_retries: maximum number of retries to poll authorizations :returns: list of all validated authorizations :rtype: List

    Raises: | AuthorizationError – If unable to retrieve all authorizations

  `deactivate_valid_authorizations`(orderr)

    Deactivate all `valid` authorizations in the order, so that they cannot be re-used in subsequent orders. :param messages.OrderResource orderr: must have authorizations filled in :returns: tuple of list of successfully deactivated authorizations, and

    > list of unsuccessfully deactivated authorizations.

    Return type: | tuple

  `_poll_authorizations`(authzrs, max_retries, best_effort)

    Poll the ACME CA server, to wait for confirmation that authorizations have their challenges all verified. The poll may occur several times, until all authorizations are checked (valid or invalid), or after a maximum of retries.

  `_choose_challenges`(authzrs)

    Retrieve necessary and pending challenges to satisfy server. NB: Necessary and already validated challenges are not retrieved, as they can be reused for a certificate issuance.

  `_get_chall_pref`(domain)

    Return list of challenge preferences.

    Parameters: | domain (str) – domain for which you are requesting preferences

  `_cleanup_challenges`(achalls)

    Cleanup challenges.

    Parameters: | achalls (`list` of `certbot.achallenges.AnnotatedChallenge`) – annotated challenges to cleanup

  `_challenge_factory`(authzr, path)

    Construct Namedtuple Challenges

    Parameters:

    - authzr (messages.AuthorizationResource) – authorization
    - path (list) – List of indices from `challenges`.

    Returns: | achalls, list of challenge type `certbot.achallenges.Indexed`
    Return type: | list
    Raises: | errors.Error – if challenge type is not recognized

`certbot.auth_handler.``challb_to_achall`(challb, account_key, domain)

  Converts a ChallengeBody object to an AnnotatedChallenge.

  Parameters:

  - challb (ChallengeBody) – ChallengeBody
  - account_key (JWK) – Authorized Account Key
  - domain (str) – Domain of the challb

  Returns: | Appropriate AnnotatedChallenge
  Return type: | `certbot.achallenges.AnnotatedChallenge`

`certbot.auth_handler.``gen_challenge_path`(challbs, preferences, combinations)

  Generate a plan to get authority over the identity.

  Todo

  This can be possibly be rewritten to use resolved_combinations.

  Parameters:

  - challbs (tuple) – A tuple of challenges (`acme.messages.Challenge`) from `acme.messages.AuthorizationResource` to be fulfilled by the client in order to prove possession of the identifier.
  - preferences (list) – List of challenge preferences for domain (`acme.challenges.Challenge` subclasses)
  - combinations (tuple) – A collection of sets of challenges from `acme.messages.Challenge`, each of which would be sufficient to prove possession of the identifier.

  Returns: | tuple of indices from `challenges`.
  Return type: | tuple
  Raises: | certbot.errors.AuthorizationError – If a path cannot be created that satisfies the CA given the preferences and combinations.

`certbot.auth_handler.``_find_smart_path`(challbs, preferences, combinations)

  Find challenge path with server hints.

  Can be called if combinations is included. Function uses a simple ranking system to choose the combo with the lowest cost.

`certbot.auth_handler.``_find_dumb_path`(challbs, preferences)

  Find challenge path without server hints.

  Should be called if the combinations hint is not included by the server. This function either returns a path containing all challenges provided by the CA or raises an exception.

`certbot.auth_handler.``_report_no_chall_path`(challbs)

  Logs and raises an error that no satisfiable chall path exists.

  Parameters: | challbs – challenges from the authorization that can’t be satisfied

`certbot.auth_handler.``_report_failed_authzrs`(failed_authzrs, account_key)

  Notifies the user about failed authorizations.

`certbot.auth_handler.``_generate_failed_chall_msg`(failed_achalls)

  Creates a user friendly error message about failed challenges.

  Parameters: | failed_achalls (list) – A list of failed `certbot.achallenges.AnnotatedChallenge` with the same error type.
  Returns: | A formatted error message for the client.
  Return type: | str