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 0x8f9920>, 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)[source]

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)[source]

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)[source]

Retrieve necessary challenges to satisfy server.

_has_challenges(aauthzrs)[source]

Do we have any challenges to perform?

_solve_challenges(aauthzrs)[source]

Get Responses for challenges from authenticators.

_get_all_achalls(aauthzrs)[source]

Return all active challenges.

_respond(aauthzrs, resp, best_effort)[source]

Send/Receive confirmation of all challenges.

Note

This method also cleans up the auth_handler state.

_send_responses(aauthzrs, resps, chall_update)[source]

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=30)[source]

Wait for all challenge results to be determined.

_handle_check(aauthzrs, index, achalls)[source]

Returns tuple of (‘completed’, ‘failed’).

_find_updated_challb(authzr, achall)[source]

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)[source]

Return list of challenge preferences.

Parameters:domain (str) – domain for which you are requesting preferences
_cleanup_challenges(aauthzrs, achalls=None)[source]

Cleanup challenges.

Parameters:
verify_authzr_complete(aauthzrs)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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