certwrangler.controllers module

This module handles all the logic around interacting with the ACME server and processing ACME orders. It is highly recommended to read and understand RFC 8555 before making changes to this code.

class certwrangler.controllers.AccountKeyChangeMessage(**kwargs: Any)

Bases: ResourceBody

Account Key change message since the acme library doesn’t seem to have this.

oldKey: JWK

The old public key.

account: str

The URI of the account.

_fields

_orig_slots

certwrangler.controllers._get_acme_client(account: Account) → ClientV2

Creates an ACME client based on the key in the provided Account’s state.

Parameters:

account – The account object that the client will be created for.

Returns:

An ACME client object.

Raises:

ControllerError – Raised if no account key is in the state.

class certwrangler.controllers.AccountController(account: Account, state_manager: StateManager)

Bases: object

Controller for ACME account operations.

Parameters:

• account – The account object that the controller will operate on.

• state_manager – The state manager object the controller will persist state to.

property client: ClientV2

Lazy loader for the ACME client.

create_key() → None

Create a new key and reset the account state.

register() → None

Register a new account.

get_registration() → None

Get registration for an existing account.

change_key() → None

Change the account key.

Raises:

ControllerError – Raised if no registration is in the state or if we get an invalid response from the ACME server.

update_contacts() → None

Update the contact information on the account.

Raises:

ControllerError – Raised if no registration is in the state.

class certwrangler.controllers.CertController(cert: Cert, state_manager: StateManager)

Bases: object

Controller for ACME cert operations.

Parameters:

• cert – The cert object that the controller will operate on.

• state_manager – The state manager object the controller will persist state to.

property client: ClientV2

Lazy loader for the ACME client.

create_key() → None

Create a new key and reset the cert state.

create_order() → None

Create a new CSR and submit an order request, then continue onto process_order().

process_order() → None

Get the latest state of the order from the ACME server and process it based on the order’s state:

STATUS_PENDING:

Process any outstanding challenges with process_challenges().

STATUS_READY:

Finalize the order with finalize_order().

STATUS_PROCESSING or STATUS_VALID:

retrieve the cert with retrieve_cert().

STATUS_INVALID:

collect any error messages from the challenges and _fail_order().

ELSE:

We shouldn’t end up here, provide a less helpful error message and _fail_order().

Raises:

ControllerError – Raised if no order is in the state.

process_challenges() → None

Loops through the DNS challenges on the order and do the following:

1. Create the requested TXT records using the solver for that zone.

2. Wait until specified timeout for the records to resolve.

3. Submit the challenges to the ACME server for authorization.

4. Poll the ACME server for its validation.

Once all that is complete, proceeds to finalize_order().

Raises:

ControllerError – Raised if no order is in the state, if we hit a timeout, if we failed validation from the ACME server, or can be raised from certwrangler.exceptions.SolverError if a solver encounters a problem creating a DNS record.

finalize_order() → None

Submits the order to the ACME server for finalization, then continues onto retrieve_cert().

Raises:

ControllerError – Raised if no order is in the state.

retrieve_cert() → None

Poll the order for finalization, then download and saves the cert to the Cert object’s state. Continues onto clean_up().

Raises:

ControllerError – Raised if no order is in the state.

clean_up() → None

Cleans up any TXT records we created then reset the order state.

Raises:

ControllerError – Raised from certwrangler.exceptions.SolverError if any of the solvers encounter errors deleting the TXT records.

publish() → None

Publish the cert to the stores.

Raises:

ControllerError – Raised from certwrangler.exceptions.StoreError if any of the stores encounter errors publishing the cert.

_create_csr() → CertificateSigningRequest

Creates a CSR for the order.

Raises:

ControllerError – Raised if no private key is in the state.

_update_order() → None

Update the order status from the server in case it changed.

Raises:

ControllerError – Raised if no order is in the state.

_validate_authorizations() → None

Validates the authorizations on the order. Continues onto _fail_order() if any authorizations are in the following statuses:

• STATUS_DEACTIVATED

• STATUS_REVOKED

• STATUS_UNKNOWN

Raises:

ControllerError – Raised if no order is in the state.

_get_challenges(validate: bool = True, completed: bool = False) → List[Tuple[str, ChallengeBody]]

Extracts the DNS challenges from the order.

Parameters:

• validate – Whether to verify the authorizations are in a valid state. If not, the order is failed.

• completed – Whether to return already completed challenges.

Returns:

A list of tuples containing (domain, acme.messages.ChallengeBody).

Raises:

ControllerError – Raised if no order is in the state.

_get_dns_records(validate: bool = True, completed: bool = False) → List[Tuple[str, str, str, Solver]]

Compiles and returns the parts of a DNS records and associated certwrangler.models.Solver instances for each of the challenges.

Parameters:

• validate – Whether to verify the authorizations are in a valid state. If not, the order is failed.

• completed – Whether to return already completed challenges.

Returns:

A list of tuples containing the name of the record, the DNS zone, the value of the TXT record, and the certwrangler.models.Solver associated with the zone for each challenge on the order.

Raises:

ControllerError – Raised if errors are encountered resolving DNS or if a certwrangler.models.Solver isn’t found for the zone.

_fail_order(error: Exception | str | None = None) → None

Cleans up any resources created as part of processing the order and removes the order from the cert’s state.

Parameters:

error – Optional error message or exception.

Raises:

ControllerError – Raised after cleanup is performed. A message can be provided with the optional error parameter.