laidline 1.0.0__py3-none-any.whl

laidline/__init__.py

@@ -0,0 +1,32 @@
+"""Laidline: mark generative AI outputs inside your own pipeline.
+
+Public API: ``Marker``, ``MarkClient``, ``MarkContext``, ``MarkedAsset``, ``DetectResult``.
+
+The API classes are imported on first access (PEP 562), so ``import laidline.trust.verify`` or
+``laidline.licence.document`` does not load the marking stack (PIL, c2pa, numpy, torch): the licence, trust and
+issuer modules are importable in a verifier, an issuing service or a Lambda that marks nothing.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from laidline.core.api import DetectResult, MarkClient, MarkContext, MarkedAsset, Marker, SystemInfo
+
+__version__ = "1.0.0"
+__all__ = ["DetectResult", "MarkClient", "MarkContext", "MarkedAsset", "Marker", "SystemInfo", "__version__"]
+
+_API = frozenset(__all__) - {"__version__"}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _API:
+        from laidline.core import api
+
+        return getattr(api, name)
+    raise AttributeError(f"module 'laidline' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | _API)

laidline/c2pa/__init__.py

@@ -0,0 +1,4 @@
+"""C2PA manifest building and signing (c2pa-python with a callback signer, RFC 3161 timestamps from the configured TSA),
+signing backends (local PEM, AWS KMS, Vault/OpenBao Transit), CSRs, certificate validation, the time-based signing
+keyring and normalised validator verdicts.
+"""

laidline/c2pa/certs.py

@@ -0,0 +1,185 @@
+"""Certificate helpers: chain parsing, boot-time validation, own-anchor extraction and the development CA.
+
+Verified against c2pa-rs 0.90: the leaf MUST carry an Organization (O) in its subject (a CN-only subject makes
+c2pa-rs report ``claimSignature.mismatch``), SubjectKeyIdentifier and AuthorityKeyIdentifier, KU digitalSignature,
+and an EKU from c2pa-rs's accepted set (``ACCEPTED_EKUS``)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
+
+from laidline.core.errors import ConfigError
+
+EKU_ID_KP_DOCUMENT_SIGNING = x509.ObjectIdentifier("1.3.6.1.5.5.7.3.36")
+EKU_MS_C2PA = x509.ObjectIdentifier("1.3.6.1.4.1.311.76.59.1.9")
+EKU_C2PA_SIGNING = x509.ObjectIdentifier("1.3.6.1.4.1.62558.2.1")
+MS_DOCUMENT_SIGNING = x509.ObjectIdentifier("1.3.6.1.4.1.311.10.3.12")
+# c2pa-rs sdk/src/crypto/cose/valid_eku_oids.cfg (c2patool-v0.27.22), less timeStamping and OCSPSigning, which are not
+# for signing manifests. Microsoft Document Signing (MS_DOCUMENT_SIGNING) is not in it.
+ACCEPTED_EKUS: frozenset[x509.ObjectIdentifier] = frozenset(
+    {ExtendedKeyUsageOID.EMAIL_PROTECTION, EKU_ID_KP_DOCUMENT_SIGNING, EKU_MS_C2PA, EKU_C2PA_SIGNING}
+)
+
+
+def load_chain(pem: str) -> list[x509.Certificate]:
+    try:
+        certs = x509.load_pem_x509_certificates(pem.encode())
+    except ValueError as e:
+        raise ConfigError(f"certificate chain is empty or malformed: {e}") from e
+    if not certs:
+        raise ConfigError("certificate chain is empty")
+    return certs
+
+
+def cert_sha256(cert: x509.Certificate) -> str:
+    return hashlib.sha256(cert.public_bytes(serialization.Encoding.DER)).hexdigest()
+
+
+def own_anchor_pem(chain_pem: str) -> str:
+    return load_chain(chain_pem)[-1].public_bytes(serialization.Encoding.PEM).decode()
+
+
+def validate_signing_chain(
+    chain: list[x509.Certificate], backend_fingerprint: str, *, at: dt.datetime | None = None
+) -> None:
+    """Check the leaf against c2pa-rs's requirements and the backend's key. Validity is checked at ``at`` (default
+    now): a scheduled key is checked at its ``not_before``."""
+    leaf = chain[0]
+    now = at or dt.datetime.now(dt.UTC)
+    if not (leaf.not_valid_before_utc <= now <= leaf.not_valid_after_utc):
+        raise ConfigError("expired: signing certificate is outside its validity window")
+    if not leaf.subject.get_attributes_for_oid(NameOID.ORGANIZATION_NAME):
+        raise ConfigError(
+            "subject_organization: c2pa validators need an Organization (O) in the signing certificate subject"
+        )
+    try:
+        ku = leaf.extensions.get_extension_for_class(x509.KeyUsage).value
+    except x509.ExtensionNotFound as e:
+        raise ConfigError("ku_digital_signature: KeyUsage extension missing") from e
+    if not ku.digital_signature:
+        raise ConfigError("ku_digital_signature: KeyUsage lacks digitalSignature")
+    try:
+        eku = leaf.extensions.get_extension_for_class(x509.ExtendedKeyUsage).value
+    except x509.ExtensionNotFound as e:
+        raise ConfigError("eku: ExtendedKeyUsage extension missing") from e
+    if not ACCEPTED_EKUS.intersection(eku):
+        if MS_DOCUMENT_SIGNING in eku:
+            raise ConfigError(
+                "eku: 1.3.6.1.4.1.311.10.3.12 is Microsoft Document Signing, which C2PA validators do not accept; "
+                "use emailProtection or id-kp-documentSigning 1.3.6.1.5.5.7.3.36"
+            )
+        raise ConfigError(
+            "eku: ExtendedKeyUsage must include emailProtection (1.3.6.1.5.5.7.3.4), id-kp-documentSigning "
+            "(1.3.6.1.5.5.7.3.36), MS C2PA (1.3.6.1.4.1.311.76.59.1.9) or C2PA signing (1.3.6.1.4.1.62558.2.1)"
+        )
+    spki = leaf.public_key().public_bytes(serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo)
+    if hashlib.sha256(spki).hexdigest() != backend_fingerprint:
+        raise ConfigError("key_mismatch: signing certificate public key does not match the signing backend key")
+
+
+def _base(
+    subject: x509.Name,
+    issuer: x509.Name,
+    public_key: ec.EllipticCurvePublicKey,
+    issuer_key: ec.EllipticCurvePrivateKey,
+    days: int,
+) -> x509.CertificateBuilder:
+    now = dt.datetime.now(dt.UTC)
+    return (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(public_key)
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - dt.timedelta(days=1))
+        .not_valid_after(now + dt.timedelta(days=days))
+        .add_extension(x509.SubjectKeyIdentifier.from_public_key(public_key), critical=False)
+        .add_extension(x509.AuthorityKeyIdentifier.from_issuer_public_key(issuer_key.public_key()), critical=False)
+    )
+
+
+def _key_usage(*, ca: bool) -> x509.KeyUsage:
+    return x509.KeyUsage(
+        digital_signature=True,
+        content_commitment=not ca,
+        key_encipherment=False,
+        data_encipherment=False,
+        key_agreement=False,
+        key_cert_sign=ca,
+        crl_sign=ca,
+        encipher_only=False,
+        decipher_only=False,
+    )
+
+
+def _new_ca(org: str) -> tuple[ec.EllipticCurvePrivateKey, x509.Certificate]:
+    ca_key = ec.generate_private_key(ec.SECP256R1())
+    ca_name = x509.Name(
+        [
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, org),
+            x509.NameAttribute(NameOID.COMMON_NAME, f"{org} Laidline Dev CA"),
+        ]
+    )
+    ca = (
+        _base(ca_name, ca_name, ca_key.public_key(), ca_key, 3650)
+        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
+        .add_extension(_key_usage(ca=True), critical=True)
+        .sign(ca_key, hashes.SHA256())
+    )
+    return ca_key, ca
+
+
+def _issue_leaf(
+    ca_key: ec.EllipticCurvePrivateKey, ca: x509.Certificate, public_key: ec.EllipticCurvePublicKey, org: str, cn: str
+) -> x509.Certificate:
+    leaf_name = x509.Name(
+        [x509.NameAttribute(NameOID.ORGANIZATION_NAME, org), x509.NameAttribute(NameOID.COMMON_NAME, cn)]
+    )
+    return (
+        _base(leaf_name, ca.subject, public_key, ca_key, 365)
+        .add_extension(x509.BasicConstraints(ca=False, path_length=None), critical=True)
+        .add_extension(_key_usage(ca=False), critical=True)
+        .add_extension(x509.ExtendedKeyUsage([ExtendedKeyUsageOID.EMAIL_PROTECTION]), critical=True)
+        .sign(ca_key, hashes.SHA256())
+    )
+
+
+def generate_dev_chain(org: str, cn: str) -> tuple[str, str, str]:
+    """Returns (leaf_key_pem, chain_pem = leaf + ca, ca_pem).
+
+    Validators report 'valid, not trusted' unless the CA is loaded as an anchor."""
+    ca_key, ca = _new_ca(org)
+    leaf_key = ec.generate_private_key(ec.SECP256R1())
+    leaf = _issue_leaf(ca_key, ca, leaf_key.public_key(), org, cn)
+    key_pem = leaf_key.private_bytes(
+        serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption()
+    ).decode()
+    ca_pem = ca.public_bytes(serialization.Encoding.PEM).decode()
+    return key_pem, leaf.public_bytes(serialization.Encoding.PEM).decode() + ca_pem, ca_pem
+
+
+def generate_dev_chain_for_public_key(org: str, cn: str, public_key: ec.EllipticCurvePublicKey) -> tuple[str, str]:
+    """Issue a dev-CA leaf over a key that lives elsewhere (AWS KMS ``ECC_NIST_P256``). Returns (chain_pem, ca_pem);
+    there is no private key file. The CA key is discarded, so re-running mints a new CA; re-distribute
+    ``dev-ca.pem``."""
+    if not isinstance(public_key.curve, ec.SECP256R1):
+        raise ConfigError("signing key must be EC P-256 (KMS key spec ECC_NIST_P256) for ES256")
+    ca_key, ca = _new_ca(org)
+    leaf = _issue_leaf(ca_key, ca, public_key, org, cn)
+    ca_pem = ca.public_bytes(serialization.Encoding.PEM).decode()
+    return leaf.public_bytes(serialization.Encoding.PEM).decode() + ca_pem, ca_pem
+
+
+def signer_hashes(der: bytes) -> tuple[str, str]:
+    """``(spki_sha256, cert_sha256)`` of a DER certificate: SHA-256 hex of its SubjectPublicKeyInfo DER (what an issuer
+    certificate binds as ``signing_spki_sha256`` and ``SigningBackend.public_key_fingerprint`` returns) and of the
+    certificate itself (``SignResult.cert_sha256``). ``ValueError`` for bytes that are not a certificate."""
+    cert = x509.load_der_x509_certificate(der)
+    spki = cert.public_key().public_bytes(serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo)
+    return hashlib.sha256(spki).hexdigest(), hashlib.sha256(der).hexdigest()

