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