pki-core 0.3.1__py3-none-any.whl

pki/core/__init__.py

@@ -0,0 +1,36 @@
+"""Generic X.509 certificate utilities."""
+
+from .algorithms import AlgorithmPolicy
+from .certificate import CertificateError
+from .crl import CRLRefreshError
+from .providers import AuthProvider, HeuristicRule, ProviderRegistry, TrustStoreSource
+from .revocation import CRL, OCSP, RevocationCheck, RevocationPolicy, RevocationResult
+from .trust_store import build_bundle_for_provider
+from .validation import (
+    CertificatePolicy,
+    ValidationResult,
+    ValidationStatus,
+    validate_certificate,
+    verify_chain,
+)
+
+__all__ = [
+    "CRL",
+    "OCSP",
+    "AlgorithmPolicy",
+    "AuthProvider",
+    "CRLRefreshError",
+    "CertificateError",
+    "CertificatePolicy",
+    "HeuristicRule",
+    "ProviderRegistry",
+    "RevocationCheck",
+    "RevocationPolicy",
+    "RevocationResult",
+    "TrustStoreSource",
+    "ValidationResult",
+    "ValidationStatus",
+    "build_bundle_for_provider",
+    "validate_certificate",
+    "verify_chain",
+]

pki/core/algorithms.py

