Document XAdES module, clean up docs and namespace

Author: kislyuk

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
       max-parallel: 8
       matrix:
         os: [ubuntu-20.04, ubuntu-22.04, macos-10.15]
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}

README.rst

@@ -27,7 +27,7 @@ Installation
 ------------
 ::
 
-    pip3 install signxml
+    pip install signxml
 
 Note: SignXML depends on `lxml <https://github.com/lxml/lxml>`_ and `cryptography
 <https://github.com/pyca/cryptography>`_, which in turn depend on `OpenSSL <https://www.openssl.org/>`_, `LibXML

docs/index.rst

@@ -7,6 +7,15 @@ API documentation
    :members:
    :imported-members:
    :undoc-members:
+   :exclude-members: XMLSignatureProcessor
+
+XAdES API documentation
+=======================
+
+.. automodule:: signxml.xades
+   :members:
+   :imported-members:
+   :undoc-members:
 
 Change log
 ==========

pyproject.toml

@@ -3,3 +3,4 @@ line-length = 120
 [tool.isort]
 profile = "black"
 line_length = 120
+skip = ["signxml/__init__.py", "signxml/xades/__init__.py"]

setup.cfg

@@ -3,6 +3,9 @@ universal=1
 [flake8]
 max-line-length=120
 extend-ignore=E203
+per-file-ignores=
+    signxml/__init__.py:F401
+    signxml/xades/__init__.py:F401
 [coverage:run]
 omit =
     signxml/__pyinstaller/*

signxml/__init__.py

@@ -1,9 +1,13 @@
-# isort: skip_file
-from .signer import XMLSigner, XMLSignatureReference  # noqa:F401
-from .verifier import XMLVerifier, VerifyResult  # noqa:F401
-from .algorithms import DigestAlgorithm, SignatureMethod, CanonicalizationMethod, SignatureType  # noqa:F401
-from .exceptions import InvalidCertificate, InvalidDigest, InvalidInput, InvalidSignature  # noqa:F401
-from .processor import XMLSignatureProcessor  # noqa:F401
-from .util import SigningSettings, namespaces  # noqa:F401
+"""
+Use :class:`signxml.XMLSigner` and :class:`signxml.XMLVerifier` to sign and verify XML Signatures, respectively.
+See `SignXML documentation <#synopsis>`_ for examples.
+"""
 
-methods = SignatureType
+from .signer import XMLSigner, XMLSignatureReference
+from .verifier import XMLVerifier, VerifyResult
+from .algorithms import DigestAlgorithm, SignatureMethod, CanonicalizationMethod, SignatureConstructionMethod
+from .exceptions import InvalidCertificate, InvalidDigest, InvalidInput, InvalidSignature
+from .processor import XMLSignatureProcessor
+from .util import namespaces
+
+methods = SignatureConstructionMethod

signxml/algorithms.py

@@ -1,19 +1,22 @@
 from enum import Enum, auto
+from typing import Callable
 
 from cryptography.hazmat.primitives import hashes
 
 from .exceptions import InvalidInput
 
 
-class SignatureType(Enum):
+class SignatureConstructionMethod(Enum):
     """
-    An enumeration of structural signature types supported by SignXML.
+    An enumeration of signature construction methods supported by SignXML, used to specify the method when signing.
+    See the list of signature types under `XML Signature Syntax and Processing Version 2.0, Definitions
+    <http://www.w3.org/TR/xmldsig-core2/#sec-Definitions>`_.
     """
 
     enveloped = auto()
     """
     The signature is over the XML content that contains the signature as an element. The content provides the root
-    XML document element.
+    XML document element. This is the most common XML signature type in modern applications.
     """
 
     enveloping = auto()
@@ -63,14 +66,18 @@ class DigestAlgorithm(FragmentLookupMixin, InvalidInputErrorMixin, Enum):
     SHA3_512 = "http://www.w3.org/2007/05/xmldsig-more#sha3-512"
 
     @property
-    def implementation(self):
+    def implementation(self) -> Callable:
+        """
+        The cryptography callable that implements the specified algorithm.
+        """
         return digest_algorithm_implementations[self]
 
 
 # TODO: check if padding errors are fixed by using padding=MGF1
 class SignatureMethod(FragmentLookupMixin, InvalidInputErrorMixin, Enum):
     """
