acmev2 0.0.3__tar.gz

acmev2-0.0.3/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.2
+Name: acmev2
+Version: 0.0.3
+Summary: ACME v2 Protocol Implementation (limited)
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: inject>=5.2.1
+Requires-Dist: josepy>=1.14.0
+Requires-Dist: parse>=1.20.2
+Requires-Dist: pydantic-settings>=2.5.2
+Requires-Dist: pydantic>=2.9.1
+Requires-Dist: requests>=2.32.3

acmev2-0.0.3/acmev2/__init__.py

@@ -0,0 +1,6 @@
+import acmev2.messages
+import acmev2.services
+import acmev2.models
+from importlib.metadata import version
+
+__version__ = version("acmev2")

acmev2-0.0.3/acmev2/challenges/__init__.py

@@ -0,0 +1,15 @@
+from typing import Type
+from .http import Http01ChallengeValidator
+from .base import ChallengeValidator
+from .custom import CustomChallengeValidatorRunner, CustomChallengeValidator
+from acmev2.models import ChallengeType
+
+
+def validator_for(typ: ChallengeType) -> Type[ChallengeValidator]:
+    match typ:
+        case ChallengeType.http_01:
+            return Http01ChallengeValidator
+        case ChallengeType.custom:
+            return CustomChallengeValidatorRunner
+
+    raise Exception("No match found for challenge type {typ}")

acmev2-0.0.3/acmev2/challenges/base.py

@@ -0,0 +1,27 @@
+import inject
+import josepy.jwk
+
+from acmev2.models import AuthorizationResource, HTTPChallengeResource
+from acmev2.settings import ACMESettings
+
+
+class ValidationError(Exception):
+    pass
+
+
+class ChallengeValidator:
+
+    settings = inject.attr(ACMESettings)
+
+    def __init__(
+        self,
+        acct_jwk: josepy.jwk.JWK,
+        authz: AuthorizationResource,
+        chall: HTTPChallengeResource,
+    ):
+        self.chall = chall
+        self.authz = authz
+        self.acct_jwk = acct_jwk
+
+    def validate(self) -> bool:
+        return False

acmev2-0.0.3/acmev2/challenges/custom.py

@@ -0,0 +1,25 @@
+import abc
+import inject
+import requests
+import urllib3
+from urllib3.exceptions import InsecureRequestWarning
+
+from acmev2.settings import ACMESettings
+from .base import ChallengeValidator
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class CustomChallengeValidatorRunner(ChallengeValidator):
+
+    def validate(self) -> bool:
+        validator = inject.instance(CustomChallengeValidator)
+        return validator.validate(self)
+
+
+class CustomChallengeValidator(abc.ABC):
+
+    @abc.abstractmethod
+    def validate(self, challenge_validator: ChallengeValidator) -> bool:
+        pass

acmev2-0.0.3/acmev2/challenges/http.py

@@ -0,0 +1,58 @@
+import inject
+import requests
+import urllib3
+from urllib3.exceptions import InsecureRequestWarning
+
+from acmev2.settings import ACMESettings
+from .base import ChallengeValidator, ValidationError
+import logging
+import josepy
+
+logger = logging.getLogger(__name__)
+
+
+class Http01ChallengeValidator(ChallengeValidator):
+
+    def validate(self) -> bool:
+        settings = inject.instance(ACMESettings)
+        # Only DNS identifiers supported
+        domain = f"http://{self.authz.identifier.value}"
+
+        endpoint = f"{domain}/.well-known/acme-challenge/{self.chall.token}"
+        logger.info(f"Validating endpoint <{endpoint}> for challenge <{self.chall.id}>")
+        expected_content = (
+            f"{self.chall.token}.{josepy.encode_b64jose(self.acct_jwk.thumbprint())}"
+        )
+
+        try:
+            # warnings can sometimes be treated as errors, we need to allow the challenge
+            # to run against certificates that are expired
+            urllib3.disable_warnings(InsecureRequestWarning)
+            challenge_headers = requests.utils.default_headers()
+            challenge_headers["User-Agent"] = settings.http_01_challenge_user_agent
+            # again, pass verify=False because this challenge should succeed on invalid certs
+            # if the challenge is redirected to https
+            challenge_response = requests.get(
+                endpoint, allow_redirects=True, verify=False
+            )
+
+            if challenge_response.status_code != 200:
+                raise ValidationError(
+                    "{challenge_response.status_code} status code returned from server"
+                )
+
+            logger.info(
+                f"Challenge returned: <{challenge_response}>, expected: <{expected_content}>"
+            )
+        except requests.RequestException as exc:
+            logger.exception("Error validating http-01 challenge")
+            raise ValidationError(
+                f"{exc.__class__.__name__}: error requesting {exc.request.url}"
+            )
+
+        # remove extra text returned
+        actual = challenge_response.text.splitlines()[0].strip()
+        if actual != expected_content:
+            raise ValidationError("Content did not match expected token")
+
+        return actual == expected_content