@@ -0,0 +1,123 @@
+"""Cryptographic algorithm policy enforcement.
+
+Validates that a certificate's public key and signature algorithm meet
+minimum requirements.  pki-core provides a generic :class:`AlgorithmPolicy`
+dataclass whose defaults match broadly accepted minimums (RSA 2048+,
+ECC P-256/P-384, SHA-256+).  Provider packs such as ``pki-federal`` define
+their own policy constants aligned with specific standards (e.g., SP 800-78).
+
+Example::
+
+    from pki.core.algorithms import AlgorithmPolicy, check_algorithms
+
+    # Use defaults (RSA 2048+, P-256/P-384, SHA-256+)
+    result, detail = check_algorithms(cert, AlgorithmPolicy())
+
+    # ECC P-384 only, no RSA
+    strict = AlgorithmPolicy(
+        min_rsa_bits=0,
+        allowed_curves=frozenset({"secp384r1"}),
+    )
+    result, detail = check_algorithms(cert, strict)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from cryptography import x509
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+logger = logging.getLogger(__name__)
+
+# Defaults that match broadly accepted minimums.
+_DEFAULT_CURVES = frozenset({"secp256r1", "secp384r1"})
+_DEFAULT_HASHES = frozenset({"sha256", "sha384", "sha512"})
+
+
+@dataclass(frozen=True)
+class AlgorithmPolicy:
+    """Approved cryptographic algorithms for certificate validation.
+
+    Defaults are broadly accepted minimums.  Provider packs (e.g.,
+    ``pki-federal``) should define constants with values aligned to their
+    governing standard.
+
+    Attributes:
+        min_rsa_bits: Minimum RSA key size in bits.  Set to ``0`` to
+            disallow RSA entirely.
+        allowed_curves: Frozenset of allowed elliptic curve names
+            (lowercase, as returned by ``key.curve.name``).
+        allowed_hashes: Frozenset of allowed signature hash algorithm
+            names (lowercase, as returned by
+            ``cert.signature_hash_algorithm.name``).
+    """
+
+    min_rsa_bits: int = 2048
+    allowed_curves: frozenset[str] = field(default_factory=lambda: _DEFAULT_CURVES)
+    allowed_hashes: frozenset[str] = field(default_factory=lambda: _DEFAULT_HASHES)
+
+
+def check_algorithms(
+    cert: x509.Certificate,
+    policy: AlgorithmPolicy,
+) -> tuple[bool, str]:
+    """Check that a certificate's algorithms comply with *policy*.
+
+    Validates:
+
+    1. **Public key type and size** — RSA keys must be at least
+       ``policy.min_rsa_bits``.  EC keys must use a curve in
+       ``policy.allowed_curves``.  Other key types (DSA, Ed25519, etc.)
+       are rejected.
+    2. **Signature hash algorithm** — must be in ``policy.allowed_hashes``.
+
+    Args:
+        cert: The certificate to check.
+        policy: Algorithm requirements.
+
+    Returns:
+        A ``(passed, detail)`` tuple.  *passed* is ``True`` if the
+        certificate meets all requirements, ``False`` otherwise.
+        *detail* is a human-readable message.
+    """
+    public_key = cert.public_key()
+
+    # Check public key type and size
+    if isinstance(public_key, rsa.RSAPublicKey):
+        if policy.min_rsa_bits == 0:
+            return False, "RSA keys are not allowed by algorithm policy"
+        key_size = public_key.key_size
+        if key_size < policy.min_rsa_bits:
+            return (
+                False,
+                f"RSA key size {key_size} bits is below minimum {policy.min_rsa_bits}",
+            )
+    elif isinstance(public_key, ec.EllipticCurvePublicKey):
+        curve_name = public_key.curve.name.lower()
+        if curve_name not in policy.allowed_curves:
+            return (
+                False,
+                f"EC curve {public_key.curve.name} is not in allowed set "
+                f"{sorted(policy.allowed_curves)}",
+            )
+    else:
+        key_type = type(public_key).__name__
+        return False, f"Unsupported public key type: {key_type}"
+
+    # Check signature hash algorithm
+    hash_alg = cert.signature_hash_algorithm
+    if hash_alg is None:
+        # EdDSA and other algorithms don't have a separate hash
+        return False, "Certificate has no signature hash algorithm (unsupported signature type)"
+
+    hash_name = hash_alg.name.lower()
+    if hash_name not in policy.allowed_hashes:
+        return (
+            False,
+            f"Signature hash algorithm {hash_alg.name} is not in allowed set "
+            f"{sorted(policy.allowed_hashes)}",
+        )
+
+    return True, "Algorithm check passed"

pki/core/certificate.py

@@ -0,0 +1,120 @@
+"""X.509 certificate parsing utilities."""
+
+import logging
+import re
+from datetime import UTC, datetime
+from hashlib import sha256
+
+from cryptography import x509
+from cryptography.hazmat.primitives.serialization import Encoding
+from cryptography.x509.oid import ExtensionOID, NameOID
+
+logger = logging.getLogger(__name__)
+
+
+class CertificateError(Exception):
+    """Raised when certificate parsing or validation fails."""
+
+
+def load_certificate(data: bytes) -> x509.Certificate:
+    """Load an x509 certificate from PEM or DER bytes."""
+    try:
+        return x509.load_pem_x509_certificate(data)
+    except Exception:
+        pass
+    try:
+        return x509.load_der_x509_certificate(data)
+    except Exception as e:
+        raise CertificateError(f"Failed to parse certificate: {e}") from e
+
+
+def get_name_attr(name: x509.Name, oid: x509.ObjectIdentifier) -> str | None:
+    """Get first attribute value for an OID from an x509 Name."""
+    attrs = name.get_attributes_for_oid(oid)
+    return str(attrs[0].value) if attrs else None
+
+
+def get_policy_oids(cert: x509.Certificate) -> list[str]:
+    """Extract certificate policy OIDs."""
+    try:
+        ext = cert.extensions.get_extension_for_oid(ExtensionOID.CERTIFICATE_POLICIES)
+        return [p.policy_identifier.dotted_string for p in ext.value]  # type: ignore[attr-defined]
+    except x509.ExtensionNotFound:
+        return []
+
+
+def extract_email(cert: x509.Certificate) -> str | None:
+    """Extract email from SAN (rfc822Name) or subject."""
+    try:
+        san = cert.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_ALTERNATIVE_NAME)
+        emails = san.value.get_values_for_type(x509.RFC822Name)  # type: ignore[attr-defined]
+        if emails:
+            return emails[0]
+    except x509.ExtensionNotFound:
+        pass
+
+    return get_name_attr(cert.subject, NameOID.EMAIL_ADDRESS)
+
+
+def extract_san_uris(cert: x509.Certificate) -> list[str]:
+    """Extract URI values from Subject Alternative Name."""
+    try:
+        san = cert.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_ALTERNATIVE_NAME)
+        return list(san.value.get_values_for_type(x509.UniformResourceIdentifier))  # type: ignore[attr-defined]
+    except x509.ExtensionNotFound:
+        return []
+
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+
+def extract_san_uuid(cert: x509.Certificate) -> str | None:
+    """Extract UUID from SAN URI (urn:uuid:...).
+
+    Returns the UUID only if it matches the standard 8-4-4-4-12 hex format.
+    """
+    for uri in extract_san_uris(cert):
+        if uri.lower().startswith("urn:uuid:"):
+            candidate = uri[9:]
+            if _UUID_RE.match(candidate):
+                return candidate
+            logger.warning("Ignoring malformed UUID in SAN: %s", candidate)
+    return None
+
+
+def extract_san_fascn(cert: x509.Certificate) -> str | None:
+    """Extract FASC-N from SAN OtherName (OID 2.16.840.1.101.3.6.6)."""
+    try:
+        san = cert.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_ALTERNATIVE_NAME)
+        for general_name in san.value:  # type: ignore[attr-defined]
+            if (
+                isinstance(general_name, x509.OtherName)
+                and general_name.type_id.dotted_string == "2.16.840.1.101.3.6.6"
+            ):
+                return general_name.value.hex()
+    except (x509.ExtensionNotFound, Exception):
+        pass
+    return None
+
+
+def cert_fingerprint(cert: x509.Certificate) -> str:
+    """SHA-256 fingerprint of the DER encoding."""
+    return sha256(cert.public_bytes(Encoding.DER)).hexdigest()
+
+
+def cert_to_pem(cert: x509.Certificate) -> str:
+    """Convert an x509 certificate to PEM string."""
+    return cert.public_bytes(Encoding.PEM).decode("ascii")
+
+
+def is_expired(cert: x509.Certificate) -> bool:
+    """Return True if the certificate has expired."""
+    return cert.not_valid_after_utc < datetime.now(UTC)
+
+
+def is_not_yet_valid(cert: x509.Certificate) -> bool:
+    """Return True if the certificate is not yet valid (before notBefore)."""
+    return cert.not_valid_before_utc > datetime.now(UTC)

pki/core/crl.py

@@ -0,0 +1,374 @@
+"""CRL fetching and revocation checking with stale-while-revalidate caching."""
+
+import hashlib
+import logging
+import os
+import threading
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+from cryptography import x509
+from platformdirs import user_cache_dir
+
+from .certificate import CertificateError
+
+logger = logging.getLogger(__name__)
+
+
+class CRLRefreshError(CertificateError):
+    """Raised when a background CRL refresh fails."""
+
+
+@dataclass
+class CRLConfig:
+    """Configuration for CRL cache behaviour.
+
+    ``cache_dir`` defaults to the platform-standard user cache location
+    based on ``app_name`` (e.g. ``~/.cache/pki-core/crls`` on Linux).
+    Pass an explicit ``cache_dir`` to override.
+
+    Attributes:
+        app_name: Application name for default cache directory.
+        cache_dir: Explicit cache directory (overrides app_name default).
+        cache_ttl: Seconds before a cached CRL is considered stale and
+            triggers a background refresh.  The stale copy is still served
+            while refreshing.
+        strict: If True (default), raise ``CertificateError`` when a CRL
+            cannot be fetched or verified.  If False, log a warning and
+            allow the request.
+        fetch_timeout: HTTP fetch timeout in seconds.
+        max_crl_bytes: Maximum CRL response size in bytes.  Responses
+            larger than this are rejected.  Default is 10 MB; DoD CRLs
+            may require a higher limit.
+        max_acceptable_age: Maximum age in seconds of a cached CRL before
+            it is considered too old to trust, even as a stale fallback.
+            If a cached CRL exceeds this age and cannot be refreshed,
+            the check fails (in strict mode) rather than serving an
+            unacceptably stale copy.  Default is 0 (disabled — any cached
+            CRL is acceptable as a stale fallback).
+    """
+
+    app_name: str = "pki-core"
+    cache_dir: str = ""
+    cache_ttl: int = 3600  # seconds
+    strict: bool = True
+    fetch_timeout: int = 10  # seconds
+    max_crl_bytes: int = 10 * 1024 * 1024  # 10 MB
+    max_acceptable_age: int = 0  # 0 = disabled
+
+    def __post_init__(self):
+        if not self.cache_dir:
+            self.cache_dir = str(Path(user_cache_dir(self.app_name)) / "crls")
+
+
+def get_crl_distribution_points(cert: x509.Certificate) -> list[str]:
+    """Extract HTTP(S) CRL distribution point URLs from a certificate."""
+    try:
+        ext = cert.extensions.get_extension_for_class(x509.CRLDistributionPoints)
+    except x509.ExtensionNotFound:
+        return []
+
+    urls = []
+    for dp in ext.value:
+        if dp.full_name is None:
+            continue
+        for name in dp.full_name:
+            if isinstance(name, x509.UniformResourceIdentifier):
+                url = name.value
+                if url.startswith("http://") or url.startswith("https://"):
+                    urls.append(url)
+    return urls
+
+
+def verify_crl(
+    crl: x509.CertificateRevocationList,
+    issuer_certs: list[x509.Certificate],
+    strict: bool = True,
+) -> bool:
+    """Verify a CRL's signature and freshness against a set of CA certificates.
+
+    Checks that:
+    1. A CA certificate whose subject matches the CRL issuer is present.
+    2. The CRL signature is valid for that CA's public key.
+    3. The CRL's ``nextUpdate`` has not passed (stale CRL protection).
+
+    Returns True if the CRL is valid.  In strict mode, raises
+    ``CertificateError`` on any failure.  In non-strict mode, logs a warning
+    and returns False.
+    """
+    crl_issuer_dn = crl.issuer
+
+    # Find matching issuer cert by parsed DN comparison (handles attribute
+    # ordering and encoding differences that string comparison would miss).
+    issuer_cert = None
+    for ca in issuer_certs:
+        if ca.subject == crl_issuer_dn:
+            issuer_cert = ca
+            break
+
+    if issuer_cert is None:
+        msg = f"No CA certificate found for CRL issuer: {crl_issuer_dn.rfc4514_string()}"
+        if strict:
+            raise CertificateError(msg)
+        logger.warning(msg)
+        return False
+
+    # Verify signature.
+    if not crl.is_signature_valid(issuer_cert.public_key()):  # type: ignore[arg-type]
+        msg = f"CRL signature verification failed for issuer: {crl_issuer_dn.rfc4514_string()}"
+        if strict:
+            raise CertificateError(msg)
+        logger.warning(msg)
+        return False
+
+    # Verify nextUpdate hasn't passed.
+    if crl.next_update_utc and crl.next_update_utc < datetime.now(UTC):
+        msg = f"CRL has expired (nextUpdate={crl.next_update_utc.isoformat()})"
+        if strict:
+            raise CertificateError(msg)
+        logger.warning(msg)
+        return False
+
+    logger.debug("CRL signature valid, issuer=%s", crl_issuer_dn.rfc4514_string())
+    return True
+
+
+def load_ca_certs_from_pem(pem_data: str | bytes) -> list[x509.Certificate]:
+    """Parse all certificates from a PEM bundle.
+
+    Useful for loading a CA bundle file into a list suitable for passing
+    as ``issuer_certs`` to :func:`check_revocation` or :func:`verify_crl`.
+    """
+    if isinstance(pem_data, str):
+        pem_data = pem_data.encode()
+    return x509.load_pem_x509_certificates(pem_data)
+
+
+def check_revocation(
+    cert: x509.Certificate,
+    config: CRLConfig,
+    issuer_certs: list[x509.Certificate] | None = None,
+) -> None:
+    """Check certificate revocation against CRL distribution points.
+
+    Uses a stale-while-revalidate cache strategy:
+    - Fresh cache  -> used immediately, no network I/O.
+    - Stale cache  -> used immediately; background thread refreshes it.
+    - No cache     -> blocking fetch (first-ever request only).
+
+    Raises CertificateError if the certificate's serial number appears in any CRL.
+    If a CRL cannot be fetched and no cached copy exists, behaviour is controlled
+    by config.strict (default True -> raise).
+
+    If ``issuer_certs`` is provided, each CRL's signature and freshness are
+    verified against the CA certificates before the revocation check.  Without
+    ``issuer_certs``, signature verification is skipped (backward compatible).
+    """
+    urls = get_crl_distribution_points(cert)
+    if not urls:
+        logger.warning(
+            "Certificate serial=%s has no CRL distribution points; skipping revocation check",
+            format(cert.serial_number, "x"),
+        )
+        return
+
+    for url in urls:
+        try:
+            crl = get_crl(url, config)
+        except CertificateError:
+            raise
+        except Exception as e:
+            logger.error("CRL unavailable for %s: %s", url, e)
+            if config.strict:
+                raise CertificateError("Could not verify revocation status; CRL unavailable") from e
+            logger.warning("strict=false -- allowing without revocation check for %s", url)
+            continue
+
+        # Verify CRL signature if CA certs are available.
+        if issuer_certs is not None:
+            verify_crl(crl, issuer_certs, strict=config.strict)
+        else:
+            logger.debug(
+                "No issuer_certs provided; skipping CRL signature verification for %s", url
+            )
+
+        if crl.get_revoked_certificate_by_serial_number(cert.serial_number) is not None:
+            raise CertificateError(
+                f"Certificate has been revoked (serial {format(cert.serial_number, 'x')})"
+            )
+
+
+def get_crl(url: str, config: CRLConfig) -> x509.CertificateRevocationList:
+    """Return a parsed CRL for the given URL using a file-backed cache.
+
+    Strategy (stale-while-revalidate):
+      1. Fresh cache  -> return immediately.
+      2. Stale cache  -> return stale copy; spawn background thread to refresh.
+      3. No cache     -> fetch synchronously, cache result, return.
+    """
+    cache_dir = Path(config.cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    url_hash = hashlib.sha256(url.encode()).hexdigest()[:24]
+    cache_file = cache_dir / f"{url_hash}.crl"
+
+    try:
+        st = cache_file.stat()
+        age = time.time() - st.st_mtime
+        data = cache_file.read_bytes()
+    except FileNotFoundError:
+        data = None
+        age = float("inf")
+
+    if data is not None:
+        if age < config.cache_ttl:
+            return parse_crl_bytes(data)
+
+        # Cache is stale — check if it's too old to serve even as a fallback
+        if config.max_acceptable_age and age > config.max_acceptable_age:
+            logger.warning(
+                "CRL cache for %s is %.0fs old (max_acceptable_age=%d) -- forcing refresh",
+                url,
+                age,
+                config.max_acceptable_age,
+            )
+            return refresh_crl(url, cache_file, config)
+
+        logger.debug(
+            "CRL stale (%.0fs old) for %s -- serving cache, refreshing in background",
+            age,
+            url,
+        )
+        threading.Thread(
+            target=_refresh_crl_background,
+            args=(url, cache_file, config),
+            daemon=True,
+        ).start()
+        return parse_crl_bytes(data)
+
+    logger.debug("No CRL cache for %s -- fetching synchronously", url)
+    return refresh_crl(url, cache_file, config)
+
+
+def _refresh_crl_background(url: str, cache_file: Path, config: CRLConfig) -> None:
+    """Wrapper for background CRL refresh that logs exceptions.
+
+    Raises CRLRefreshError so that callers using a custom thread pool or
+    callback mechanism can observe the failure. In the default daemon-thread
+    usage, the exception is logged and then discarded.
+    """
+    try:
+        refresh_crl(url, cache_file, config)
+    except Exception as e:
+        logger.error("Background CRL refresh failed for %s: %s", url, e)
+        raise CRLRefreshError(f"Background CRL refresh failed for {url}: {e}") from e
+
+
+def refresh_crl(
+    url: str, cache_file: Path, config: CRLConfig | None = None
+) -> x509.CertificateRevocationList:
+    """Fetch a CRL from url, write it to cache_file, and return parsed CRL.
+
+    Called directly (blocking) when no cache exists, or from ``_refresh_crl_background``
+    when the cache is stale.  Raises ``ValueError`` if the response exceeds
+    ``config.max_crl_bytes``.
+    """
+    if config is None:
+        config = CRLConfig()
+    try:
+        resp = httpx.get(url, timeout=config.fetch_timeout, follow_redirects=True)
+        resp.raise_for_status()
+        data = resp.content
+        if len(data) > config.max_crl_bytes:
+            raise ValueError(
+                f"CRL from {url} exceeds size limit ({len(data)} > {config.max_crl_bytes} bytes)"
+            )
+        crl = parse_crl_bytes(data)
+        tmp = cache_file.with_suffix(".tmp")
+        fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, data)
+        finally:
+            os.close(fd)
+        tmp.rename(cache_file)
+        logger.debug("CRL cached from %s (%d bytes)", url, len(data))
+        return crl
+    except CertificateError:
+        raise
+    except Exception as e:
+        logger.error("Failed to fetch/cache CRL from %s: %s", url, e)
+        raise
+
+
+def parse_crl_bytes(data: bytes) -> x509.CertificateRevocationList:
+    """Load a CRL from DER bytes (common format) with PEM fallback."""
+    try:
+        return x509.load_der_x509_crl(data)
+    except Exception:
+        pass
+    try:
+        return x509.load_pem_x509_crl(data)
+    except Exception as e:
+        raise CertificateError(f"Failed to parse CRL: {e}") from e
+
+
+def prefetch_crls(cert: x509.Certificate, config: CRLConfig) -> dict[str, str]:
+    """Proactively fetch and cache CRLs for a certificate.
+
+    Intended for scheduled invocation (cron / Lambda) to keep the CRL cache
+    warm so that real requests never block on a network fetch.
+
+    Returns a dict mapping each CRL URL to "refreshed", "skipped (fresh)",
+    or "error: <message>".
+    """
+    urls = get_crl_distribution_points(cert)
+    if not urls:
+        return {}
+
+    cache_dir = Path(config.cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    results: dict[str, str] = {}
+
+    for url in urls:
+        url_hash = hashlib.sha256(url.encode()).hexdigest()[:24]
+        cache_file = cache_dir / f"{url_hash}.crl"
+        if cache_file.exists():
+            age = time.time() - cache_file.stat().st_mtime
+            if age < config.cache_ttl:
+                results[url] = "skipped (fresh)"
+                continue
+        try:
+            refresh_crl(url, cache_file, config)
+            results[url] = "refreshed"
+        except Exception as e:
+            results[url] = f"error: {e}"
+
+    return results
+
+
+def get_crl_max_age(cert: x509.Certificate, config: CRLConfig) -> float | None:
+    """Return the age in seconds of the oldest cached CRL for a certificate.
+
+    Returns None if no CRL distribution points are found.
+    Returns float("inf") if any CRL has no cached file yet.
+    """
+    urls = get_crl_distribution_points(cert)
+    if not urls:
+        return None
+
+    cache_dir = Path(config.cache_dir)
+    max_age: float | None = None
+
+    for url in urls:
+        url_hash = hashlib.sha256(url.encode()).hexdigest()[:24]
+        cache_file = cache_dir / f"{url_hash}.crl"
+        if not cache_file.exists():
+            return float("inf")
+        age = time.time() - cache_file.stat().st_mtime
+        if max_age is None or age > max_age:
+            max_age = age
+
+    return max_age