laidline/c2pa/csr.py

@@ -0,0 +1,183 @@
+"""PKCS#10 certificate signing requests for keys held in AWS KMS, Vault/OpenBao Transit or a local PEM file.
+
+A managed key cannot sign through cryptography's ``CertificateSigningRequestBuilder`` (it needs a private key object),
+so the CSR is assembled around the backend:
+
+1. build a throwaway CSR with an ephemeral P-256 key carrying the subject and the extensionRequest;
+2. take its CertificationRequestInfo (``tbs_certrequest_bytes``: version, subject, subjectPKInfo, ``[0]`` attributes);
+3. swap the subjectPKInfo for the managed key's SPKI DER and re-encode the outer length;
+4. sign the new CertificationRequestInfo with ``backend.sign`` (ECDSA P-256 over SHA-256, P-1363 ``r||s``) and convert
+   the signature to DER;
+5. assemble ``SEQUENCE { CRI, SEQUENCE { OID ecdsa-with-SHA256 }, BIT STRING 00||sig }``;
+6. load the result with cryptography and check the signature and the SPKI before returning it.
+
+Only the public key leaves the KMS or Vault; the ephemeral key is discarded.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Literal
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
+
+from laidline.c2pa.certs import EKU_ID_KP_DOCUMENT_SIGNING
+from laidline.c2pa.signer import SigningBackend
+from laidline.core.errors import ConfigError, MarkError
+
+Eku = Literal["email", "document-signing", "both"]
+
+# AlgorithmIdentifier { OID 1.2.840.10045.4.3.2 ecdsa-with-SHA256 } with absent parameters (RFC 5758 section 3.2).
+ECDSA_WITH_SHA256 = bytes.fromhex("300a06082a8648ce3d040302")
+
+_EKUS: dict[str, list[x509.ObjectIdentifier]] = {
+    "email": [ExtendedKeyUsageOID.EMAIL_PROTECTION],
+    "document-signing": [EKU_ID_KP_DOCUMENT_SIGNING],
+    "both": [ExtendedKeyUsageOID.EMAIL_PROTECTION, EKU_ID_KP_DOCUMENT_SIGNING],
+}
+
+
+def read_tlv(buf: bytes, off: int) -> tuple[int, int, int]:
+    """Parse the DER header at ``buf[off]``: ``(tag, header_len, length)``. Single-byte tags and definite, minimally
+    encoded lengths only; the value must fit in ``buf``. Anything else raises ``ValueError``."""
+    if off < 0 or off + 2 > len(buf):
+        raise ValueError(f"DER truncated at offset {off}: no tag and length")
+    tag, first = buf[off], buf[off + 1]
+    if tag & 0x1F == 0x1F:
+        raise ValueError(f"DER multi-byte tag at offset {off} not supported")
+    if first < 0x80:
+        header_len, length = 2, first
+    elif first == 0x80:
+        raise ValueError(f"DER indefinite length at offset {off}")
+    else:
+        n = first & 0x7F
+        if n > 4:
+            raise ValueError(f"DER length of {n} bytes at offset {off} is too long")
+        if off + 2 + n > len(buf):
+            raise ValueError(f"DER truncated at offset {off}: length bytes missing")
+        length = int.from_bytes(buf[off + 2 : off + 2 + n], "big")
+        if length < 0x80 or buf[off + 2] == 0:
+            raise ValueError(f"DER length at offset {off} is not minimally encoded")
+        header_len = 2 + n
+    if off + header_len + length > len(buf):
+        raise ValueError(f"DER truncated at offset {off}: {length} value bytes declared, fewer present")
+    return tag, header_len, length
+
+
+def encode_len(n: int) -> bytes:
+    """DER length octets for ``n``."""
+    if n < 0:
+        raise ValueError("negative length")
+    if n < 0x80:
+        return bytes([n])
+    body = n.to_bytes((n.bit_length() + 7) // 8, "big")
+    return bytes([0x80 | len(body)]) + body
+
+
+def tlv(tag: int, body: bytes) -> bytes:
+    return bytes([tag]) + encode_len(len(body)) + body
+
+
+def _children(buf: bytes) -> list[bytes]:
+    """The complete TLVs inside the constructed value ``buf`` (header included), which must be consumed exactly."""
+    out: list[bytes] = []
+    off = 0
+    while off < len(buf):
+        _, header_len, length = read_tlv(buf, off)
+        out.append(buf[off : off + header_len + length])
+        off += header_len + length
+    return out
+
+
+def _swap_spki(cri: bytes, spki: bytes) -> bytes:
+    """Replace the subjectPKInfo of a CertificationRequestInfo SEQUENCE with ``spki``."""
+    tag, header_len, length = read_tlv(cri, 0)
+    if tag != 0x30 or header_len + length != len(cri):
+        raise ValueError("CertificationRequestInfo is not a single DER SEQUENCE")
+    children = _children(cri[header_len:])
+    if len(children) != 4 or [c[0] for c in children] != [0x02, 0x30, 0x30, 0xA0]:
+        raise ValueError("CertificationRequestInfo is not version, subject, subjectPKInfo, [0] attributes")
+    children[2] = spki
+    return tlv(0x30, b"".join(children))
+
+
+def _template(org: str, cn: str, country: str | None, eku: Eku) -> bytes:
+    """Steps 1-2: the CertificationRequestInfo of a throwaway CSR over an ephemeral P-256 key."""
+    attrs = [x509.NameAttribute(NameOID.COUNTRY_NAME, country)] if country else []
+    attrs += [x509.NameAttribute(NameOID.ORGANIZATION_NAME, org), x509.NameAttribute(NameOID.COMMON_NAME, cn)]
+    ku = x509.KeyUsage(
+        digital_signature=True,
+        content_commitment=False,
+        key_encipherment=False,
+        data_encipherment=False,
+        key_agreement=False,
+        key_cert_sign=False,
+        crl_sign=False,
+        encipher_only=False,
+        decipher_only=False,
+    )
+    throwaway = (
+        x509.CertificateSigningRequestBuilder()
+        .subject_name(x509.Name(attrs))
+        .add_extension(ku, critical=True)
+        .add_extension(x509.ExtendedKeyUsage(_EKUS[eku]), critical=False)
+        .sign(ec.generate_private_key(ec.SECP256R1()), hashes.SHA256())
+    )
+    return throwaway.tbs_certrequest_bytes
+
+
+def build_csr(
+    backend: SigningBackend,
+    *,
+    org: str,
+    cn: str,
+    country: str | None = None,
+    eku: Eku = "email",
+) -> x509.CertificateSigningRequest:
+    """A CSR for ``backend``'s key, signed by the backend (ECDSA with SHA-256). Subject ``C`` (optional), ``O``, ``CN``;
+    extensionRequest KU digitalSignature (critical) and the EKU ``eku`` names. Raises ``ConfigError`` for bad input or a
+    key that is not ES256 on P-256, and ``MarkError("csr_invalid")`` when the assembled CSR does not verify."""
+    if not org:
+        raise ConfigError("csr: an Organization (O) is required; c2pa validators need it in the leaf subject")
+    if not cn:
+        raise ConfigError("csr: a Common Name (CN) is required")
+    if country is not None and (len(country) != 2 or not country.isascii() or not country.isalpha()):
+        raise ConfigError(f"csr: country (C) must be a two-letter ISO 3166 code (got {country!r})")
+    if eku not in _EKUS:
+        raise ConfigError(f"csr: eku must be one of {', '.join(_EKUS)} (got {eku})")
+    if backend.alg != "es256":
+        raise ConfigError(f"csr: the signing key must be ES256 on P-256 (got {backend.alg})")
+    public_key = backend.public_key()
+    if not isinstance(public_key, ec.EllipticCurvePublicKey) or not isinstance(public_key.curve, ec.SECP256R1):
+        raise ConfigError("csr: the signing key must be EC P-256 (ES256)")
+    spki = public_key.public_bytes(serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo)
+    try:
+        cri = _swap_spki(_template(org, cn, country, eku), spki)
+    except ValueError as e:
+        raise MarkError("csr_invalid", f"cannot re-encode the CertificationRequestInfo: {e}") from e
+    raw = backend.sign(cri)  # the backend hashes with SHA-256: an ecdsa-with-SHA256 signature over the CRI
+    if len(raw) != 64:
+        raise MarkError("csr_invalid", f"backend returned a {len(raw)}-byte signature, expected 64 (P-1363 r||s)")
+    sig = encode_dss_signature(int.from_bytes(raw[:32], "big"), int.from_bytes(raw[32:], "big"))
+    der = tlv(0x30, cri + ECDSA_WITH_SHA256 + tlv(0x03, b"\x00" + sig))
+    try:
+        csr = x509.load_der_x509_csr(der)
+        valid = csr.is_signature_valid
+        csr_spki = csr.public_key().public_bytes(
+            serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+    except ValueError as e:
+        raise MarkError("csr_invalid", f"assembled CSR does not parse: {e}") from e
+    if not valid:
+        raise MarkError("csr_invalid", "the CSR signature does not verify against the backend's public key")
+    if csr_spki != spki or hashlib.sha256(csr_spki).hexdigest() != backend.public_key_fingerprint():
+        raise MarkError("csr_invalid", "the CSR public key is not the backend's key")
+    return csr
+
+
+def csr_pem(csr: x509.CertificateSigningRequest) -> bytes:
+    return csr.public_bytes(serialization.Encoding.PEM)