aspose-pdf-foss-for-python 0.1.0__py3-none-any.whl

aspose_pdf/_pending_signatures.py

@@ -0,0 +1,222 @@
+"""What ``Document.sign``, ``add_ltv`` and ``add_document_timestamp`` leave for ``save``.
+
+A signature covers bytes, so it can only be made once the document has been
+serialized: each call records what to do, and ``Document.save`` does it, in call
+order, to the bytes it is about to write -- each as an incremental revision, so
+an earlier signature in the same save stays valid under a later one. The
+arguments are checked when the call is made, so a mistake surfaces there rather
+than halfway through a save that may already have asked a timestamp authority
+for a token.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed448, ed25519, rsa
+from cryptography.x509 import ocsp
+from cryptography.x509.oid import NameOID
+
+from aspose_pdf.engine.dss import DssMaterial, add_document_timestamp, enable_ltv
+from aspose_pdf.engine.sign_field import sign_field
+from aspose_pdf.exceptions import PdfValidationException
+from aspose_pdf.validation import CertificationLevel
+
+_KEY_TYPES = (
+    rsa.RSAPrivateKey,
+    ec.EllipticCurvePrivateKey,
+    ed25519.Ed25519PrivateKey,
+    ed448.Ed448PrivateKey,
+)
+# PKCS#7 (``adbe.pkcs7.detached``) goes through ``cryptography``'s builder,
+# which signs with RSA and EC keys only; the CAdES builder also takes Ed25519.
+_PKCS7_KEY_TYPES = (rsa.RSAPrivateKey, ec.EllipticCurvePrivateKey)
+
+
+def _public_key_der(key: Any) -> bytes:
+    return key.public_bytes(
+        serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+    )
+
+
+def _check_pair(certificate: Any, private_key: Any, role: str) -> None:
+    if not isinstance(certificate, x509.Certificate):
+        raise TypeError(f"The {role} certificate must be a cryptography x509.Certificate")
+    if not isinstance(private_key, _KEY_TYPES):
+        raise TypeError(f"The {role} private key must be an RSA, EC or Ed25519 private key")
+    # A key that is not the certificate's makes a signature that no validator
+    # accepts; nothing further along notices, so it is caught here.
+    if _public_key_der(private_key.public_key()) != _public_key_der(certificate.public_key()):
+        raise PdfValidationException(f"The {role} private key does not belong to its certificate")
+
+
+def certificate_common_name(certificate: Any) -> str | None:
+    """The name to show for *certificate*'s holder, or ``None``.
+
+    A visible signature says who signed, and the certificate is the one place
+    that already knows. The subject's **common name** is what every other
+    producer shows; an organization certificate that has none falls back to
+    its organization name, and a certificate with neither is left for the
+    caller's own ``signer_name``.
+    """
+    for oid in (NameOID.COMMON_NAME, NameOID.ORGANIZATION_NAME):
+        for attribute in certificate.subject.get_attributes_for_oid(oid):
+            value = attribute.value
+            if isinstance(value, bytes):  # a non-UTF-8 directory string
+                value = value.decode("utf-8", "replace")
+            text = str(value).strip()
+            if text:
+                return text
+    return None
+
+
+def check_signer(certificate: Any, private_key: Any, *, pades: bool) -> None:
+    """Refuse a certificate and key that could not make a verifiable signature."""
+    _check_pair(certificate, private_key, "signer")
+    if isinstance(private_key, ed448.Ed448PrivateKey):
+        # RFC 8419: Ed448 in CMS digests with SHAKE256, not produced here.
+        raise PdfValidationException(
+            "Ed448 keys are not supported for signing: an Ed448 signature "
+            "digests with SHAKE256 (RFC 8419), which this signer does not produce"
+        )
+    if not pades and not isinstance(private_key, _PKCS7_KEY_TYPES):
+        raise PdfValidationException(
+            f"A {type(private_key).__name__} signs only with pades=True: the "
+            "adbe.pkcs7.detached encoder takes RSA and EC keys"
+        )
+
+
+def check_timestamp_source(url: Any, authority: Any) -> tuple[Any, Any] | None:
+    """Validate a timestamp URL or local authority; return the authority as a pair."""
+    if url is not None and authority is not None:
+        raise PdfValidationException(
+            "Give a timestamp_url or a timestamp_authority, not both"
+        )
+    if url is not None and (not isinstance(url, str) or not url):
+        raise TypeError("timestamp_url must be a non-empty string")
+    if authority is None:
+        return None
+    try:
+        certificate, private_key = authority
+    except (TypeError, ValueError):
+        raise TypeError(
+            "timestamp_authority must be a (certificate, private_key) pair"
+        ) from None
+    _check_pair(certificate, private_key, "timestamp authority")
+    # The local authority signs its tokens with RSA PKCS#1 v1.5.
+    if not isinstance(private_key, rsa.RSAPrivateKey):
+        raise PdfValidationException("A local timestamp authority needs an RSA key")
+    return certificate, private_key
+
+
+def certification_level(value: Any) -> int | None:
+    """The DocMDP ``/P`` a ``certify`` argument asks for, or ``None``."""
+    if value is None or value is CertificationLevel.NOT_CERTIFIED:
+        return None
+    if isinstance(value, CertificationLevel):
+        return value.value
+    if isinstance(value, bool) or not isinstance(value, int) or value not in (1, 2, 3):
+        raise PdfValidationException(
+            "certify must be a CertificationLevel or a DocMDP level 1, 2 or 3"
+        )
+    return value
+
+
+def der_items(values: Iterable[Any], kind: str) -> list[bytes]:
+    """DER bytes for each certificate, CRL or OCSP response in *values*."""
+    if isinstance(values, (bytes, bytearray)):
+        raise TypeError(f"{kind} must be a sequence of items, not one bytes value")
+    out: list[bytes] = []
+    for value in values:
+        if isinstance(value, (bytes, bytearray)):
+            out.append(bytes(value))
+        elif isinstance(
+            value,
+            (x509.Certificate, x509.CertificateRevocationList, ocsp.OCSPResponse),
+        ):
+            out.append(value.public_bytes(serialization.Encoding.DER))
+        else:
+            raise TypeError(
+                f"{kind} items must be DER bytes or cryptography objects, "
+                f"not {type(value).__name__}"
+            )
+    return out
+
+
+@dataclass(frozen=True)
+class PendingSignature:
+    """A signature to put into field *field* when the document is saved."""
+
+    field: str
+    certificate: Any
+    private_key: Any
+    extra_certificates: tuple[Any, ...]
+    reason: str | None
+    location: str | None
+    contact: str | None
+    signer_name: str | None
+    pades: bool
+    timestamp_url: str | None
+    timestamp_authority: tuple[Any, Any] | None
+    timestamp_timeout: float
+    certify: int | None
+    #: How the signature is drawn, or ``None`` for an invisible one. It is not
+    #: used here: the appearance is written into the widget before the document
+    #: is serialized, so the signature covers it (see
+    #: ``Document._flush_signature_appearances``).
+    appearance: Any = None
+
+    def apply(self, data: bytes, *, encryption: Any, limits: Any) -> bytes:
+        return sign_field(
+            data,
+            self.field,
+            self.certificate,
+            self.private_key,
+            pades=self.pades,
+            reason=self.reason,
+            location=self.location,
+            contact=self.contact,
+            signer_name=self.signer_name,
+            extra_certs=list(self.extra_certificates) or None,
+            tsa=self.timestamp_authority,
+            timestamp_url=self.timestamp_url,
+            timestamp_timeout=self.timestamp_timeout,
+            certify_permissions=self.certify,
+            limits=limits,
+            encryption=encryption,
+        )
+
+
+@dataclass(frozen=True)
+class PendingLtv:
+    """A ``/DSS`` to add, or extend, when the document is saved."""
+
+    material: DssMaterial
+
+    def apply(self, data: bytes, *, encryption: Any, limits: Any) -> bytes:
+        return enable_ltv(data, extra=self.material, encryption=encryption)
+
+
+@dataclass(frozen=True)
+class PendingDocumentTimestamp:
+    """A document timestamp (``ETSI.RFC3161``) to append when the document is saved."""
+
+    timestamp_url: str | None
+    timestamp_authority: tuple[Any, Any] | None
+    timeout: float
+
+    def apply(self, data: bytes, *, encryption: Any, limits: Any) -> bytes:
+        return add_document_timestamp(
+            data,
+            tsa=self.timestamp_authority,
+            timestamp_url=self.timestamp_url,
+            timeout=self.timeout,
+            encryption=encryption,
+        )
+
+
+PendingOperation = PendingSignature | PendingLtv | PendingDocumentTimestamp

aspose_pdf/_version.py

@@ -0,0 +1,17 @@
+"""Version helpers for the ``aspose_pdf`` package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+__release_version__ = "0.1.0"
+
+
+def _detect_installed_version() -> str:
+    try:
+        return version("aspose-pdf-foss-for-python")
+    except PackageNotFoundError:
+        return __release_version__
+
+
+__version__ = _detect_installed_version()