-    An enumeration of signature methods supported by SignXML. See RFC 9231 for details.
+    An enumeration of signature methods (also referred to as signature algorithms) supported by SignXML. See RFC 9231
+    for details.
     """
 
     DSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#dsa-sha1"
@@ -101,7 +108,8 @@ class SignatureMethod(FragmentLookupMixin, InvalidInputErrorMixin, Enum):
 
 class CanonicalizationMethod(InvalidInputErrorMixin, Enum):
     """
-    An enumeration of XML canonicalization methods supported by SignXML. See RFC 9231 for details.
+    An enumeration of XML canonicalization methods (also referred to as canonicalization algorithms) supported by
+    SignXML. See RFC 9231 for details.
     """
 
     CANONICAL_XML_1_0 = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"

signxml/processor.py

@@ -33,26 +33,26 @@ def parser(self):
             return self._default_parser
         return self._parser
 
-    def fromstring(self, xml_string, **kwargs):
+    def _fromstring(self, xml_string, **kwargs):
         xml_node = etree.fromstring(xml_string, parser=self.parser, **kwargs)
         for entity in xml_node.iter(etree.Entity):
             raise InvalidInput("Entities are not supported in XML input")
         return xml_node
 
-    def tostring(self, xml_node, **kwargs):
+    def _tostring(self, xml_node, **kwargs):
         return etree.tostring(xml_node, **kwargs)
 
     def get_root(self, data):
         if isinstance(data, (str, bytes)):
-            return self.fromstring(data)
+            return self._fromstring(data)
         elif isinstance(data, stdlibElementTree.Element):
             # TODO: add debug level logging statement re: performance impact here
-            return self.fromstring(stdlibElementTree.tostring(data, encoding="utf-8"))
+            return self._fromstring(stdlibElementTree.tostring(data, encoding="utf-8"))
         else:
             # HACK: deep copy won't keep root's namespaces resulting in an invalid digest
             # We use a copy so we can modify the tree
             # TODO: turn this off for xmlenc
-            return self.fromstring(etree.tostring(data))
+            return self._fromstring(etree.tostring(data))
 
 
 class XMLSignatureProcessor(XMLProcessor):

signxml/signer.py

@@ -12,8 +12,8 @@
 from .algorithms import (
     CanonicalizationMethod,
     DigestAlgorithm,
+    SignatureConstructionMethod,
     SignatureMethod,
-    SignatureType,
     digest_algorithm_implementations,
 )
 from .exceptions import InvalidInput
@@ -59,9 +59,8 @@ class XMLSigner(XMLSignatureProcessor):
     pieces of data.
 
     :param method:
-        ``signxml.methods.enveloped``, ``signxml.methods.enveloping``, or ``signxml.methods.detached``. See the list
-        of signature types under `XML Signature Syntax and Processing Version 2.0, Definitions
-        <http://www.w3.org/TR/xmldsig-core2/#sec-Definitions>`_.
+        ``signxml.methods.enveloped``, ``signxml.methods.enveloping``, or ``signxml.methods.detached``. See
+        :class:`SignatureConstructionMethod` for details.
     :param signature_algorithm:
         Algorithm that will be used to generate the signature, composed of the signature algorithm and the digest
         algorithm, separated by a hyphen. All algorithm IDs listed under the `Algorithm Identifiers and
@@ -72,16 +71,32 @@ class XMLSigner(XMLSignatureProcessor):
         <http://www.w3.org/TR/xmldsig-core1/#sec-AlgID>`_ section of the XML Signature 1.1 standard are supported.
     """
 
+    signature_annotators: List
+    """
+    A list of callables that will be called at signature creation time to annotate the content to be signed before
+    signing. You can use this to register a custom signature decorator as follows:
+
+    .. code-block:: python
+
+        def my_annotator(sig_root, signing_settings):
+            ...
+            sig_root.append(my_custom_node)
+
+        signer = XMLSigner()
+        signer.signature_annotators.append(my_annotator)
+        signed = signer.sign(data, ...)
+    """
+
     def __init__(
         self,
-        method: SignatureType = SignatureType.enveloped,
+        method: SignatureConstructionMethod = SignatureConstructionMethod.enveloped,
         signature_algorithm: Union[SignatureMethod, str] = SignatureMethod.RSA_SHA256,
         digest_algorithm: Union[DigestAlgorithm, str] = DigestAlgorithm.SHA256,
         c14n_algorithm=CanonicalizationMethod.CANONICAL_XML_1_1,
     ):