acmev2-0.0.3/acmev2/errors.py

@@ -0,0 +1,130 @@
+from enum import Enum
+
+
+ERROR_PREFIX = "urn:ietf:params:acme:error:"
+
+ERROR_CODES = {
+    "accountDoesNotExist": "The request specified an account that does not exist",
+    "alreadyRevoked": "The request specified a certificate to be revoked that has"
+    " already been revoked",
+    "badCSR": "The CSR is unacceptable (e.g., due to a short key)",
+    "badNonce": "The client sent an unacceptable anti-replay nonce",
+    "badPublicKey": "The JWS was signed by a public key the server does not support",
+    "badRevocationReason": "The revocation reason provided is not allowed by the server",
+    "badSignatureAlgorithm": "The JWS was signed with an algorithm the server does not support",
+    "caa": "Certification Authority Authorization (CAA) records forbid the CA from issuing"
+    " a certificate",
+    "compound": 'Specific error conditions are indicated in the "subproblems" array',
+    "connection": ("The server could not connect to the client to verify the domain"),
+    "dns": "There was a problem with a DNS query during identifier validation",
+    "dnssec": "The server could not validate a DNSSEC signed domain",
+    "incorrectResponse": "Response received didn't match the challenge's requirements",
+    "invalidContact": "The provided contact URI was invalid",
+    "malformed": "The request message was malformed",
+    "rejectedIdentifier": "The server will not issue certificates for the identifier",
+    "orderNotReady": "The request attempted to finalize an order that is not ready to be finalized",
+    "rateLimited": "There were too many requests of a given type",
+    "serverInternal": "The server experienced an internal error",
+    "tls": "The server experienced a TLS error during domain verification",
+    "unauthorized": "The client lacks sufficient authorization",
+    "unsupportedContact": "A contact URL for an account used an unsupported protocol scheme",
+    "unknownHost": "The server could not resolve a domain name",
+    "unsupportedIdentifier": "An identifier is of an unsupported type",
+    "externalAccountRequired": "The server requires external account binding",
+    "userActionRequired": "User action required",
+}
+
+
+class ACMEError(Exception):
+    type: str = "malformed"
+    detail: str = None
+    code: int = 403
+    header_links: list[tuple[str, str]] = []
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args)
+
+        if "type" in kwargs:
+            self.type = kwargs["type"]
+
+        if "detail" in kwargs:
+            self.detail = kwargs["detail"]
+
+        if "code" in kwargs:
+            self.code = kwargs["code"]
+
+        if "header_links" in kwargs:
+            self.header_links = kwargs["header_links"]
+
+        if self.type in ERROR_CODES:
+            self.type = f"{ERROR_PREFIX}{self.type}"
+
+
+class ACMEUnauthorizedError(ACMEError):
+    type = "unauthorized"
+    code = 401
+
+
+class ACMEResourceNotFoundError(ACMEError):
+    type = "resourceNotFound"
+    code = 404
+
+
+class ACMEMalformedError(ACMEError):
+    type = "malformed"
+    detail = "Malformed request"
+    code = 400
+
+
+class ACMESignatureVerificationError(ACMEError):
+    type = "malformed"
+    detail = "Malformed signature"
+    code = 400
+
+
+class ACMEToSAgreementError(ACMEError):
+    type = "userActionRequired"
+    code = 403
+    detail = "Please read and agree to the terms of service"
+
+
+class ACMEUserActionRequiredError(ACMEError):
+    type = "userActionRequired"
+    code = 403
+
+    def __init__(self, detail: str, *args, **kwargs):
+        self.detail = detail
+        super().__init__(*args, **kwargs)
+
+
+class ACMEMethodNotAllowedError(ACMEError):
+    type = "malformed"
+    code = 403
+
+
+class ACMEBadCSRDetail(str, Enum):
+    sansRequired = "SANS are required"
+    invalidSan = "Invalid subjectAlternateName extension value"
+    cnMissingFromSan = (
+        "The common name must also appear in the subjectAlternateName extension"
+    )
+    csrOrderMismatch = (
+        "The CSR must indiciate the exact same set of identifiers as the order"
+    )
+    orderNotAuthorized = "Order has not completed all authorizations"
+
+
+class ACMEBadCSRError(ACMEError):
+    type = "badCSR"
+
+    def __init__(self, detail: ACMEBadCSRDetail):
+        self.detail = str(detail)
+        super().__init__()
+
+
+class ACMEInvalidContentTypeError(ACMEError):
+    code = 415
+
+
+class JoseJsonFormatError(ACMEError):
+    pass

