SignXML

https://xml-security.github.io/signxml/
Admin
SignXML is a Python library for creating and verifying XML signatures and XAdES (XML Advanced...
Tokens:27,235
Snippets:161
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install SignXML

Source: https://xml-security.github.io/signxml/index.html

Use pip to install the library.

```bash
pip install signxml
```

--------------------------------

### Verifying SHA1 Signatures

Source: https://xml-security.github.io/signxml/_modules/signxml/algorithms.html

Example showing how to configure the XMLVerifier to allow SHA1-based signatures, which are disabled by default for security reasons.

```python
XMLVerifier().verify(
    expect_config=SignatureConfiguration(
        signature_methods=...,
        digest_algorithms=...
    )
)
```

--------------------------------

### Get Certificate Verification Time

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Retrieves the current verification time, defaulting to UTC if not specified in the configuration.

```python
    def _get_cert_verification_time(self):
        verification_time = self.config.verification_time or datetime.now(tz=timezone.utc)
        if verification_time.tzinfo is None:
            return verification_time.replace(tzinfo=timezone.utc)
        return verification_time.astimezone(timezone.utc)
```

--------------------------------

### Initialize Certificate Chain Verifier

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Creates an X509CertChainVerifier instance using the provided CA file and policies.

```python
    def get_cert_chain_verifier(self, ca_pem_file, ee_policy, ca_policy):
        return X509CertChainVerifier(
            ca_pem_file=ca_pem_file,
            verification_time=self._get_cert_verification_time(),
            ee_policy=ee_policy,
            ca_policy=ca_policy,
        )
```

--------------------------------

### Initialize SignXML Verifier

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Internal initialization logic for the verifier, handling HMAC key configuration, deprecated parameters, and X.509 certificate validation.

```python
self.hmac_key = hmac_key
if hmac_key is not None:
    if expect_config.signature_methods == SignatureConfiguration().signature_methods:  # default value
        expect_config = replace(
            expect_config,
            signature_methods=frozenset(sm for sm in SignatureMethod if sm.name.startswith("HMAC")),
        )
    elif any(not sm.name.startswith("HMAC") for sm in expect_config.signature_methods):
        raise InvalidInput("When hmac_key is set, all expected signature methods must use HMAC")

self.config = expect_config
if deprecated_kwargs:
    self.config = replace(expect_config, **deprecated_kwargs)
self._parser = parser

if x509_cert or cert_resolver:
    self.config = replace(self.config, require_x509=True)

if x509_cert and str(type(x509_cert)) == "<class 'OpenSSL.crypto.X509'>":
    warn(
        "SignXML received a PyOpenSSL object as x509_cert input. Please pass a Cryptography.X509 object instead.",
        DeprecationWarning,
    )
    x509_cert = cast(Any, x509_cert).to_cryptography()

self.x509_cert = x509_cert

if id_attribute is not None:
    self.id_attributes = (id_attribute,)

root = self.get_root(data)
signature_ref = self._get_signature(root)

# We could do a deep copy here, but it wouldn't preserve root level namespaces
signature = self._fromstring(self._tostring(signature_ref))
```

--------------------------------

### Verify XML signature with basic configuration

Source: https://xml-security.github.io/signxml/index.html

Use this pattern to verify an XML signature while enforcing a specific location for the signature element.

```python
from signxml import XMLVerifier, SignatureConfiguration
config = SignatureConfiguration(location="./")
XMLVerifier(...).verify(..., expect_config=config)
```

--------------------------------

### XAdES Class Initialization

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Initializes the XAdES signer, configuring signature properties and annotators. HMAC signatures are explicitly disallowed.

```python
    def __init__(
        self,
        signature_policy: Optional[XAdESSignaturePolicy] = None,
        claimed_roles: Optional[List] = None,
        data_object_format: Optional[XAdESDataObjectFormat] = None,
        **xml_signer_args,
    ) -> None:
        super().__init__(**xml_signer_args)
        if self.sign_alg.name.startswith("HMAC_"):
            raise Exception("HMAC signatures are not supported by XAdES")
        self.signature_annotators.append(self._build_xades_ds_object)
        self._tokens_used: Dict[str, bool] = {}
        self.signed_signature_properties_annotators = [
            self.add_signing_time,
            self.add_signing_certificate,
            self.add_signature_policy_identifier,
            self.add_signature_production_place,
            self.add_signer_role,
        ]
        self.signed_data_object_properties_annotators = [
            self.add_data_object_format,
        ]
        self.signature_policy = signature_policy
        self.claimed_roles = claimed_roles
        if data_object_format is None:
            data_object_format = XAdESDataObjectFormat()
        self.data_object_format = data_object_format
        self.namespaces.update(xades=namespaces.xades)
```

--------------------------------

### Build Signature Information

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Constructs the SignedInfo element and processes references to generate digest values.

```python
    def _build_sig(
        self, sig_root, references, c14n_inputs, inclusive_ns_prefixes, exclude_c14n_transform_element=False
    ):
        signed_info = SubElement(sig_root, self._ds_tag("SignedInfo"), nsmap=self.namespaces)
        sig_c14n_method = SubElement(signed_info, self._ds_tag("CanonicalizationMethod"), Algorithm=self.c14n_alg.value)
        if inclusive_ns_prefixes:
            SubElement(sig_c14n_method, ec_tag("InclusiveNamespaces"), PrefixList=" ".join(inclusive_ns_prefixes))

        SubElement(signed_info, self._ds_tag("SignatureMethod"), Algorithm=self.sign_alg.value)
        for i, reference in enumerate(references):
            if reference.c14n_method is None:
                reference = replace(reference, c14n_method=self.c14n_alg)
            if reference.inclusive_ns_prefixes is None:
                reference = replace(reference, inclusive_ns_prefixes=inclusive_ns_prefixes)
            reference_node = SubElement(signed_info, self._ds_tag("Reference"), URI=reference.URI)
            transforms = SubElement(reference_node, self._ds_tag("Transforms"))
            self._build_transforms_for_reference(
                transforms_node=transforms,
                reference=reference,
                exclude_c14n_transform_element=exclude_c14n_transform_element,
            )
            SubElement(reference_node, self._ds_tag("DigestMethod"), Algorithm=self.digest_alg.value)
            digest_value = SubElement(reference_node, self._ds_tag("DigestValue"))
            payload_c14n = self._c14n(
                c14n_inputs[i], algorithm=reference.c14n_method, inclusive_ns_prefixes=reference.inclusive_ns_prefixes
            )
            digest = self._get_digest(payload_c14n, algorithm=self.digest_alg)
            digest_value.text = b64encode(digest).decode()
        signature_value = SubElement(sig_root, self._ds_tag("SignatureValue"))
        return signed_info, signature_value
```

--------------------------------

### Verify SAML assertions using metadata

Source: https://xml-security.github.io/signxml/index.html

Extracts an X.509 certificate from metadata and verifies the assertion body.

```python
from lxml import etree
from base64 import b64decode
from signxml import XMLVerifier

with open("metadata.xml", "rb") as fh:
    cert = etree.parse(fh).find("//ds:X509Certificate").text

assertion_data = XMLVerifier().verify(b64decode(assertion_body), x509_cert=cert).signed_xml
```

--------------------------------

### Build XAdES Object

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Constructs the XAdES QualifyingProperties structure and appends it to the signature.

```python
    def _build_xades_ds_object(self, sig_root, signing_settings: SigningSettings):
        ds_object = SubElement(sig_root, ds_tag("Object"), nsmap=self.namespaces)
        sig_root.append(ds_object)
        if "Id" not in sig_root.keys():
            sig_root.set("Id", f"SignXMLSignature{self._get_token()}")
        key_info = self._find(sig_root, "KeyInfo")
        if "Id" not in key_info.keys():
            key_info.set("Id", f"SignXMLCertificate{self._get_token()}")

        qualifying_properties = SubElement(
            ds_object, xades_tag("QualifyingProperties"), nsmap=self.namespaces, Target=f"#{sig_root.get('Id')}"
        )
        signed_properties = SubElement(
            qualifying_properties,
            xades_tag("SignedProperties"),
            nsmap=self.namespaces,
            Id=f"{sig_root.get('Id')}-SignedProperties{self._get_token()}",
        )
        signed_signature_properties = SubElement(
            signed_properties, xades_tag("SignedSignatureProperties"), nsmap=self.namespaces
        )
        for ssp_annotator in self.signed_signature_properties_annotators:
            ssp_annotator(signed_signature_properties, sig_root=sig_root, signing_settings=signing_settings)
        signed_data_object_properties = SubElement(
            signed_properties, xades_tag("SignedDataObjectProperties"), nsmap=self.namespaces
        )
        for dop_annotator in self.signed_data_object_properties_annotators:
            dop_annotator(signed_data_object_properties, sig_root=sig_root, signing_settings=signing_settings)
        self._add_reference_to_signed_info(
            sig_root, signed_properties, Type="http://uri.etsi.org/01903#SignedProperties"
        )
        self._add_reference_to_signed_info(sig_root, key_info)
```

--------------------------------

### Sign and Verify XML

Source: https://xml-security.github.io/signxml/index.html

Basic usage of XMLSigner and XMLVerifier to sign an XML element and verify the resulting signature.

```python
from lxml import etree
from signxml import XMLSigner, XMLVerifier

data_to_sign = "<Test/>"
cert = open("cert.pem").read()
key = open("privkey.pem").read()
root = etree.fromstring(data_to_sign)
signed_root = XMLSigner().sign(root, key=key, cert=cert)
verified_data = XMLVerifier().verify(signed_root).signed_xml
```

--------------------------------

### XML Signing Method

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Signs data and returns the root element of the resulting XML tree. Supports various keys, certificates, and custom reference configurations.

```python
def sign(
        self,
        data,
        *,
        key: Optional[Union[str, bytes, rsa.RSAPrivateKey, dsa.DSAPrivateKey, ec.EllipticCurvePrivateKey]] = None,
        passphrase: Optional[bytes] = None,
        cert: Optional[Union[str, List[str], List[x509.Certificate]]] = None,
        reference_uri: Optional[Union[str, List[str], List[SignatureReference]]] = None,
        key_name: Optional[str] = None,
        key_info: Optional[_Element] = None,
        id_attribute: Optional[str] = None,
        always_add_key_value: bool = False,
        inclusive_ns_prefixes: Optional[List[str]] = None,
        signature_properties: Optional[Union[_Element, List[_Element]]] = None,
        exclude_c14n_transform_element: bool = False,
    ) -> _Element:
```

--------------------------------

### Signing with XAdES

Source: https://xml-security.github.io/signxml/index.html

Implement XAdES signatures by configuring signature policies and data object formats using XAdESSigner.

```python
from signxml import DigestAlgorithm
from signxml.xades import (XAdESSigner, XAdESVerifier, XAdESVerifyResult,
                           XAdESSignaturePolicy, XAdESDataObjectFormat)
signature_policy = XAdESSignaturePolicy(
    Identifier="MyPolicyIdentifier",
    Description="Hello XAdES",
    DigestMethod=DigestAlgorithm.SHA256,
    DigestValue="Ohixl6upD6av8N7pEvDABhEL6hM=",
)
data_object_format = XAdESDataObjectFormat(
    Description="My XAdES signature",
    MimeType="text/xml",
)
signer = XAdESSigner(
    signature_policy=signature_policy,
    claimed_roles=["signer"],
    data_object_format=data_object_format,
    c14n_algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
)
signed_doc = signer.sign(doc, key=private_key, cert=certificate)
```

--------------------------------

### Verify XML Signature and References

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Handles the core verification logic for public key and HMAC signatures, followed by reference validation.

```python
            try:
                verified_signed_info_c14n, key_used = self._verify_signature_with_pubkey(
                    signed_info_c14n=signed_info_c14n,
                    raw_signature=raw_signature,
                    signing_certificate=signing_cert,
                    signature_alg=signature_alg,
                )
            except cryptography.exceptions.InvalidSignature as e:
                raise InvalidSignature(f"Signature verification failed: {e}")

            self._match_key_values(
                key_value=key_value,
                der_encoded_key_value=der_encoded_key_value,
                signing_cert=signing_cert,
                signature_alg=signature_alg,
            )
        elif signature_alg.name.startswith("HMAC_"):
            if self.hmac_key is None:
                raise InvalidInput('Parameter "hmac_key" is required when verifying a HMAC signature')

            signer = HMAC(key=self.hmac_key, algorithm=digest_algorithm_implementations[signature_alg]())
            signer.update(signed_info_c14n)
            try:
                signer.verify(raw_signature)
                verified_signed_info_c14n = signed_info_c14n
            except cryptography.exceptions.InvalidSignature:
                raise InvalidSignature("Signature mismatch (HMAC)")
            key_used = self.hmac_key
        else:
            if key_value is None and der_encoded_key_value is None:
                raise InvalidInput("Expected to find either KeyValue or X509Data XML element in KeyInfo")

            verified_signed_info_c14n, key_used = self._verify_signature_with_pubkey(
                signed_info_c14n=signed_info_c14n,
                raw_signature=raw_signature,
                key_value=key_value,
                der_encoded_key_value=der_encoded_key_value,
                signature_alg=signature_alg,
            )

        verified_signed_info = self._fromstring(verified_signed_info_c14n)
        verify_results: List[VerifyResult] = []
        for idx, reference in enumerate(self._findall(verified_signed_info, "Reference")):
            verify_results.append(
                self._verify_reference(reference, idx, root, uri_resolver, c14n_algorithm, signature, key_used)
            )

        if type(self.config.expect_references) is int and len(verify_results) != self.config.expect_references:
            msg = "Expected to find {} references, but found {}"
            raise InvalidSignature(msg.format(self.config.expect_references, len(verify_results)))

        return (
            verify_results[0]
            if type(self.config.expect_references) is int and self.config.expect_references == 1
            else verify_results
        )
```

--------------------------------

### verify(data, *, expect_signature_policy=None, expect_config=XAdESSignatureConfiguration(), **xml_verifier_args)

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Verifies a XAdES signature within the provided data and returns a list of XAdESVerifyResult objects. This method acts as a wrapper for the standard XMLVerifier.verify method with additional XAdES-specific validation.

```APIDOC
## verify(data, *, expect_signature_policy=None, expect_config=XAdESSignatureConfiguration(), **xml_verifier_args)

### Description
Verifies the XAdES signature supplied in the data. It returns a list of XAdESVerifyResult data structures or raises an exception if the signature is invalid.

### Parameters
- **data** (Any) - Required - The XML data containing the XAdES signature to verify.
- **expect_signature_policy** (XAdESSignaturePolicy) - Optional - An object used to assert that the signature carries specific data in the SignaturePolicyIdentifier element.
- **expect_config** (XAdESSignatureConfiguration) - Optional - An object describing the expected properties of the verified signature. Defaults to XAdESSignatureConfiguration().
- **xml_verifier_args** (Any) - Optional - Additional keyword arguments passed directly to signxml.XMLVerifier.verify.

### Returns
- **List[XAdESVerifyResult]** - A list of verification results representing the data signed by the signature.
```

--------------------------------

### Process Signature References

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Resolves signature references and prepares canonicalization inputs for XML signing.

```python
    def _get_c14n_inputs_from_references(self, doc_root, references: List[SignatureReference]):
        c14n_inputs, new_references = [], []
        for reference in references:
            uri = reference.URI if reference.URI.startswith("#") else "#" + reference.URI
            c14n_inputs.append(self.get_root(self._resolve_reference(doc_root, {"URI": uri})))
            new_references.append(replace(reference, URI=uri))
        return c14n_inputs, new_references
```

--------------------------------

### Namespace Handling Logic

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Internal method to determine the correct QName for elements based on the current namespace map.

```python
namespaces_map = cast(Dict[Optional[str], str], self.namespaces)
        if namespaces_map.get(None) == namespaces.ds:
            return QName(None, tag)
        return ds_tag(tag)
```

--------------------------------

### Add Data Object Format

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Configures the DataObjectFormat for a signed reference.

```python
def add_data_object_format(self, signed_data_object_properties, sig_root, signing_settings: SigningSettings):
    signed_info = self._find(sig_root, "ds:SignedInfo")
    reference = self._find(signed_info, "ds:Reference")
    if "Id" not in reference.keys():
        reference.set("Id", f"SignXMLReference{self._get_token()}")
    data_object_format = SubElement(
        signed_data_object_properties,
        xades_tag("DataObjectFormat"),
        nsmap=self.namespaces,
        ObjectReference=f"#{reference.get('Id')}",
    )
    description = SubElement(data_object_format, xades_tag("Description"), nsmap=self.namespaces)
    description.text = self.data_object_format.Description
    mime_type = SubElement(data_object_format, xades_tag("MimeType"), nsmap=self.namespaces)
    mime_type.text = self.data_object_format.MimeType
```

--------------------------------

### Preprocess Reference URIs

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Converts input URIs into a list of SignatureReference objects.

```python
    def _preprocess_reference_uri(self, reference_uris):
        if reference_uris is None:
            return None
        if isinstance(reference_uris, (str, bytes)):
            reference_uris = [reference_uris]
        references = list(
            ref if isinstance(ref, SignatureReference) else SignatureReference(URI=ref) for ref in reference_uris
        )
        return references
```

--------------------------------

### Configuring Namespace Prefixes

Source: https://xml-security.github.io/signxml/index.html

Set the XMLSigner.namespaces attribute to define custom namespace mappings before signing. This is critical for XML canonicalization consistency.

```python
signer = signxml.XMLSigner(...)
signer.namespaces = {None: signxml.namespaces.ds}
signed_root = signer.sign(...)
```

--------------------------------

### Initialize XAdES Signer

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

XAdESSigner is used to configure and perform XAdES signing, supporting signature policies, claimed roles, and data object formats.

```python
class XAdESSigner(XAdESProcessor, XMLSigner):
    """
    Create a new XAdES Signature Signer object, which can be used to hold configuration information and sign multiple
    pieces of data. This is a subclass of :class:`signxml.XMLSigner`; all of its configuration semantics are supported.

    :param signature_policy:
        If you need your XAdES signature to carry the **SignaturePolicyIdentifier** element, use this parameter to pass
        a :class:`XAdESSignaturePolicy` object carrying strings and the digest method identifier for the element.
    :param claimed_roles:
        If you need your XAdES signature to carry the **SignerRole/ClaimedRoles** element, use this parameter to pass a
        list of strings to use as text for the **ClaimedRole** tags.
    :param data_object_format:
        If you need your XAdES signature to carry the **DataObjectFormat** element, use this parameter to pass a
        :class:`XAdESDataObjectFormat` object carrying the Description and MimeType strings for the element.
    :param xml_signer_args:
        Parameters to pass to the :class:`signxml.XMLSigner` constructor.
    """

    use_deprecated_legacy_signing_certificate: bool = False
```

--------------------------------

### Verify XAdES Certificate Chain

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Loads certificates from the signature XML and verifies the signing certificate node.

```python
    def _verify_cert_digests(self, verify_result: VerifyResult):
        certs = []
        for x509_data in self._findall(verify_result.signature_xml, "ds:KeyInfo/ds:X509Data"):
            for cert in self._findall(x509_data, "X509Certificate"):
                certs.append(x509.load_pem_x509_certificate(add_pem_header(cert.text)))
        signing_cert = self._find_signing_cert(verify_result, certs)
        if signing_cert is not None:
            self._add_cert_if_missing(certs, signing_cert)

        signed_signature_props = self._find(verify_result.signed_xml, "xades:SignedSignatureProperties")
        signing_cert_node = self._find(signed_signature_props, "xades:SigningCertificate", require=False)
        signing_cert_v2_node = self._find(signed_signature_props, "xades:SigningCertificateV2", require=False)
        if signing_cert_node is None and signing_cert_v2_node is None:
            raise InvalidInput("Expected to find XML element xades:SigningCertificate or xades:SigningCertificateV2")
        if signing_cert_node is not None and signing_cert_v2_node is not None:
            raise InvalidInput("Expected to find exactly one of xades:SigningCertificate or xades:SigningCertificateV2")
        if signing_cert_node is not None:
            self._verify_cert_digest(signing_cert_node, certs=certs, signing_cert=signing_cert)
        elif signing_cert_v2_node is not None:
            self._verify_cert_digest(signing_cert_v2_node, certs=certs, signing_cert=signing_cert)
```

--------------------------------

### Build Signature Properties

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Creates an Object element containing SignatureProperties for the XML signature.

```python
    def _build_signature_properties(self, signature_properties):
        # FIXME: make this use the annotator API
        obj = Element(self._ds_tag("Object"), attrib={"Id": "prop"}, nsmap=self.namespaces)
        signature_properties_el = Element(self._ds_tag("SignatureProperties"))
        for i, el in enumerate(signature_properties):
            signature_property = Element(
                self._ds_tag("SignatureProperty"),
                attrib={
                    "Id": el.attrib.pop("Id", f"sigprop{i}"),
                    "Target": el.attrib.pop("Target", f"#sigproptarget{i}"),
                },
            )
            signature_property.append(el)
            signature_properties_el.append(signature_property)
        obj.append(signature_properties_el)
        return obj
```

--------------------------------

### XML Signature Generation Logic

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Internal implementation of the signing process, including key loading, reference unpacking, and signature construction.

```python
        if id_attribute is not None:
            self.id_attributes = (id_attribute,)

        cert_chain = self._get_cert_chain(cert)

        input_references = self._preprocess_reference_uri(reference_uri)

        signing_settings = SigningSettings(
            key=None,
            key_name=key_name,
            key_info=key_info,
            always_add_key_value=always_add_key_value,
            cert_chain=cert_chain,
        )

        if key is None:
            raise InvalidInput('Parameter "key" is required')
        elif not self.sign_alg.name.startswith("HMAC_"):
            if isinstance(key, (str, bytes)):
                signing_settings.key = load_pem_private_key(ensure_bytes(key), password=passphrase)
            else:
                signing_settings.key = key

        sig_root, doc_root, c14n_inputs, references = self._unpack(data, input_references)

        if self.construction_method == SignatureConstructionMethod.detached and signature_properties is not None:
            references.append(SignatureReference(URI="#prop"))
            if signature_properties is not None and not isinstance(signature_properties, list):
                signature_properties = [signature_properties]
            signature_properties_el = self._build_signature_properties(signature_properties)
            c14n_inputs.append(signature_properties_el)

        signed_info_node, signature_value_node = self._build_sig(
            sig_root,
            references=references,
            c14n_inputs=c14n_inputs,
            inclusive_ns_prefixes=inclusive_ns_prefixes,
            exclude_c14n_transform_element=exclude_c14n_transform_element,
        )

        for signature_annotator in self.signature_annotators:
            signature_annotator(sig_root, signing_settings=signing_settings)
```

--------------------------------

### Add KeyInfo to Signature

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Appends KeyInfo elements to the signature root if not using HMAC and if KeyInfo is not already provided.

```python
    def _add_key_info(self, sig_root, signing_settings: SigningSettings):
        if self.sign_alg.name.startswith("HMAC_"):
            return
        if signing_settings.key_info is None:
            key_info = SubElement(sig_root, self._ds_tag("KeyInfo"))
            if signing_settings.key_name is not None:
                keyname = SubElement(key_info, self._ds_tag("KeyName"))
                keyname.text = signing_settings.key_name

            if signing_settings.cert_chain is None or signing_settings.always_add_key_value:
                self._serialize_key_value(signing_settings.key, key_info)
```

--------------------------------

### Verify KeyValue Against Public Key

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Compares a KeyValue element from an XML signature against a provided public key for ECDSA, DSA, or RSA algorithms.

```python
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, ec.EllipticCurvePublicKey):
        ec_key_value = self._find(key_value, "dsig11:ECKeyValue")
        named_curve = self._find(ec_key_value, "dsig11:NamedCurve")
        pub_key = self._find(ec_key_value, "dsig11:PublicKey")
        key_data = b64decode(pub_key.text)[1:]
        x = bytes_to_long(key_data[: len(key_data) // 2])
        y = bytes_to_long(key_data[len(key_data) // 2 :])
        curve_uri = named_curve.get("URI")
        if curve_uri is None:
            return False
        curve = self.known_ecdsa_curves[curve_uri]

        pubk_curve = public_key.public_numbers().curve
        pubk_x = public_key.public_numbers().x
        pubk_y = public_key.public_numbers().y

        return pubk_curve.name == curve.name and x == pubk_x and y == pubk_y

    elif signature_alg.name.startswith("DSA_") and isinstance(public_key, dsa.DSAPublicKey):
        dsa_key_value = self._find(key_value, "DSAKeyValue")
        p = self._get_long(dsa_key_value, "P")
        q = self._get_long(dsa_key_value, "Q")
        g = self._get_long(dsa_key_value, "G", require=False)

        pubk_p = public_key.public_numbers().parameter_numbers.p
        pubk_q = public_key.public_numbers().parameter_numbers.q
        pubk_g = public_key.public_numbers().parameter_numbers.g

        return p == pubk_p and q == pubk_q and g == pubk_g

    elif signature_alg.name.startswith("RSA_") and isinstance(public_key, rsa.RSAPublicKey):
        rsa_key_value = self._find(key_value, "RSAKeyValue")
        n = self._get_long(rsa_key_value, "Modulus")
        e = self._get_long(rsa_key_value, "Exponent")

        pubk_n = public_key.public_numbers().n
        pubk_e = public_key.public_numbers().e

        return n == pubk_n and e == pubk_e

    raise NotImplementedError()
```

--------------------------------

### XMLSigner.sign()

Source: https://xml-security.github.io/signxml/index.html

Signs an XML document using the configured settings.

```APIDOC
## XMLSigner.sign()

### Description
Signs the provided XML document using the configuration defined in the XMLSigner instance.

### Method
Method call

### Parameters
- **data** (Element) - Required - The XML element to sign.
- **key** (Key) - Required - The private key used for signing.
- **cert** (Certificate) - Optional - The certificate to include in the signature.
```

--------------------------------

### signxml.SignatureConfiguration

Source: https://xml-security.github.io/signxml/index.html

A container holding signature settings that will be used to assert properties of the signature during verification.

```APIDOC
## class signxml.SignatureConfiguration

### Description
A container holding signature settings that will be used to assert properties of the signature.

### Parameters
- **require_x509** (bool) - Optional - If True, a valid X.509 certificate-based signature is required. Defaults to True.
- **location** (str) - Optional - XPath location where the signature tag is expected. Defaults to './/'.
- **expect_references** (int | bool) - Optional - Number of references to expect in the signature. Defaults to 1.
- **signature_methods** (FrozenSet[SignatureMethod]) - Optional - Set of acceptable signature algorithms.
- **digest_algorithms** (FrozenSet[DigestAlgorithm]) - Optional - Set of acceptable digest algorithms.
- **ignore_ambiguous_key_info** (bool) - Optional - Whether to ignore ambiguous key info. Defaults to False.
- **verification_time** (datetime) - Optional - The time used for verification.
- **default_reference_c14n_method** (CanonicalizationMethod) - Optional - The default canonicalization method.
```

--------------------------------

### SignatureConfiguration.expect_references

Source: https://xml-security.github.io/signxml/index.html

Specifies the expected number of references in XAdES signatures. By default, it is set to 3 (original data, KeyInfo, and signed properties).

```APIDOC
## SignatureConfiguration.expect_references

### Description
Specifies the expected number of references in XAdES signatures. By default, XAdES signatures carry 3 references (the original data reference, the KeyInfo (X.509 certificate) reference, and the signed properties reference). Signatures can carry more references if more data or extensions are present.

### Type
int | bool

### Default Value
3
```

--------------------------------

### Add Signature Production Place

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Placeholder method for adding SignatureProductionPlace properties.

```python
def add_signature_production_place(self, signed_signature_properties, sig_root, signing_settings: SigningSettings):
    # SignatureProductionPlace or SignatureProductionPlaceV2
    pass
```

--------------------------------

### Verify XML signature with SAML assertion path

Source: https://xml-security.github.io/signxml/index.html

Configure the signature location to target a specific child element, such as a SAML Assertion, within the XML document.

```python
config = SignatureConfiguration(
    location="./{urn:oasis:names:tc:SAML:2.0:assertion}Assertion/"
)
XMLVerifier().verify(response_xml, x509_cert=cert, expect_config=config)
```

--------------------------------

### XMLVerifier.verify

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

The verify method is the primary entry point for validating XML signatures. It processes the input data and returns a VerifyResult object containing the signed data, parsed XML elements, and the verification key.

```APIDOC
## XMLVerifier().verify(input_data)

### Description
Verifies an XML signature within the provided input data. Returns a VerifyResult object containing the signed bytes, parsed XML, and the key used for verification.

### Parameters
- **input_data** (bytes/Element) - Required - The XML data containing the signature to be verified.

### Returns
- **VerifyResult** (dataclass) - An object containing:
  - **signed_data** (bytes): The binary data as it was signed.
  - **signed_xml** (etree._Element): The signed data parsed as XML.
  - **signature_xml** (etree._Element): The signature element parsed as XML.
  - **signature_key** (bytes): The cryptographic key used to verify the signature.
```

--------------------------------

### XAdESSigner.sign()

Source: https://xml-security.github.io/signxml/index.html

Signs an XML document with XAdES extensions.

```APIDOC
## XAdESSigner.sign()

### Description
Signs the XML document and adds XAdES-specific properties to the signature.

### Method
Method call

### Parameters
- **data** (Element) - Required - The XML element to sign.
- **key** (Key) - Required - The private key used for signing.
```

--------------------------------

### Configure XMLSigner to excise empty xmlns declarations

Source: https://xml-security.github.io/signxml/changelog.html

Enables the removal of empty xmlns declarations during the XML signing process.

```python
signer = XMLSigner()
signer.excise_empty_xmlns_declarations = True
signer.sign(...)
```

--------------------------------

### Verify XAdES Signed Properties

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Orchestrates the verification of signing time, certificate digests, and signature policy.

```python
    def _verify_signed_properties(self, verify_result):
        self._verify_signing_time(verify_result)
        self._verify_cert_digests(verify_result)
        if self.expect_signature_policy:
            self._verify_signature_policy(
                verify_result=verify_result, expect_signature_policy=self.expect_signature_policy
            )
        return self._find(verify_result.signed_xml, "xades:SignedSignatureProperties")
```

--------------------------------

### XMLVerifier.verify()

Source: https://xml-security.github.io/signxml/index.html

Verifies an XML signature against the provided data.

```APIDOC
## XMLVerifier.verify()

### Description
Verifies the XML signature of the provided data and returns a VerifyResult object.

### Method
Method call

### Parameters
- **data** (Element) - Required - The XML document or element containing the signature to verify.
- **x509_cert** (Certificate) - Optional - The public key or certificate to use for verification.
```

--------------------------------

### XMLSigner

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

The XMLSigner class is used to hold configuration information and sign XML data. It supports enveloped, enveloping, and detached signature construction methods.

```APIDOC
## XMLSigner(method, signature_algorithm, digest_algorithm, c14n_algorithm)

### Description
Initializes a new XML Signature Signer object. This object maintains the configuration required to sign multiple pieces of XML data.

### Parameters
- **method** (SignatureConstructionMethod) - Optional - The construction method (enveloped, enveloping, or detached).
- **signature_algorithm** (Union[SignatureMethod, str]) - Optional - The algorithm used to generate the signature.
- **digest_algorithm** (Union[DigestAlgorithm, str]) - Optional - The algorithm used to hash the data.
- **c14n_algorithm** (Union[CanonicalizationMethod, str]) - Optional - The algorithm used to canonicalize the XML.
```

--------------------------------

### signxml.xades.XAdESSigner

Source: https://xml-security.github.io/signxml/index.html

The XAdESSigner class is used to configure and perform XAdES signatures. It inherits from XMLSigner and supports additional XAdES-specific metadata elements.

```APIDOC
## class signxml.xades.XAdESSigner

### Description
Creates a new XAdES Signature Signer object to hold configuration and sign data.

### Parameters
- **signature_policy** (XAdESSignaturePolicy) - Optional - Object carrying strings and digest method for the SignaturePolicyIdentifier element.
- **claimed_roles** (List) - Optional - List of strings for the SignerRole/ClaimedRoles element.
- **data_object_format** (XAdESDataObjectFormat) - Optional - Object carrying Description and MimeType for the DataObjectFormat element.
- **xml_signer_args** (dict) - Optional - Additional arguments passed to the XMLSigner constructor.
```

--------------------------------

### Build XML Signature Transforms

Source: https://xml-security.github.io/signxml/_modules/signxml/signer.html

Constructs the Transform elements for a signature reference, handling enveloped signatures and canonicalization methods.

```python
    def _build_transforms_for_reference(
        self, *, transforms_node: _Element, reference: SignatureReference, exclude_c14n_transform_element: bool = True
    ):
        assert reference.c14n_method is not None
        if self.construction_method == SignatureConstructionMethod.enveloped:
            SubElement(
                transforms_node, self._ds_tag("Transform"), Algorithm=SignatureConstructionMethod.enveloped.value
            )
            if not exclude_c14n_transform_element:
                SubElement(transforms_node, self._ds_tag("Transform"), Algorithm=reference.c14n_method.value)
        else:
            if not exclude_c14n_transform_element:
                c14n_xform = SubElement(
                    transforms_node,
                    self._ds_tag("Transform"),
                    Algorithm=reference.c14n_method.value,
                )
            if reference.inclusive_ns_prefixes:
                SubElement(
                    c14n_xform, ec_tag("InclusiveNamespaces"), PrefixList=" ".join(reference.inclusive_ns_prefixes)
                )
```

--------------------------------

### Define digest algorithm implementations

Source: https://xml-security.github.io/signxml/_modules/signxml/algorithms.html

A dictionary mapping DigestAlgorithm and SignatureMethod enums to their respective cryptography hash algorithm classes.

```python
digest_algorithm_implementations: Dict[Union[DigestAlgorithm, SignatureMethod], Type[hashes.HashAlgorithm]] = {
    DigestAlgorithm.SHA1: hashes.SHA1,
    DigestAlgorithm.SHA224: hashes.SHA224,
    DigestAlgorithm.SHA384: hashes.SHA384,
    DigestAlgorithm.SHA256: hashes.SHA256,
    DigestAlgorithm.SHA512: hashes.SHA512,
    DigestAlgorithm.SHA3_224: hashes.SHA3_224,
    DigestAlgorithm.SHA3_256: hashes.SHA3_256,
    DigestAlgorithm.SHA3_384: hashes.SHA3_384,
    DigestAlgorithm.SHA3_512: hashes.SHA3_512,
    SignatureMethod.DSA_SHA1: hashes.SHA1,
    SignatureMethod.HMAC_SHA1: hashes.SHA1,
    SignatureMethod.RSA_SHA1: hashes.SHA1,
    SignatureMethod.ECDSA_SHA1: hashes.SHA1,
    SignatureMethod.ECDSA_SHA224: hashes.SHA224,
    SignatureMethod.ECDSA_SHA256: hashes.SHA256,
    SignatureMethod.ECDSA_SHA384: hashes.SHA384,
    SignatureMethod.ECDSA_SHA512: hashes.SHA512,
    SignatureMethod.HMAC_SHA224: hashes.SHA224,
    SignatureMethod.HMAC_SHA256: hashes.SHA256,
    SignatureMethod.HMAC_SHA384: hashes.SHA384,
    SignatureMethod.HMAC_SHA512: hashes.SHA512,
    SignatureMethod.RSA_SHA224: hashes.SHA224,
    SignatureMethod.RSA_SHA256: hashes.SHA256,
    SignatureMethod.RSA_SHA384: hashes.SHA384,
    SignatureMethod.RSA_SHA512: hashes.SHA512,
    SignatureMethod.DSA_SHA256: hashes.SHA256,
    SignatureMethod.ECDSA_SHA3_224: hashes.SHA3_224,
    SignatureMethod.ECDSA_SHA3_256: hashes.SHA3_256,
    SignatureMethod.ECDSA_SHA3_384: hashes.SHA3_384,
    SignatureMethod.ECDSA_SHA3_512: hashes.SHA3_512,
    SignatureMethod.SHA3_224_RSA_MGF1: hashes.SHA3_224,
    SignatureMethod.SHA3_256_RSA_MGF1: hashes.SHA3_256,
    SignatureMethod.SHA3_384_RSA_MGF1: hashes.SHA3_384,
    SignatureMethod.SHA3_512_RSA_MGF1: hashes.SHA3_512,
    SignatureMethod.SHA224_RSA_MGF1: hashes.SHA224,
    SignatureMethod.SHA256_RSA_MGF1: hashes.SHA256,
    SignatureMethod.SHA384_RSA_MGF1: hashes.SHA384,
    SignatureMethod.SHA512_RSA_MGF1: hashes.SHA512,
    SignatureMethod.SHA1_RSA_MGF1: hashes.SHA1,
}
```

--------------------------------

### XML Signature Verification Logic

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Internal verification workflow handling canonicalization, signature extraction, and X.509 certificate validation.

```python
        if validate_schema:
            self.validate_schema(signature)

        signed_info = self._find(signature, "SignedInfo")
        c14n_method = self._find(signed_info, "CanonicalizationMethod")
        c14n_algorithm = CanonicalizationMethod(c14n_method.get("Algorithm"))
        inclusive_ns_prefixes = self._get_inclusive_ns_prefixes(c14n_method)
        signature_method = self._find(signed_info, "SignatureMethod")
        signature_value = self._find(signature, "SignatureValue")
        signature_alg = SignatureMethod(signature_method.get("Algorithm"))
        self.check_signature_alg_expected(signature_alg)
        raw_signature = b64decode(signature_value.text)
        x509_data = signature.find("ds:KeyInfo/ds:X509Data", namespaces=namespaces)
        key_value = signature.find("ds:KeyInfo/ds:KeyValue", namespaces=namespaces)
        der_encoded_key_value = signature.find("ds:KeyInfo/dsig11:DEREncodedKeyValue", namespaces=namespaces)
        signed_info_c14n = self._c14n(
            signed_info, algorithm=c14n_algorithm, inclusive_ns_prefixes=inclusive_ns_prefixes
        )

        if x509_data is not None or self.config.require_x509:
            if self.x509_cert is None:
                if x509_data is None:
                    raise InvalidInput("Expected a X.509 certificate based signature")
                certs = [cert.text for cert in self._findall(x509_data, "X509Certificate")]
                cert_chain_source = "X509Data/X509Certificate"
                if len(certs) == 0:
                    x509_iss = x509_data.find("ds:X509IssuerSerial/ds:X509IssuerName", namespaces=namespaces)
                    x509_sn = x509_data.find("ds:X509IssuerSerial/ds:X509SerialNumber", namespaces=namespaces)
                    x509_digest = x509_data.find("dsig11:X509Digest", namespaces=namespaces)
                    if cert_resolver and any(i is not None for i in (x509_iss, x509_sn, x509_digest)):
                        cert_chain = cert_resolver(
                            x509_issuer_name=x509_iss.text if x509_iss is not None else None,
                            x509_serial_number=x509_sn.text if x509_sn is not None else None,
                            x509_digest=x509_digest.text if x509_digest is not None else None,
                        )
                        if len(cert_chain) == 0:
                            raise InvalidCertificate("No certificate found for given X509 data")
                        cert_chain_source = "cert_resolver result"
                        if not all(isinstance(c, x509.Certificate) for c in cert_chain):
                            cert_chain = [x509.load_pem_x509_certificate(add_pem_header(cert)) for cert in cert_chain]
                    else:
                        msg = "Expected to find an X509Certificate element in the signature"
                        msg += " (X509SubjectName, X509SKI are not supported)"
                        raise InvalidInput(msg)
                else:
                    cert_chain = [x509.load_pem_x509_certificate(add_pem_header(cert)) for cert in certs]

                cert_verifier = self.get_cert_chain_verifier(
                    ca_pem_file=ca_pem_file, ee_policy=ee_policy, ca_policy=ca_policy
                )

                try:
                    signing_cert = cert_verifier.verify(cert_chain)
                except InvalidCertificate as exc:
                    if "valid at validation time" in str(exc):
                        for index, cert in enumerate(cert_chain):
                            self._check_cert_validity(cert, f"{cert_chain_source} certificate at index {index}")
                    raise
                signing_cert_source = f"verified {cert_chain_source} signing certificate"
            elif isinstance(self.x509_cert, x509.Certificate):
                signing_cert = self.x509_cert
                signing_cert_source = "provided x509_cert"
            else:
                signing_cert = x509.load_pem_x509_certificate(add_pem_header(self.x509_cert))
                signing_cert_source = "provided x509_cert"

            self._check_cert_validity(signing_cert, signing_cert_source)

            if cert_subject_name is not None:
                cn_oid = x509.oid.NameOID.COMMON_NAME
                subject_cn_from_signing_cert = signing_cert.subject.get_attributes_for_oid(cn_oid)[0].value
                if subject_cn_from_signing_cert != cert_subject_name:
                    raise InvalidSignature("Certificate subject common name mismatch")
```

--------------------------------

### XAdES Sign Method

Source: https://xml-security.github.io/signxml/_modules/signxml/xades/xades.html

Wraps the standard XMLSigner sign method with XAdES-specific logic.

```python
    @_with_parent_signature(XMLSigner.sign)
    def sign(self, data, always_add_key_value: bool = True, **kwargs: Any) -> _Element:
        return super().sign(data=data, always_add_key_value=always_add_key_value, **kwargs)
```

--------------------------------

### XMLVerifier.verify

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Verifies the XML signature supplied in the data and returns a list of VerifyResult data structures representing the signed data, or raises an exception if the signature is invalid.

```APIDOC
## XMLVerifier.verify(data, **kwargs)

### Description
Verifies an XML signature within the provided data. By default, it requires a valid X.509 certificate for validation.

### Parameters
- **data** (Any) - Required - The XML data to verify.
- **x509_cert** (str | x509.Certificate) - Optional - The certificate to use for verification.
- **cert_subject_name** (str) - Optional - The expected subject name in the signing certificate.
- **cert_resolver** (Callable) - Optional - A resolver for certificates.
- **ca_pem_file** (str | bytes) - Optional - A custom CA PEM file for trust establishment.
- **hmac_key** (bytes) - Optional - The HMAC key if using HMAC signatures.
- **validate_schema** (bool) - Optional - Whether to validate the XML schema (default: True).
- **expect_config** (SignatureConfiguration) - Optional - Configuration for verification, including location and verification time.

### Returns
- **Union[VerifyResult, List[VerifyResult]]** - The result of the verification process.
```

--------------------------------

### Match Key Values

Source: https://xml-security.github.io/signxml/_modules/signxml/verifier.html

Verifies that public keys provided in KeyValue or DEREncodedKeyValue match the signing certificate's public key.

```python
    def _match_key_values(self, key_value, der_encoded_key_value, signing_cert, signature_alg):
        if self.config.ignore_ambiguous_key_info is True:
            return
        cert_pub_key = signing_cert.public_key()
        # If both X509Data and KeyValue are present, match one against the other and raise an error on mismatch
        if key_value is not None:
            match_result = self._check_key_value_matches_cert_public_key(key_value, cert_pub_key, signature_alg)
            if match_result is False:
                raise InvalidInput(
                    "Both X509Data and KeyValue found and they represent different public keys. "
                    "Use verify(ignore_ambiguous_key_info=True) to ignore KeyValue and validate "
                    "using X509Data only."
                )

        # If both X509Data and DEREncodedKeyValue are present, match one against the other and raise an error on
        # mismatch
        if der_encoded_key_value is not None:
            match_result = self._check_der_key_value_matches_cert_public_key(
                der_encoded_key_value, signing_cert.public_key(), signature_alg
            )
            if match_result is False:
                raise InvalidInput(
                    "Both X509Data and DEREncodedKeyValue found and they represent different "
                    "public keys. Use verify(ignore_ambiguous_key_info=True) to ignore "
                    "DEREncodedKeyValue and validate using X509Data only."
                )
```
Tokens:
Raw