ACME AuthHandler.

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

Bases: object

ACME Authorization Handler for a client.

handle_authorizations(orderr, best_effort=False, max_retries=30)[source]

Retrieve all authorizations, perform all challenges required to validate these authorizations, then poll and wait for the authorization to be checked. :param acme.messages.OrderResource orderr: must have authorizations filled in :param bool best_effort: if True, not all authorizations need to be validated (eg. renew) :param int max_retries: maximum number of retries to poll authorizations :returns: list of all validated authorizations :rtype: List

Raises:AuthorizationError – If unable to retrieve all authorizations
_poll_authorizations(authzrs, max_retries, best_effort)[source]

Poll the ACME CA server, to wait for confirmation that authorizations have their challenges all verified. The poll may occur several times, until all authorizations are checked (valid or invalid), or after a maximum of retries.


Retrieve necessary and pending challenges to satisfy server. NB: Necessary and already validated challenges are not retrieved, as they can be reused for a certificate issuance.


Return list of challenge preferences.

Parameters:domain (str) – domain for which you are requesting preferences

Cleanup challenges.

Parameters:achalls (list of certbot.achallenges.AnnotatedChallenge) – annotated challenges to cleanup
_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
certbot.auth_handler._report_failed_authzrs(failed_authzrs, account_key)[source]

Notifies the user about failed authorizations.


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