acmev2-0.0.3/acmev2/handlers/__init__.py

@@ -0,0 +1,12 @@
+from .authorization import AuthorizationRequestHandler
+from .base import ACMERequestHandler, ACMEModelResponse
+from .challenge import ChallengeRequestHandler
+from .new_account import NewAccountRequestHandler
+from .new_nonce import NewNonceRequestHandler
+from .order import (
+    NewOrderRequestHandler,
+    OrderFinalizationRequestHandler,
+    OrderRequestHandler,
+)
+from .certificate import CertRequestHandler
+from .handler import handle

acmev2-0.0.3/acmev2/handlers/authorization.py

@@ -0,0 +1,35 @@
+import inject
+from acmev2.errors import ACMEError
+from acmev2.messages import AuthorizationMessage
+from acmev2.models import AuthorizationStatus
+from acmev2.services import IAuthorizationService
+from .base import ACMERequestHandler, ACMEModelResponse
+
+
+class AuthorizationRequestHandler(ACMERequestHandler):
+    """Returns an authorization and all the associated challenges."""
+
+    message_type = AuthorizationMessage
+    authorization_service = inject.attr(IAuthorizationService)
+
+    def process(self, msg: AuthorizationMessage):
+        authz_resource = msg.resource
+
+        if self.should_deactivate(msg):
+            authz_resource = self.authorization_service.update_status(
+                authz_resource, AuthorizationStatus.deactivated
+            )
+
+        return ACMEModelResponse(msg=authz_resource, code=200)
+
+    def should_deactivate(self, msg: AuthorizationMessage) -> bool:
+        if msg.payload.status == AuthorizationStatus.deactivated:
+            if msg.resource.status == AuthorizationStatus.valid:
+                return True
+
+            # Invalid, cannot transition to deactivated from any state but valid
+            raise ACMEError(
+                detail=f"May not transition to '{AuthorizationStatus.deactivated.value}' from '{msg.resource.status.value}'"
+            )
+
+        return False

acmev2-0.0.3/acmev2/handlers/base.py

@@ -0,0 +1,84 @@
+from typing import Any, Generic, Mapping, Optional, Type, TypeVar
+from urllib.parse import quote
+
+import inject
+
+from acmev2.messages.base import ACMEMessage
+from acmev2.models import ACMEResource
+from acmev2.services import IDirectoryService
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class HttpVerb:
+    HEAD = "HEAD"
+    GET = "GET"
+    POST = "POST"
+
+
+class ACMERequestHandler:
+    allowed_verbs = [HttpVerb.POST]
+    message_type: Type[ACMEMessage] = ACMEMessage
+    requires_nonce = True
+
+    def __init__(
+        self,
+        request_url: str,
+        verb: HttpVerb,
+        headers: Mapping[str, Any] = None,
+        msg: Optional[Mapping[str, Any]] = None,
+    ):
+        self.request_url = request_url
+        self.verb = verb
+        self.headers = headers or {}
+        self.msg = msg
+
+    def extract_message(self, msg: Optional[Mapping[str, Any]]):
+        return self.message_type.from_json(msg)
+
+    def process(msg: ACMEMessage) -> "ACMEModelResponse":
+        pass
+
+
+T = TypeVar("T")
+
+
+class ACMEResponse(Generic[T]):
+    content_type: str = "application/json"
+    directory_service = inject.attr(IDirectoryService)
+    msg: T | None
+
+    def __init__(
+        self,
+        headers: Mapping[str, Any] = None,
+        msg: Optional[T] = None,
+        code: int = 200,
+        location: str = None,
+    ):
+        self.headers = headers or {}
+        self.msg = msg or None
+        self.code = code
+
+        if location:
+            self.headers["Location"] = location
+
+        directory_root = self.directory_service.root_url
+        self.add_link_header(directory_root, "index")
+
+    def add_link_header(self, link: str, rel: str):
+        link_header = self.headers.get("Link", "")
+
+        header_value = f'<{quote(link, safe="/:")}>;rel="{rel}"'
+        if link_header:
+            link_header += ","
+
+        self.headers["Link"] = link_header + header_value
+
+
+class ACMEModelResponse(ACMEResponse[ACMEResource]):
+    def serialize(self) -> str:
+        if self.msg:
+            return self.msg.model_dump_json(indent=2)
+        else:
+            return ""

