# `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 at 0x9e3040>, len=<built-in function len>)

    Make a new AnnotatedAuthzr object from a sequence or iterable

  `_replace`(_self, **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=15)

    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