signxml 4.4.0

Verifying SAML assertions

Assuming metadata.xml contains SAML metadata for the assertion source:

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

XML signature construction methods: enveloped, detached, enveloping

The XML Signature specification defines three ways to compose a signature with the data being signed: enveloped, detached, and enveloping signature. Enveloped is the default method. To specify the type of signature that you want to generate, pass the method argument to sign():

signed_root = XMLSigner(method=signxml.methods.detached).sign(root, key=key, cert=cert)
verified_data = XMLVerifier().verify(signed_root).signed_xml

For detached signatures, the code above will use the Id or ID attribute of root to generate a relative URI (<Reference URI="#value"). You can also override the value of URI by passing a reference_uri argument to sign(). To verify a detached signature that refers to an external entity, pass a callable resolver in XMLVerifier().verify(data, uri_resolver=...).

See the API documentation for more details.

XML representation details: Configuring namespace prefixes and whitespace

Some applications require a particular namespace prefix configuration - for example, a number of applications assume that the http://www.w3.org/2000/09/xmldsig# namespace is set as the default, unprefixed namespace instead of using the customary ds: prefix. While in normal use namespace prefix naming is an insignificant representation detail, it can be significant in some XML canonicalization and signature configurations. To configure the namespace prefix map when generating a signature, set the XMLSigner.namespaces attribute:

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

Similarly, whitespace in the signed document is significant for XML canonicalization and signature purposes. Do not pretty-print the XML after generating the signature, since this can unfortunately render the signature invalid.

XML parsing security and compatibility with xml.etree.ElementTree

SignXML uses the lxml ElementTree library, not the ElementTree from Python’s standard library, to work with XML. lxml is used due to its superior resistance to XML attacks, as well as XML canonicalization and namespace organization features. It is recommended that you pass XML string input directly to signxml before further parsing, and use lxml to work with untrusted XML input in general. If you do pass xml.etree.ElementTree objects to SignXML, you should be aware of differences in XML namespace handling between the two libraries. See the following references for more information:

• How do I use lxml safely as a web-service endpoint?

• ElementTree compatibility of lxml.etree

• XML Signatures with Python ElementTree

XAdES signatures

XAdES (“XML Advanced Electronic Signatures”) is a standard for attaching metadata to XML Signature objects. This standard is endorsed by the European Union as the implementation for its eSignature regulations.

SignXML supports signing and verifying documents using XAdES signatures:

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)

verifier = XAdESVerifier()
verify_results = verifier.verify(
    signed_doc, x509_cert=certificate, expect_references=3, expect_signature_policy=signature_policy
)
for verify_result in verify_results:
    if isinstance(verify_result, XAdESVerifyResult):
        verify_result.signed_properties  # use this to access parsed XAdES properties

Bugs

Please report bugs, issues, feature requests, etc. on GitHub.

Versioning

This package follows the Semantic Versioning 2.0.0 standard. To control changes, it is recommended that application developers pin the package version and manage it using uv or similar. For library developers, pinning the major version is recommended.