acmev2-0.0.3/acmev2/handlers/certificate.py

@@ -0,0 +1,42 @@
+import inject
+
+from acmev2.messages import (
+    CertMessage,
+)
+from acmev2.services import (
+    IOrderService,
+    IAuthorizationService,
+    IDirectoryService,
+)
+from acmev2.models import CertResource
+from .base import ACMERequestHandler, ACMEResponse
+
+
+class ACMECertResponse(ACMEResponse[CertResource]):
+    content_type = "application/pem-certificate-chain"
+
+    def serialize(self) -> str:
+        # TODO: return different certs depending on the
+        # client Accept header.
+        #  application/pkix-cert - DER
+        #  application/pkcs7-mime - DER
+        return self.msg.pem
+
+
+class CertRequestHandler(ACMERequestHandler):
+    """Returns a certificate chain for the requested identifier. Only supports
+    PEM-encoded certificates."""
+
+    message_type = CertMessage
+    order_service = inject.attr(IOrderService)
+    directory_service = inject.attr(IDirectoryService)
+    authorization_service = inject.attr(IAuthorizationService)
+
+    def process(
+        self,
+        msg: CertMessage,
+    ):
+        # todo: this is actually multiple certs, change the response
+        cert = msg.resource
+
+        return ACMECertResponse(msg=cert, code=200)

acmev2-0.0.3/acmev2/handlers/challenge.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+
+import inject
+
+from acmev2.errors import (
+    ACMEError,
+)
+from acmev2.messages import ChallengeMessage
+from acmev2.models import AuthorizationResource, ChallengeStatus
+from acmev2.services import (
+    ACMEEndpoint,
+    IAuthorizationService,
+    IChallengeService,
+    IDirectoryService,
+)
+
+from .base import ACMEModelResponse, ACMERequestHandler
+
+
+class ChallengeRequestHandler(ACMERequestHandler):
+    """Begins validating a specific challenge. Validation can be done in-line or
+    the service implementer can decide to periodically validate in the background."""
+
+    message_type = ChallengeMessage
+    directory_service = inject.attr(IDirectoryService)
+    challenge_service = inject.attr(IChallengeService)
+    authorization_service = inject.attr(IAuthorizationService)
+
+    def process(self, msg: ChallengeMessage):
+        chall = msg.resource
+        authz = self.authorization_service.get(chall.authz_id)
+        self.validate_expiration(msg, authz)
+
+        if chall.status == ChallengeStatus.pending:
+            chall = self.challenge_service.queue_validation(chall)
+            chall.status = ChallengeStatus.processing
+
+        resp = ACMEModelResponse(msg=chall, code=200)
+        resp.add_link_header(
+            self.directory_service.url_for(ACMEEndpoint.authz, authz.id), "up"
+        )
+
+        return resp
+
+    def validate_expiration(self, msg: ChallengeMessage, authz: AuthorizationResource):
+        if datetime.now() > authz.expires:
+            raise ACMEError(detail="Authorization has expired")

acmev2-0.0.3/acmev2/handlers/handler.py