aspose_pdf/actions.py

@@ -0,0 +1,273 @@
+"""What a document, a page or a field does when something happens to it.
+
+ISO 32000-1 12.6.3: an *additional-actions* dictionary (``/AA``) maps a trigger
+to an action. The triggers are different for each kind of owner, and naming one
+that the owner has no trigger for is a mistake nothing would ever report -- a
+viewer simply never fires it -- so each collection knows its own::
+
+    field.actions["validate"] = JavaScriptAction("if (event.value < 0) ...")
+    page.actions["open"] = JavaScriptAction("app.alert('page one')")
+    document.actions["will_print"] = JavaScriptAction("...")
+
+The actions themselves are the ones in :mod:`aspose_pdf.interactive`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from aspose_pdf.exceptions import PdfValidationException
+
+__all__ = [
+    "DOCUMENT_TRIGGERS",
+    "FIELD_TRIGGERS",
+    "PAGE_TRIGGERS",
+    "ActionCollection",
+    "JavaScriptCollection",
+]
+
+#: A form field's triggers (Table 196), and the widget's own (Table 195).
+#: ``/K``, ``/F``, ``/V`` and ``/C`` belong on the field, the rest on its widget,
+#: which is where a viewer looks for each -- the collection writes whichever
+#: dictionary the trigger belongs to.
+FIELD_TRIGGERS: dict[str, str] = {
+    "keystroke": "K",
+    "format": "F",
+    "validate": "V",
+    "calculate": "C",
+    "enter": "E",
+    "exit": "X",
+    "mouse_down": "D",
+    "mouse_up": "U",
+    "focus": "Fo",
+    "blur": "Bl",
+    "page_open": "PO",
+    "page_close": "PC",
+    "page_visible": "PV",
+    "page_invisible": "PI",
+}
+
+#: The triggers that belong on the *field* rather than on its widget.
+FIELD_ONLY_TRIGGERS = frozenset({"keystroke", "format", "validate", "calculate"})
+
+#: A page's triggers (Table 194).
+PAGE_TRIGGERS: dict[str, str] = {"open": "O", "close": "C"}
+
+#: The document's triggers (Table 197), on the catalog.
+DOCUMENT_TRIGGERS: dict[str, str] = {
+    "will_close": "WC",
+    "will_save": "WS",
+    "did_save": "DS",
+    "will_print": "WP",
+    "did_print": "DP",
+}
+
+
+class ActionCollection:
+    """A mapping of trigger name to :class:`~aspose_pdf.interactive.Action`.
+
+    Reads go to the document each time, so the collection is never a stale copy.
+    Assigning ``None``, or deleting a key, removes the trigger; an action this API
+    has no class for is read as ``None`` and left in the file as it is, the way
+    every other typed view in the package treats one.
+    """
+
+    __slots__ = ("_read", "_triggers", "_what", "_write")
+
+    def __init__(
+        self,
+        triggers: dict[str, str],
+        read: Any,
+        write: Any,
+        what: str,
+    ) -> None:
+        self._triggers = triggers
+        self._read = read
+        self._write = write
+        self._what = what
+
+    def _key(self, trigger: str) -> str:
+        """The ``/AA`` entry *trigger* names, or a refusal listing the ones there are."""
+        if not isinstance(trigger, str):
+            raise PdfValidationException(f"A {self._what} trigger is named by a string.")
+        key = trigger.strip().lower().replace("-", "_").replace(" ", "_")
+        if key in self._triggers:
+            return self._triggers[key]
+        # The PDF key itself is accepted, so code that knows the standard can say
+        # what it means in the standard's own terms.
+        if trigger in self._triggers.values():
+            return trigger
+        raise PdfValidationException(
+            f"{trigger!r} is not a {self._what} trigger; use one of: "
+            + ", ".join(sorted(self._triggers))
+        )
+
+    def _name_of(self, key: str) -> str:
+        """The friendly name of a ``/AA`` entry, or the entry itself."""
+        for name, entry in self._triggers.items():
+            if entry == key:
+                return name
+        return key
+
+    def __len__(self) -> int:
+        return len(self._read())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(sorted(self._name_of(key) for key in self._read()))
+
+    def __contains__(self, trigger: object) -> bool:
+        if not isinstance(trigger, str):
+            return False
+        try:
+            return self._key(trigger) in self._read()
+        except PdfValidationException:
+            return False
+
+    def __getitem__(self, trigger: str) -> Any:
+        key = self._key(trigger)
+        actions = self._read()
+        if key not in actions:
+            raise KeyError(trigger)
+        return actions[key]
+
+    def get(self, trigger: str, default: Any = None) -> Any:
+        """The action *trigger* fires, or *default* when it has none.
+
+        A trigger that *is* set but whose action this API has no class for reads
+        as ``None`` rather than as *default*: the action is there, and it is only
+        this typed view that cannot describe it.
+        """
+        try:
+            return self[trigger]
+        except KeyError:
+            return default
+
+    def __setitem__(self, trigger: str, action: Any) -> None:
+        self._write(self._key(trigger), action)
+
+    def __delitem__(self, trigger: str) -> None:
+        key = self._key(trigger)
+        if key not in self._read():
+            raise KeyError(trigger)
+        self._write(key, None)
+
+    def set(self, trigger: str, action: Any) -> None:
+        """Set *trigger* to fire *action*; ``None`` removes it."""
+        self[trigger] = action
+
+    def remove(self, trigger: str) -> bool:
+        """Remove *trigger*; ``True`` when it had an action."""
+        key = self._key(trigger)
+        if key not in self._read():
+            return False
+        self._write(key, None)
+        return True
+
+    def clear(self) -> None:
+        """Remove every trigger."""
+        for key in list(self._read()):
+            self._write(key, None)
+
+    def keys(self) -> list[str]:
+        return list(self)
+
+    def values(self) -> list[Any]:
+        return [self[name] for name in self]
+
+    def items(self) -> list[tuple[str, Any]]:
+        return [(name, self[name]) for name in self]
+
+    @property
+    def triggers(self) -> tuple[str, ...]:
+        """Every trigger this owner has, whether it is set or not."""
+        return tuple(sorted(self._triggers))
+
+    def __repr__(self) -> str:
+        return f"ActionCollection({self._what}, {self.keys()!r})"
+
+
+class JavaScriptCollection:
+    """The document's own scripts, as a mapping of name to source.
+
+    ISO 32000-1 12.6.4.17: these live in the catalog's ``/Names /JavaScript`` name
+    tree, and a viewer runs them when the document opens -- in **key order**, so
+    the names are what decides which runs first. This is where the functions a
+    field's ``/AA`` script calls are defined.
+
+    Reads go to the document each time. A name is encoded with latin-1, the one
+    codec that round-trips a name tree's byte keys unchanged.
+    """
+
+    __slots__ = ("_document",)
+
+    def __init__(self, document: Any) -> None:
+        self._document = document
+
+    def _engine(self) -> Any:
+        self._document._ensure_not_disposed()
+        engine = self._document._engine_pdf
+        if engine is None:
+            from aspose_pdf.exceptions import AsposePdfException
+
+            raise AsposePdfException("No document loaded")
+        return engine
+
+    def _scripts(self) -> dict[str, str]:
+        return self._engine().document_javascript()
+
+    def __len__(self) -> int:
+        return len(self._scripts())
+
+    def __iter__(self) -> Iterator[str]:
+        """The names, in the order a viewer runs them: key order."""
+        return iter(sorted(self._scripts()))
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self._scripts()
+
+    def __getitem__(self, name: str) -> str:
+        scripts = self._scripts()
+        if name not in scripts:
+            raise KeyError(name)
+        return scripts[name]
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """The script *name* holds, or *default*."""
+        return self._scripts().get(name, default)
+
+    def __setitem__(self, name: str, script: str) -> None:
+        self.add(name, script)
+
+    def add(self, name: str, script: str) -> None:
+        """Define (or replace) the script *name*."""
+        if not isinstance(script, str):
+            raise PdfValidationException("A document script is source text.")
+        self._engine().set_document_javascript(name, script)
+
+    def __delitem__(self, name: str) -> None:
+        if not self.remove(name):
+            raise KeyError(name)
+
+    def remove(self, name: str) -> bool:
+        """Remove the script *name*; ``True`` when there was one."""
+        if name not in self._scripts():
+            return False
+        self._engine().set_document_javascript(name, None)
+        return True
+
+    def clear(self) -> None:
+        """Remove every document-level script."""
+        self._engine().clear_document_javascript()
+
+    def keys(self) -> list[str]:
+        return list(self)
+
+    def values(self) -> list[str]:
+        return [self[name] for name in self]
+
+    def items(self) -> list[tuple[str, str]]:
+        return [(name, self[name]) for name in self]
+
+    def __repr__(self) -> str:
+        return f"JavaScriptCollection({self.keys()!r})"