ACME AuthHandler.

class certbot.auth_handler.AnnotatedAuthzr(authzr, achalls)

Bases: tuple

Stores an authorization resource and its active annotated challenges.


Return a new OrderedDict which maps field names to their values

classmethod _make(iterable, new=<built-in method __new__ of type object at 0x906d60>, 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


Alias for field number 1


Alias for field number 0

class certbot.auth_handler.AuthHandler(auth, acme, account, pref_challs)[source]

Bases: object

ACME Authorization Handler for a client.

  • 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.

  • orderr (acme.messages.OrderResource) – must have authorizations filled in
  • best_effort (bool) – Whether or not all authorizations are required (this is useful in renewal)

List of authorization resources

Return type:



AuthorizationError – If unable to retrieve all authorizations


Retrieve necessary challenges to satisfy server.


Do we have any challenges to perform?


Get Responses for challenges from authenticators.


Return all active challenges.

_respond(aauthzrs, resp, best_effort)[source]

Send/Receive confirmation of all challenges.


This method also cleans up the auth_handler state.

_send_responses(aauthzrs, resps, chall_update)[source]

Send responses and make sure errors are handled.

  • 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)[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.


This assumes only one instance of type of challenge in each challenge resource.

  • authzr (AuthorizationResource) – Authorization Resource
  • achall (AnnotatedChallenge) – Annotated challenge for which to get status

Return list of challenge preferences.

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

Cleanup challenges.


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

  • authzr (messages.AuthorizationResource) – authorization
  • path (list) – List of indices from challenges.

achalls, list of challenge type certbot.achallenges.Indexed

Return type:



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.

  • challb (ChallengeBody) – ChallengeBody
  • account_key (JWK) – Authorized Account Key
  • domain (str) – Domain of the challb

Appropriate AnnotatedChallenge

Return type:


certbot.auth_handler.gen_challenge_path(challbs, preferences, combinations)[source]

Generate a plan to get authority over the identity.


This can be possibly be rewritten to use resolved_combinations.

  • 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.

tuple of indices from challenges.

Return type:



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.


Logs and raises an error that no satisfiable chall path exists.

Parameters:challbs – challenges from the authorization that can’t be satisfied

Notifies the user about failed challenges.

Parameters:failed_achalls (set) – A set of failed certbot.achallenges.AnnotatedChallenge.

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