provide-foundation 0.0.0.dev0__py3-none-any.whl → 0.0.0.dev1__py3-none-any.whl

provide/foundation/crypto/certificates/factory.py

@@ -0,0 +1,213 @@
+"""Certificate factory methods."""
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import CertificateError, _require_crypto
+from provide.foundation.crypto.certificates.operations import create_x509_certificate
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+
+
+def create_ca_certificate(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+) -> "Certificate":
+    """Creates a new self-signed CA certificate."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new CA certificate: CN={common_name}, Org={organization_name}"
+    )
+    ca_cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+        alt_names=[common_name],
+    )
+    # Re-sign to ensure CA flags are correctly set for a CA
+    logger.info("📜🔑🏭 Re-signing generated CA certificate to ensure is_ca=True")
+    actual_ca_x509_cert = create_x509_certificate(
+        base=ca_cert_obj._base,
+        private_key=ca_cert_obj._private_key,
+        alt_names=ca_cert_obj.alt_names,
+        is_ca=True,
+        is_client_cert=False,
+    )
+    ca_cert_obj._cert = actual_ca_x509_cert
+    ca_cert_obj.cert = actual_ca_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    return ca_cert_obj
+
+
+def create_signed_certificate(
+    ca_certificate: "Certificate",
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    alt_names: list[str] | None = None,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    is_client_cert: bool = False,
+) -> "Certificate":
+    """Creates a new certificate signed by the provided CA certificate."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new certificate signed by CA '{ca_certificate.subject}': "
+        f"CN={common_name}, Org={organization_name}, ClientCert={is_client_cert}"
+    )
+    if not ca_certificate._private_key:
+        raise CertificateError(
+            message="CA certificate's private key is not available for signing.",
+            hint="Ensure the CA certificate object was loaded or created with its private key.",
+        )
+    if not ca_certificate.is_ca:
+        logger.warning(
+            f"📜🔑⚠️ Signing certificate (Subject: {ca_certificate.subject}) "
+            "is not marked as a CA. This might lead to validation issues."
+        )
+    
+    new_cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+    )
+    
+    signed_x509_cert = create_x509_certificate(
+        base=new_cert_obj._base,
+        private_key=new_cert_obj._private_key,
+        alt_names=new_cert_obj.alt_names,
+        issuer_name_override=ca_certificate._base.subject,
+        signing_key_override=ca_certificate._private_key,
+        is_ca=False,
+        is_client_cert=is_client_cert,
+    )
+    
+    new_cert_obj._cert = signed_x509_cert
+    new_cert_obj.cert = signed_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    
+    logger.info(
+        f"📜🔑✅ Successfully created and signed certificate for "
+        f"CN={common_name} by CA='{ca_certificate.subject}'"
+    )
+    return new_cert_obj
+
+
+def create_self_signed_server_cert(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    alt_names: list[str] | None = None,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+) -> "Certificate":
+    """Creates a new self-signed end-entity certificate suitable for a server."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new self-signed SERVER certificate: "
+        f"CN={common_name}, Org={organization_name}"
+    )
+    
+    cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+    )
+    
+    if not cert_obj._private_key:
+        raise CertificateError(
+            "Private key not generated for self-signed server certificate"
+        )
+    
+    actual_x509_cert = create_x509_certificate(
+        base=cert_obj._base,
+        private_key=cert_obj._private_key,
+        alt_names=cert_obj.alt_names,
+        is_ca=False,
+        is_client_cert=False,
+    )
+    
+    cert_obj._cert = actual_x509_cert
+    cert_obj.cert = actual_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    
+    logger.info(
+        f"📜🔑✅ Successfully created self-signed SERVER certificate for CN={common_name}"
+    )
+    return cert_obj
+
+
+# Convenience functions for common use cases
+def create_self_signed(
+    common_name: str = "localhost",
+    alt_names: list[str] | None = None,
+    organization: str = "Default Organization",
+    validity_days: int = DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+) -> "Certificate":
+    """Create a self-signed certificate (convenience function)."""
+    _require_crypto()
+    return create_self_signed_server_cert(
+        common_name=common_name,
+        organization_name=organization,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+    )
+
+
+def create_ca(
+    common_name: str,
+    organization: str = "Default CA Organization",
+    validity_days: int = DEFAULT_CERTIFICATE_VALIDITY_DAYS * 2,  # CAs live longer
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+) -> "Certificate":
+    """Create a CA certificate (convenience function)."""
+    _require_crypto()
+    return create_ca_certificate(
+        common_name=common_name,
+        organization_name=organization,
+        validity_days=validity_days,
+        key_type=key_type,
+    )

provide/foundation/crypto/certificates/generator.py

@@ -0,0 +1,138 @@
+"""Certificate generation utilities."""
+
+from datetime import UTC, datetime, timedelta
+import traceback
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, rsa
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    ec = None
+    rsa = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import (
+    CertificateBase,
+    CertificateConfig,
+    CertificateError,
+    CurveType,
+    KeyType,
+)
+from provide.foundation.crypto.certificates.operations import create_x509_certificate
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+
+
+def generate_certificate(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    alt_names: list[str] | None = None,
+    is_ca: bool = False,
+    is_client_cert: bool = False,
+) -> tuple[CertificateBase, "x509.Certificate", "rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey", str, str]:
+    """
+    Generate a new certificate with a keypair.
+    
+    Returns:
+        Tuple of (CertificateBase, X509Certificate, private_key, cert_pem, key_pem)
+    """
+    try:
+        logger.debug("📜🔑🚀 Generating new keypair")
+        
+        now = datetime.now(UTC)
+        not_valid_before = now - timedelta(days=1)
+        not_valid_after = now + timedelta(days=validity_days)
+        
+        # Parse key type
+        normalized_key_type_str = key_type.lower()
+        match normalized_key_type_str:
+            case "rsa":
+                gen_key_type = KeyType.RSA
+            case "ecdsa":
+                gen_key_type = KeyType.ECDSA
+            case _:
+                raise ValueError(
+                    f"Unsupported key_type string: '{key_type}'. "
+                    "Must be 'rsa' or 'ecdsa'."
+                )
+        
+        # Configure key parameters
+        gen_curve: CurveType | None = None
+        gen_key_size = None
+        
+        if gen_key_type == KeyType.ECDSA:
+            try:
+                gen_curve = CurveType[ecdsa_curve.upper()]
+            except KeyError as e_curve:
+                raise ValueError(
+                    f"Unsupported ECDSA curve: {ecdsa_curve}"
+                ) from e_curve
+        else:  # RSA
+            gen_key_size = key_size
+        
+        # Build configuration
+        conf: CertificateConfig = {
+            "common_name": common_name,
+            "organization": organization_name,
+            "alt_names": alt_names or ["localhost"],
+            "key_type": gen_key_type,
+            "not_valid_before": not_valid_before,
+            "not_valid_after": not_valid_after,
+        }
+        if gen_curve is not None:
+            conf["curve"] = gen_curve
+        if gen_key_size is not None:
+            conf["key_size"] = gen_key_size
+        logger.debug(f"📜🔑🚀 Generation config: {conf}")
+        
+        # Generate base certificate and private key
+        base, private_key = CertificateBase.create(conf)
+        
+        # Create X.509 certificate
+        x509_cert = create_x509_certificate(
+            base=base,
+            private_key=private_key,
+            alt_names=alt_names or ["localhost"],
+            is_ca=is_ca,
+            is_client_cert=is_client_cert,
+        )
+        
+        if x509_cert is None:
+            raise CertificateError(
+                "Certificate object (_cert) is None after creation"
+            )
+        
+        # Convert to PEM format
+        cert_pem = x509_cert.public_bytes(serialization.Encoding.PEM).decode("utf-8")
+        key_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        ).decode("utf-8")
+        
+        logger.debug("📜🔑✅ Generated cert and key")
+        
+        return base, x509_cert, private_key, cert_pem, key_pem
+        
+    except Exception as e:
+        logger.error(
+            f"📜❌ Failed to generate certificate. Error: {type(e).__name__}: {e}",
+            extra={"error": str(e), "trace": traceback.format_exc()},
+        )
+        raise CertificateError(
+            f"Failed to initialize certificate. Original error: {type(e).__name__}"
+        ) from e

provide/foundation/crypto/certificates/loader.py

@@ -0,0 +1,130 @@
+"""Certificate loading utilities."""
+
+from datetime import UTC
+import os
+from pathlib import Path
+import traceback
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, rsa
+    from cryptography.hazmat.primitives.serialization import load_pem_private_key
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    ec = None
+    rsa = None
+    load_pem_private_key = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import CertificateBase, CertificateError
+
+
+def load_from_uri_or_pem(data: str) -> str:
+    """Load PEM data either directly from a string or from a file URI."""
+    try:
+        if data.startswith("file://"):
+            path_str = data.removeprefix("file://")
+            if os.name == "nt" and path_str.startswith("//"):
+                path = Path(path_str)
+            else:
+                path_str = path_str.lstrip("/")
+                if os.name != "nt" and data.startswith("file:///"):
+                    path_str = "/" + path_str
+                path = Path(path_str)
+
+            logger.debug(f"📜📂🚀 Loading data from file: {path}")
+            with path.open("r", encoding="utf-8") as f:
+                loaded_data = f.read().strip()
+            logger.debug("📜📂✅ Loaded data from file")
+            return loaded_data
+
+        loaded_data = data.strip()
+        if not loaded_data.startswith("-----BEGIN"):
+            logger.warning("📜📂⚠️ Data doesn't look like PEM format")
+        return loaded_data
+    except Exception as e:
+        logger.error(f"📜📂❌ Failed to load data: {e}", extra={"error": str(e)})
+        raise CertificateError(f"Failed to load data: {e}") from e
+
+
+def load_certificate_from_pem(
+    cert_pem_or_uri: str, 
+    key_pem_or_uri: str | None = None
+) -> tuple[CertificateBase, "x509.Certificate", "rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey | None", str, str | None]:
+    """
+    Load a certificate and optionally its private key from PEM data or file URIs.
+    
+    Returns:
+        Tuple of (CertificateBase, X509Certificate, private_key, cert_pem, key_pem)
+    """
+    try:
+        logger.debug("📜🔑🚀 Loading certificate from provided data")
+        cert_data = load_from_uri_or_pem(cert_pem_or_uri)
+        
+        logger.debug("📜🔑🔍 Loading X.509 certificate from PEM data")
+        x509_cert = x509.load_pem_x509_certificate(cert_data.encode("utf-8"))
+        logger.debug("📜🔑✅ X.509 certificate object loaded from PEM")
+        
+        private_key = None
+        key_data = None
+        
+        if key_pem_or_uri:
+            logger.debug("📜🔑🚀 Loading private key")
+            key_data = load_from_uri_or_pem(key_pem_or_uri)
+            
+            loaded_priv_key = load_pem_private_key(
+                key_data.encode("utf-8"), password=None
+            )
+            if not isinstance(
+                loaded_priv_key,
+                rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey,
+            ):
+                raise CertificateError(
+                    f"Loaded private key is of unsupported type: {type(loaded_priv_key)}. "
+                    "Expected RSA or ECDSA private key."
+                )
+            private_key = loaded_priv_key
+            logger.debug("📜🔑✅ Private key object loaded and type validated")
+        
+        # Extract certificate details for CertificateBase
+        loaded_not_valid_before = x509_cert.not_valid_before_utc
+        loaded_not_valid_after = x509_cert.not_valid_after_utc
+        if loaded_not_valid_before.tzinfo is None:
+            loaded_not_valid_before = loaded_not_valid_before.replace(tzinfo=UTC)
+        if loaded_not_valid_after.tzinfo is None:
+            loaded_not_valid_after = loaded_not_valid_after.replace(tzinfo=UTC)
+        
+        cert_public_key = x509_cert.public_key()
+        if not isinstance(
+            cert_public_key, rsa.RSAPublicKey | ec.EllipticCurvePublicKey
+        ):
+            raise CertificateError(
+                f"Certificate's public key is of unsupported type: {type(cert_public_key)}. "
+                "Expected RSA or ECDSA public key."
+            )
+        
+        base = CertificateBase(
+            subject=x509_cert.subject,
+            issuer=x509_cert.issuer,
+            public_key=cert_public_key,
+            not_valid_before=loaded_not_valid_before,
+            not_valid_after=loaded_not_valid_after,
+            serial_number=x509_cert.serial_number,
+        )
+        logger.debug("📜🔑✅ Reconstructed CertificateBase from loaded cert")
+        
+        return base, x509_cert, private_key, cert_data, key_data
+        
+    except Exception as e:
+        logger.error(
+            f"📜❌ Failed to load certificate. Error: {type(e).__name__}: {e}",
+            extra={"error": str(e), "trace": traceback.format_exc()},
+        )
+        raise CertificateError(
+            f"Failed to initialize certificate. Original error: {type(e).__name__}"
+        ) from e

provide/foundation/crypto/certificates/operations.py

@@ -0,0 +1,198 @@
+"""Certificate operations: CA creation, signing, and trust verification."""
+
+import traceback
+from typing import cast
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
+    from cryptography.x509 import Certificate as X509Certificate
+    from cryptography.x509.oid import ExtendedKeyUsageOID
+
+    _HAS_CRYPTO = True
+except ImportError:
+    # Stub out cryptography types for type hints
+    x509 = None
+    hashes = None
+    serialization = None
+    ec = None
+    padding = None
+    rsa = None
+    X509Certificate = None
+    ExtendedKeyUsageOID = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+from .base import CertificateBase, CertificateError, KeyPair, PublicKey
+
+
+def create_x509_certificate(
+    base: CertificateBase,
+    private_key: "KeyPair",
+    alt_names: list[str] | None = None,
+    issuer_name_override: "x509.Name | None" = None,
+    signing_key_override: "KeyPair | None" = None,
+    is_ca: bool = False,
+    is_client_cert: bool = False,
+) -> "X509Certificate":
+    """Internal helper to build and sign the X.509 certificate object."""
+    try:
+        logger.debug("📜📝🚀 create_x509_certificate: Building certificate")
+
+        actual_issuer_name = issuer_name_override if issuer_name_override else base.issuer
+        actual_signing_key = signing_key_override if signing_key_override else private_key
+
+        if not actual_signing_key:
+            raise CertificateError(
+                "Cannot sign certificate without a signing key (either own or override)"
+            )
+
+        builder = (
+            x509.CertificateBuilder()
+            .subject_name(base.subject)
+            .issuer_name(actual_issuer_name)
+            .public_key(base.public_key)
+            .serial_number(base.serial_number)
+            .not_valid_before(base.not_valid_before)
+            .not_valid_after(base.not_valid_after)
+        )
+
+        san_list = [x509.DNSName(name) for name in (alt_names or []) if name]
+        if san_list:
+            builder = builder.add_extension(
+                x509.SubjectAlternativeName(san_list), critical=False
+            )
+            logger.debug(f"📜📝✅ Added SANs: {alt_names or []}")
+
+        builder = builder.add_extension(
+            x509.BasicConstraints(ca=is_ca, path_length=None),
+            critical=True,
+        )
+
+        if is_ca:
+            builder = builder.add_extension(
+                x509.KeyUsage(
+                    digital_signature=False,
+                    key_encipherment=False,
+                    key_agreement=False,
+                    content_commitment=False,
+                    data_encipherment=False,
+                    key_cert_sign=True,
+                    crl_sign=True,
+                    encipher_only=False,
+                    decipher_only=False,
+                ),
+                critical=True,
+            )
+        else:
+            builder = builder.add_extension(
+                x509.KeyUsage(
+                    digital_signature=True,
+                    key_encipherment=(
+                        True
+                        if not is_client_cert
+                        and isinstance(base.public_key, rsa.RSAPublicKey)
+                        else False
+                    ),
+                    key_agreement=(
+                        True
+                        if isinstance(base.public_key, ec.EllipticCurvePublicKey)
+                        else False
+                    ),
+                    content_commitment=False,
+                    data_encipherment=False,
+                    key_cert_sign=False,
+                    crl_sign=False,
+                    encipher_only=False,
+                    decipher_only=False,
+                ),
+                critical=True,
+            )
+            extended_usages = []
+            if is_client_cert:
+                extended_usages.append(ExtendedKeyUsageOID.CLIENT_AUTH)
+            else:
+                extended_usages.append(ExtendedKeyUsageOID.SERVER_AUTH)
+
+            if extended_usages:
+                builder = builder.add_extension(
+                    x509.ExtendedKeyUsage(extended_usages),
+                    critical=False,
+                )
+
+        logger.debug(
+            f"📜📝✅ Added BasicConstraints (is_ca={is_ca}), "
+            f"KeyUsage, ExtendedKeyUsage (is_client_cert={is_client_cert})"
+        )
+
+        signed_cert = builder.sign(
+            private_key=actual_signing_key,
+            algorithm=hashes.SHA256(),
+        )
+        logger.debug("📜📝✅ Certificate signed successfully")
+        return signed_cert
+
+    except Exception as e:
+        logger.error(
+            f"📜❌ create_x509_certificate: Failed: {e}",
+            extra={"error": str(e), "trace": traceback.format_exc()},
+        )
+        raise CertificateError("Failed to create X.509 certificate object") from e
+
+
+def validate_signature(signed_cert_obj: "X509Certificate", signing_cert_obj: "X509Certificate", signing_public_key: "PublicKey") -> bool:
+    """Internal helper: Validates signature and issuer/subject match."""
+    if signed_cert_obj.issuer != signing_cert_obj.subject:
+        logger.debug(
+            f"📜🔍❌ Signature validation failed: Issuer/Subject mismatch. "
+            f"Signed Issuer='{signed_cert_obj.issuer}', "
+            f"Signing Subject='{signing_cert_obj.subject}'"
+        )
+        return False
+
+    try:
+        if not signing_public_key:
+            logger.error(
+                "📜🔍❌ Cannot validate signature: Signing certificate has no public key"
+            )
+            return False
+
+        signature = signed_cert_obj.signature
+        tbs_certificate_bytes = signed_cert_obj.tbs_certificate_bytes
+        signature_hash_algorithm = signed_cert_obj.signature_hash_algorithm
+
+        if not signature_hash_algorithm:
+            logger.error("📜🔍❌ Cannot validate signature: Unknown hash algorithm")
+            return False
+
+        if isinstance(signing_public_key, rsa.RSAPublicKey):
+            cast(rsa.RSAPublicKey, signing_public_key).verify(
+                signature,
+                tbs_certificate_bytes,
+                padding.PKCS1v15(),
+                signature_hash_algorithm,
+            )
+        elif isinstance(signing_public_key, ec.EllipticCurvePublicKey):
+            cast(ec.EllipticCurvePublicKey, signing_public_key).verify(
+                signature,
+                tbs_certificate_bytes,
+                ec.ECDSA(signature_hash_algorithm),
+            )
+        else:
+            logger.error(
+                f"📜🔍❌ Unsupported signing public key type: {type(signing_public_key)}"
+            )
+            return False
+
+        return True
+
+    except Exception as e:
+        logger.debug(f"📜🔍❌ Signature validation failed: {type(e).__name__}: {e}")
+        return False