Models¶

Data models representing ACME protocol objects.

Account¶

class acmeow.Account[source]¶

Bases: object

ACME account management.

Handles account creation, key management, and persistence of account data to disk. Account keys use EC P-256 (SECP256R1) as recommended by the ACME specification.

Parameters:

email (str) – Account email address.
storage_path (Path) – Base directory for storing account data.
server_url (str) – ACME server URL (used to organize storage by server).

Raises:

AcmeConfigurationError – If email is invalid.

__init__(email, storage_path, server_url)[source]¶

Parameters:

email (str)
storage_path (Path)
server_url (str)

Return type:

None

property email: str¶: Account email address.

property key: EllipticCurvePrivateKey¶

Account private key.

Raises:: AcmeAuthenticationError – If key is not initialized.

property jwk: dict[str, str]¶

JSON Web Key representation of public key.

Raises:: AcmeAuthenticationError – If key is not initialized.

property thumbprint: str¶

JWK thumbprint for key authorization.

Raises:: AcmeAuthenticationError – If key is not initialized.

property uri: str | None¶: Account URI from the ACME server.

property status: AccountStatus | None¶: Account status.

property exists: bool¶: Check if account data exists on disk.

property is_valid: bool¶: Check if account is valid and ready for use.

property contact: str¶

format).

