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

ACME AuthHandler.

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.Client*) -- ACME client API.

      * **account** -- Client's Account

      * **authzr** (*dict*) -- ACME Authorization Resource dict
        where keys are domains and values are
        "acme.messages.AuthorizationResource"

      * **achalls** (*list*) -- DV challenges in the form of
        "certbot.achallenges.AnnotatedChallenge"

      * **pref_challs** (*list*) -- sorted user specified preferred
        challenges type strings with the most preferred challenge
        listed first

   get_authorizations(domains, best_effort=False)

      Retrieve all authorizations for challenges.

      Parameters:
         * **domains** (*list*) -- Domains for authorization

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

      Retrieve necessary challenges to satisfy server.

   _solve_challenges()

      Get Responses for challenges from authenticators.

   _respond(resp, best_effort)

      Send/Receive confirmation of all challenges.

      Note: This method also cleans up the auth_handler state.

   _send_responses(achalls, resps, chall_update)

      Send responses and make sure errors are handled.

      Parameters:
         **chall_update** (*dict*) -- parameter that is updated to
         hold authzr -> list of outstanding solved annotated
         challenges

   _poll_challenges(chall_update, best_effort, min_sleep=3, max_rounds=15)

      Wait for all challenge results to be determined.

   _handle_check(domain, 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(achall_list=None)

      Cleanup challenges.

      If achall_list is not provided, cleanup all achallenges.

   verify_authzr_complete()

      Verifies that all authorizations have been decided.

      Returns:
         Whether all authzr are complete

      Return type:
         bool

   _challenge_factory(domain, path)

      Construct Namedtuple Challenges

      Parameters:
         * **domain** (*str*) -- domain of the enrollee

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

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

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