-        if method is None or method not in SignatureType:
-            raise InvalidInput(f"Unknown signature method {method}")
-        self.signature_type = method
+        if method is None or method not in SignatureConstructionMethod:
+            raise InvalidInput(f"Unknown signature construction method {method}")
+        self.construction_method = method
         if isinstance(signature_algorithm, str) and "#" not in signature_algorithm:
             self.sign_alg = SignatureMethod.from_fragment(signature_algorithm)
         else:
@@ -108,7 +123,7 @@ def sign(
         always_add_key_value: bool = False,
         inclusive_ns_prefixes: Optional[List[str]] = None,
         signature_properties=None,
-    ):
+    ) -> _Element:
         """
         Sign the data and return the root element of the resulting XML tree.
 
@@ -168,7 +183,7 @@ def sign(
 
         To specify the location of an enveloped signature within **data**, insert a
         ``<ds:Signature Id="placeholder"></ds:Signature>`` element in **data** (where
-        "ds" is the "http://www.w3.org/2000/09/xmldsig#" namespace). This element will
+        "ds" is the ``http://www.w3.org/2000/09/xmldsig#`` namespace). This element will
         be replaced by the generated signature, and excised when generating the digest.
         """
         if id_attribute is not None:
@@ -199,7 +214,7 @@ def sign(
 
         sig_root, doc_root, c14n_inputs, references = self._unpack(data, input_references)
 
-        if self.signature_type == SignatureType.detached and signature_properties is not None:
+        if self.construction_method == SignatureConstructionMethod.detached and signature_properties is not None:
             references.append(XMLSignatureReference(URI="#prop"))
             if signature_properties is not None and not isinstance(signature_properties, list):
                 signature_properties = [signature_properties]
@@ -246,14 +261,14 @@ def sign(
         else:
             raise NotImplementedError()
 
-        if self.signature_type == SignatureType.enveloping:
+        if self.construction_method == SignatureConstructionMethod.enveloping:
             for c14n_input in c14n_inputs:
                 doc_root.append(c14n_input)
 
-        if self.signature_type == SignatureType.detached and signature_properties is not None:
+        if self.construction_method == SignatureConstructionMethod.detached and signature_properties is not None:
             sig_root.append(signature_properties_el)
 
-        return doc_root if self.signature_type == SignatureType.enveloped else sig_root
+        return doc_root if self.construction_method == SignatureConstructionMethod.enveloped else sig_root
 
     def _preprocess_reference_uri(self, reference_uris):
         if reference_uris is None:
@@ -298,7 +313,7 @@ def _get_c14n_inputs_from_references(self, doc_root, references: List[XMLSignatu
 
     def _unpack(self, data, references: List[XMLSignatureReference]):
         sig_root = Element(ds_tag("Signature"), nsmap=self.namespaces)
-        if self.signature_type == SignatureType.enveloped:
+        if self.construction_method == SignatureConstructionMethod.enveloped:
             if isinstance(data, (str, bytes)):
                 raise InvalidInput("When using enveloped signature, **data** must be an XML element")
             doc_root = self.get_root(data)
@@ -328,7 +343,7 @@ def _unpack(self, data, references: List[XMLSignatureReference]):
                     payload_id = c14n_input.get("Id", c14n_input.get("ID"))
                     uri = "#{}".format(payload_id) if payload_id is not None else ""
                     references.append(XMLSignatureReference(URI=uri))
-        elif self.signature_type == SignatureType.detached:
+        elif self.construction_method == SignatureConstructionMethod.detached:
             doc_root = self.get_root(data)
             if references is None:
                 uri = "#{}".format(data.get("Id", data.get("ID", "object")))
@@ -338,7 +353,7 @@ def _unpack(self, data, references: List[XMLSignatureReference]):
                 c14n_inputs, references = self._get_c14n_inputs_from_references(doc_root, references)
             except InvalidInput:  # Dummy reference URI
                 c14n_inputs = [self.get_root(data)]
-        elif self.signature_type == SignatureType.enveloping:
+        elif self.construction_method == SignatureConstructionMethod.enveloping:
             doc_root = sig_root
             c14n_inputs = [Element(ds_tag("Object"), nsmap=self.namespaces, Id="object")]
             if isinstance(data, (str, bytes)):
@@ -362,7 +377,7 @@ def _build_sig(self, sig_root, references, c14n_inputs, inclusive_ns_prefixes):
                 reference.inclusive_ns_prefixes = inclusive_ns_prefixes
             reference_node = SubElement(signed_info, ds_tag("Reference"), URI=reference.URI)
             transforms = SubElement(reference_node, ds_tag("Transforms"))
-            if self.signature_type == SignatureType.enveloped:
+            if self.construction_method == SignatureConstructionMethod.enveloped:
                 SubElement(transforms, ds_tag("Transform"), Algorithm=namespaces.ds + "enveloped-signature")
                 SubElement(transforms, ds_tag("Transform"), Algorithm=reference.c14n_method.value)
             else:

signxml/verifier.py

@@ -48,8 +48,7 @@ class VerifyResult:
 
 class XMLVerifier(XMLSignatureProcessor):
     """
-    Create a new XML Signature Verifier object, which can be used to hold configuration information and verify multiple
-    pieces of data.
+    Create a new XML Signature Verifier object, which can be used to verify multiple pieces of data.
     """
 
     def _get_signature(self, root):
@@ -184,7 +183,7 @@ def verify(
         ignore_ambiguous_key_info: bool = False,
     ) -> Union[VerifyResult, List[VerifyResult]]:
         """
-        Verify the XML signature supplied in the data and return a list of **VerifyResult** data structures
+        Verify the XML signature supplied in the data and return a list of :class:`VerifyResult` data structures
         representing the data signed by the signature, or raise an exception if the signature is not valid. By default,
         this requires the signature to be generated using a valid X.509 certificate. To enable other means of signature
         validation, set the **require_x509** argument to `False`.
@@ -277,7 +276,7 @@ def verify(
         signature_ref = self._get_signature(root)
 
         # HACK: deep copy won't keep root's namespaces
-        signature = self.fromstring(self.tostring(signature_ref))
+        signature = self._fromstring(self._tostring(signature_ref))
 
         if validate_schema:
             self.validate_schema(signature)
@@ -346,7 +345,7 @@ def verify(
             # If both X509Data and KeyValue are present, match one against the other and raise an error on mismatch
             if key_value is not None:
                 if (
-                    self.check_key_value_matches_cert_public_key(key_value, signing_cert.get_pubkey(), signature_alg)
+                    self._check_key_value_matches_cert_public_key(key_value, signing_cert.get_pubkey(), signature_alg)
                     is False
                 ):
                     if ignore_ambiguous_key_info is False:
@@ -360,7 +359,7 @@ def verify(
             # mismatch
             if der_encoded_key_value is not None:
                 if (
-                    self.check_der_key_value_matches_cert_public_key(
+                    self._check_der_key_value_matches_cert_public_key(
                         der_encoded_key_value, signing_cert.get_pubkey(), signature_alg
                     )
                     is False
@@ -397,7 +396,7 @@ def verify(
 
         verify_results: List[VerifyResult] = []
         for reference in self._findall(signed_info, "Reference"):
-            copied_root = self.fromstring(self.tostring(root))
+            copied_root = self._fromstring(self._tostring(root))
             copied_signature_ref = self._get_signature(copied_root)
             transforms = self._find(reference, "Transforms", require=False)
             digest_alg = self._find(reference, "DigestMethod").get("Algorithm")
@@ -409,7 +408,7 @@ def verify(
 
             # We return the signed XML (and only that) to ensure no access to unsigned data happens
             try:
-                payload_c14n_xml = self.fromstring(payload_c14n)
+                payload_c14n_xml = self._fromstring(payload_c14n)
             except etree.XMLSyntaxError:
                 payload_c14n_xml = None
             verify_results.append(VerifyResult(payload_c14n, payload_c14n_xml, signature))
@@ -430,7 +429,7 @@ def validate_schema(self, signature):
                 last_exception = e
         raise last_exception  # type: ignore
 
-    def check_key_value_matches_cert_public_key(self, key_value, public_key, signature_alg: SignatureMethod):
+    def _check_key_value_matches_cert_public_key(self, key_value, public_key, signature_alg: SignatureMethod):
         if signature_alg.name.startswith("ECDSA_") and isinstance(
             public_key.to_cryptography_key(), ec.EllipticCurvePublicKey
         ):
@@ -472,7 +471,7 @@ def check_key_value_matches_cert_public_key(self, key_value, public_key, signatu
 
         raise NotImplementedError()
 
-    def check_der_key_value_matches_cert_public_key(self, der_encoded_key_value, public_key, signature_alg):
+    def _check_der_key_value_matches_cert_public_key(self, der_encoded_key_value, public_key, signature_alg):
         # TODO: Add a test case for this functionality
         der_public_key = load_der_public_key(b64decode(der_encoded_key_value.text))