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 (set) – 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.HTTP01'>, <class 'acme.challenges.TLSSNI01'>])]))

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