"certbot.auth_handler"
**********************

ACME AuthHandler.

class certbot.auth_handler.AnnotatedAuthzr(authzr, achalls)

   Bases: "tuple"

   Stores an authorization resource and its active annotated
   challenges.

   _asdict()

      Return a new OrderedDict which maps field names to their values

   classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

      Make a new AnnotatedAuthzr object from a sequence or iterable

   _replace(**kwds)

      Return a new AnnotatedAuthzr object replacing specified fields
      with new values

   achalls

      Alias for field number 1

   authzr

      Alias for field number 0

class certbot.auth_handler.AuthHandler(auth, acme, account, pref_challs)

   Bases: "object"

   ACME Authorization Handler for a client.

   Variables:
      * **auth** – Authenticator capable of solving "Challenge"
        types

      * **acme** (*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)

      Retrieve all authorizations for challenges.

      Parameters:
         * **orderr** (*acme.messages.OrderResource*) – must have
           authorizations filled in

         * **best_effort** (*bool*) – Whether or not all
           authorizations are required (this is useful in renewal)

      Returns:
         List of authorization resources

      Return type:
         list

      Raises:
         **AuthorizationError** – If unable to retrieve all
         authorizations

   _choose_challenges(aauthzrs)

      Retrieve necessary challenges to satisfy server.

   _has_challenges(aauthzrs)

      Do we have any challenges to perform?

   _solve_challenges(aauthzrs)

      Get Responses for challenges from authenticators.

   _get_all_achalls(aauthzrs)

      Return all active challenges.

   _respond(aauthzrs, resp, best_effort)

      Send/Receive confirmation of all challenges.

      Note: This method also cleans up the auth_handler state.

   _send_responses(aauthzrs, resps, chall_update)

      Send responses and make sure errors are handled.

      Parameters:
         * **aauthzrs** ("list" of "AnnotatedAuthzr") –
           authorizations and the selected annotated challenges to try
           and perform

         * **resps** ("collections.abc.Iterable" of
           "ChallengeResponse" or "False" or "None") – challenge
           responses from the authenticator where each response at
           index i corresponds to the annotated challenge at index i
           in the list returned by "_get_all_achalls()"

         * **chall_update** (*dict*) – parameter that is updated to
           hold aauthzr index to list of outstanding solved annotated
           challenges

   _poll_challenges(aauthzrs, chall_update, best_effort, min_sleep=3, max_rounds=30)

      Wait for all challenge results to be determined.

   _handle_check(aauthzrs, index, achalls)

      Returns tuple of (‘completed’, ‘failed’).

   _find_updated_challb(authzr, achall)

      Find updated challenge body within Authorization Resource.

      Warning: This assumes only one instance of type of challenge
        in each challenge resource.

      Parameters:
         * **authzr** (*AuthorizationResource*) – Authorization
           Resource

         * **achall** (*AnnotatedChallenge*) – Annotated challenge
           for which to get status

   _get_chall_pref(domain)

      Return list of challenge preferences.

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

   _cleanup_challenges(aauthzrs, achalls=None)

      Cleanup challenges.

      Parameters:
         * **aauthzrs** ("list" of "AnnotatedAuthzr") –
           authorizations and their selected annotated challenges

         * **achalls** ("list" of
           "certbot.achallenges.AnnotatedChallenge") – annotated
           challenges to cleanup

   verify_authzr_complete(aauthzrs)

      Verifies that all authorizations have been decided.

      Parameters:
         **aauthzrs** ("list" of "AnnotatedAuthzr") – authorizations
         and their selected annotated challenges

      Returns:
         Whether all authzr are complete

      Return type:
         bool

   _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_challs(failed_achalls)

   Notifies the user about failed challenges.

   Parameters:
      **failed_achalls** (*set*) – A set of failed
      "certbot.achallenges.AnnotatedChallenge".

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
