# `letsencrypt.auth_handler`

ACME AuthHandler.

class `letsencrypt.auth_handler.``AuthHandler`(dv_auth, cont_auth, acme, account)

  Bases: `object`

  ACME Authorization Handler for a client.

  Variables:

  - dv_auth – Authenticator capable of solving `DVChallenge` types
  - cont_auth – Authenticator capable of solving `ContinuityChallenge` 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`
  - dv_c (list) – DV challenges in the form of `letsencrypt.achallenges.AnnotatedChallenge`
  - cont_c (list) – Continuity challenges in the form of `letsencrypt.achallenges.AnnotatedChallenge`

  `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: | tuple of lists of authorization resources. Takes the form of (`completed`, `failed`)
    Return type: | tuple
    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`(cont_resp, dv_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: | dv_chall, list of DVChallenge type `letsencrypt.achallenges.Indexed` cont_chall, list of ContinuityChallenge type `letsencrypt.achallenges.Indexed`
    Return type: | tuple
    Raises: | .errors.Error – if challenge type is not recognized

`letsencrypt.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: | `letsencrypt.achallenges.AnnotatedChallenge`

`letsencrypt.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: | letsencrypt.errors.AuthorizationError – If a path cannot be created that satisfies the CA given the preferences and combinations.

`letsencrypt.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.

`letsencrypt.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 returns the best path that does not contain multiple mutually exclusive challenges.

`letsencrypt.auth_handler.``mutually_exclusive`(obj1, obj2, groups, different=False)

  Are two objects mutually exclusive?

`letsencrypt.auth_handler.``is_preferred`(offered_challb, satisfied, exclusive_groups=frozenset([frozenset([<class 'acme.challenges.TLSSNI01'>, <class 'acme.challenges.HTTP01'>])]))

  Return whether or not the challenge is preferred in path.

`letsencrypt.auth_handler.``_report_failed_challs`(failed_achalls)

  Notifies the user about failed challenges.

  Parameters: | failed_achalls (set) – A set of failed `letsencrypt.achallenges.AnnotatedChallenge`.

`letsencrypt.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 `letsencrypt.achallenges.AnnotatedChallenge` with the same error type.
  Returns: | A formatted error message for the client.
  Return type: | str