Type:: Contact URL for the account (mailto

create_key()[source]¶

Generate a new account key.

Creates a new EC P-256 private key and saves it to disk.

Raises:: AcmeAuthenticationError – If key already exists.
Return type:: None

save(uri, status)[source]¶

Save account data after registration.

Parameters:

uri (str) – Account URI from the ACME server.
status (str) – Account status string.

Return type:

None

update_key(new_key)[source]¶

Update the account key after a key rollover.

Parameters:: new_key (EllipticCurvePrivateKey) – The new EC P-256 private key.
Return type:: None

get_certificate_paths(common_name)[source]¶

Get the paths for storing a certificate and its key.

Parameters:: common_name (str) – Certificate common name.
Return type:: tuple[Path, Path]
Returns:: Tuple of (certificate_path, key_path).

Order¶

class acmeow.Order[source]¶

Bases: object

An ACME certificate order.

Orders represent a request for a certificate covering one or more identifiers. They progress through states as authorizations are completed and the certificate is issued.

Note: This class is mutable because orders are updated as their status changes during the certificate issuance process.

Parameters:

status (OrderStatus) – Current order status.
url (str) – URL for polling order status.
identifiers (tuple[Identifier, ...]) – List of identifiers the certificate will cover.
finalize_url (str) – URL for submitting the CSR.
expires (str | None) – Expiration timestamp for the order.
certificate_url (str | None) – URL for downloading the certificate (when ready).
authorizations (list[Authorization]) – List of authorizations for this order.
error (dict[str, str] | None) – Error details if the order failed.

status: OrderStatus¶

url: str¶

identifiers: tuple[Identifier, ...]¶

finalize_url: str¶

expires: str | None¶

certificate_url: str | None¶

authorizations: list[Authorization]¶

error: dict[str, str] | None¶

classmethod from_dict(data, url)[source]¶

Create an Order from an ACME response dictionary.

Parameters:

data (dict[str, Any]) – Order object from ACME server response.
url (str) – The order URL.

Return type:

Order

Returns:

New Order instance.

update_from_dict(data)[source]¶

Update the order from an ACME response dictionary.

Parameters:: data (dict[str, Any]) – Order object from ACME server response.
Return type:: None

property is_pending: bool¶: Check if the order is pending authorization completion.

property is_ready: bool¶: Check if the order is ready for finalization.

property is_processing: bool¶: Check if the order is being processed.

property is_valid: bool¶: Check if the order is complete and certificate is ready.

property is_invalid: bool¶: Check if the order failed.

property is_finalized: bool¶: Check if the order has been finalized (processing or valid).

property domains: list[str]¶

Get the list of domain names in this order.

Returns:: List of domain/identifier values.

property common_name: str¶

Get the common name (first identifier) for this order.

Returns:: The first identifier value.

__str__()[source]¶

Return a human-readable string representation.

Return type:: str

__init__(status, url, identifiers, finalize_url, expires=None, certificate_url=None, authorizations=<factory>, error=None)¶

Parameters:

status (OrderStatus)
url (str)
identifiers (tuple[Identifier, ...])
finalize_url (str)
expires (str | None)
certificate_url (str | None)
authorizations (list[Authorization])
error (dict[str, str] | None)

Return type:

None

Authorization¶

class acmeow.Authorization[source]¶

Bases: object

An ACME authorization for an identifier.

Authorizations represent the server’s acknowledgment that the account holder has proven control over an identifier. They contain one or more challenges that can be completed to validate control.

Parameters:

identifier (Identifier) – The identifier this authorization is for.
status (AuthorizationStatus) – Current authorization status.
url (str) – URL for polling authorization status.
expires (str | None) – Expiration timestamp for the authorization.
challenges (tuple[Challenge, ...]) – List of available challenges.
wildcard (bool) – Whether this is a wildcard authorization.

identifier: Identifier¶

status: AuthorizationStatus¶

url: str¶

expires: str | None¶

challenges: tuple[Challenge, ...]¶

wildcard: bool¶

classmethod from_dict(data, url)[source]¶

Create an Authorization from an ACME response dictionary.

Parameters:

data (dict[str, Any]) – Authorization object from ACME server response.
url (str) – The authorization URL.

Return type:

Authorization

Returns:

New Authorization instance.

get_challenge(challenge_type)[source]¶

Get a challenge of the specified type.

Parameters:: challenge_type (ChallengeType) – The type of challenge to find.
Return type:: Challenge | None
Returns:: The matching challenge, or None if not found.

get_dns_challenge()[source]¶

Get the DNS-01 challenge if available.

Return type:: Challenge | None
Returns:: The DNS-01 challenge, or None if not available.

get_http_challenge()[source]¶

Get the HTTP-01 challenge if available.

Return type:: Challenge | None
Returns:: The HTTP-01 challenge, or None if not available.

get_tls_alpn_challenge()[source]¶

Get the TLS-ALPN-01 challenge if available.

Return type:: Challenge | None
Returns:: The TLS-ALPN-01 challenge, or None if not available.

property is_pending: bool¶: Check if the authorization is pending completion.

property is_valid: bool¶: Check if the authorization has been validated.

property is_invalid: bool¶: Check if the authorization failed.

property domain: str¶

Get the domain name for this authorization.

Returns:: The identifier value (domain name).

__str__()[source]¶

Return a human-readable string representation.

Return type:: str

__init__(identifier, status, url, expires=None, challenges=<factory>, wildcard=False)¶

Parameters:

identifier (Identifier)
status (AuthorizationStatus)
url (str)
expires (str | None)
challenges (tuple[Challenge, ...])
wildcard (bool)

Return type:

None

Challenge¶

class acmeow.Challenge[source]¶

Bases: object

An ACME challenge for domain validation.

Challenges are used to prove control over an identifier. They are immutable; status changes require fetching updated challenge data from the server.

Parameters:

type (ChallengeType) – The challenge type (DNS-01 or HTTP-01).
status (ChallengeStatus) – Current challenge status.
url (str) – URL for responding to and polling the challenge.
token (str) – Challenge token provided by the server.
validated (str | None) – Timestamp when the challenge was validated (if valid).
error (dict[str, str] | None) – Error details if the challenge failed.

type: ChallengeType¶

status: ChallengeStatus¶

url: str¶

token: str¶

validated: str | None¶

error: dict[str, str] | None¶

classmethod from_dict(data)[source]¶

Create a Challenge from an ACME response dictionary.

Parameters:: data (dict[str, Any]) – Challenge object from ACME server response.
Return type:: Challenge
Returns:: New Challenge instance.

property is_pending: bool¶: Check if the challenge is pending response.

property is_processing: bool¶: Check if the challenge is being validated.

property is_valid: bool¶: Check if the challenge was successfully validated.

property is_invalid: bool¶: Check if the challenge failed validation.

__str__()[source]¶

Return a human-readable string representation.

Return type:: str

__init__(type, status, url, token, validated=None, error=None)¶

Parameters:

type (ChallengeType)
status (ChallengeStatus)
url (str)
token (str)
validated (str | None)
error (dict[str, str] | None)

Return type:

None

Identifier¶

class acmeow.Identifier[source]¶

Bases: object

An ACME identifier representing a domain or IP address.

Identifiers specify what the certificate will be issued for. They are immutable to ensure consistency throughout the certificate issuance process.

Parameters:

type (IdentifierType) – The type of identifier (DNS or IP).
value (str) – The identifier value (e.g., “example.com” or “192.168.1.1”).

Examples

>>> domain = Identifier(IdentifierType.DNS, "example.com")
>>> ip = Identifier(IdentifierType.IP, "192.168.1.1")

type: IdentifierType¶

value: str¶

to_dict()[source]¶

Convert to dictionary for ACME requests.

Return type:: dict[str, str]
Returns:: Dictionary with “type” and “value” keys.

classmethod from_dict(data)[source]¶

Create an Identifier from an ACME response dictionary.

Parameters:: data (dict[str, str]) – Dictionary with “type” and “value” keys.
Return type:: Identifier
Returns:: New Identifier instance.

classmethod dns(domain)[source]¶

Create a DNS identifier for a domain name.

Parameters:: domain (str) – Domain name (e.g., “example.com”).
Return type:: Identifier
Returns:: DNS Identifier for the domain.

classmethod ip(address)[source]¶

Create an IP identifier for an IP address.

Parameters:: address (str) – IP address (e.g., “192.168.1.1”).
Return type:: Identifier
Returns:: IP Identifier for the address.

__str__()[source]¶

Return a human-readable string representation.

Return type:: str

__init__(type, value)¶

Parameters:

type (IdentifierType)
value (str)

Return type:

None