@@ -0,0 +1,138 @@
+import logging
+
+import inject
+import pydantic
+
+from acmev2.errors import (
+    ACMEError,
+    ACMEInvalidContentTypeError,
+    ACMEMethodNotAllowedError,
+    ACMEUnauthorizedError,
+)
+from acmev2.handlers import ACMEModelResponse, ACMERequestHandler
+from acmev2.logging import LazyLoggedResponse
+from acmev2.handlers.base import HttpVerb
+from acmev2.messages.base import (
+    ACMEMessage,
+    AuthenticatedACMEMessage,
+    SignedACMEMessage,
+)
+from acmev2.models import AccountStatus, ProblemResource
+from acmev2.services import INonceService
+
+logger = logging.getLogger(__name__)
+
+
+def format_problem(error: ACMEError):
+    """Formats an ACMEError as a problem document response.
+
+    Args:
+        error (ACMEError): The error to transform.
+
+    Returns:
+        ACMEModelResponse: A model response that will serialize to a problem document.
+    """
+    resp = ACMEModelResponse(
+        headers={"Content-Type": "application/problem+json"},
+        msg=ProblemResource(type=error.type, detail=error.detail),
+        code=error.code,
+    )
+
+    for link, rel in error.header_links:
+        resp.add_link_header(link, rel)
+
+    return resp
+
+
+class LazyLoggedMessage:
+    def __init__(self, message: ACMEMessage):
+        self.message = message
+
+    def __str__(self):
+        import json
+
+        if isinstance(self.message, SignedACMEMessage):
+            return json.dumps(
+                {
+                    "payload": self.message.jose_message.payload_decoded,
+                    "protected": self.message.jose_message.protected_decoded,
+                },
+                indent=2,
+            )
+        else:
+            return json.dumps(self.message.body, indent=2)
+
+
+def handle(req: ACMERequestHandler) -> ACMEModelResponse:
+    """Handles the ACME request and any errors it raises, along with
+    ensuring every request that needs a nonce has one returned.
+
+    Args:
+        req (ACMERequestHandler): The request handler to be executed.
+
+    Returns:
+        ACMEModelResponse: A serializable model that an ACME client can understand.
+    """
+    nonce_service = inject.instance(INonceService)
+    resp: ACMEModelResponse = None
+    acme_message: ACMEMessage | None = None
+    try:
+        if (
+            req.msg is not None
+            and req.verb == HttpVerb.POST
+            and req.headers.get("Content-Type") != "application/jose+json"
+        ):
+            raise ACMEInvalidContentTypeError()
+
+        if req.verb not in req.allowed_verbs:
+            raise ACMEMethodNotAllowedError()
+
+        acme_message = req.extract_message(req.msg)
+        logger.debug("client message: %s", LazyLoggedMessage(acme_message))
+
+        # Request url integrity: https://datatracker.ietf.org/doc/html/rfc8555/#section-6.4
+        if isinstance(acme_message, SignedACMEMessage):
+            if acme_message.url != req.request_url:
+                raise ACMEUnauthorizedError()
+
+        # Ensure account hasn't been revoked or deactivated
+        if isinstance(acme_message, AuthenticatedACMEMessage):
+            if acme_message.account.status != AccountStatus.valid:
+                raise ACMEError(detail="Account not valid")
+
+        # Consume the nonce right before processing the request
+        if req.requires_nonce and not nonce_service.consume(acme_message.nonce):
+            raise ACMEError(type="badNonce")
+
+        resp = req.process(acme_message)
+
+        if resp.content_type:
+            resp.headers["Content-Type"] = resp.content_type
+    except ACMEError as exc:
+        # These are normal expected errors raised by handlers
+        logging_extra_info = ""
+        if acme_message and isinstance(acme_message, SignedACMEMessage):
+            logging_extra_info += f" url<{acme_message.url}>"
+        if acme_message and isinstance(acme_message, AuthenticatedACMEMessage):
+            logging_extra_info += f" account<{acme_message.account_id}>"
+
+        logging.info(
+            f"ACMEError - type<{exc.type}> detail<{exc.detail}>{logging_extra_info}"
+        )
+        resp = format_problem(exc)
+    except pydantic.ValidationError:
+        # Pydantic errors usually happen when the request is malformed
+        logger.exception("Error validating Pydantic model")
+        resp = format_problem(ACMEError(type="malformed"))
+    except Exception:
+        # All other errors return a generic problem document
+        logging.exception("Unhandled exception caught at error boundry")
+        resp = format_problem(ACMEError(type="serverInternal", code=500))
+
+    if req.verb == HttpVerb.POST and "Replay-Nonce" not in resp.headers:
+        # Every POST needs a nonce returned. Head/Get requests should only
+        # generate a nonce with the newNonce handler.
+        resp.headers["Replay-Nonce"] = nonce_service.generate()
+
+    logger.debug("response: %s", LazyLoggedResponse(resp))
+    return resp