Python XML Signature and XAdES library
Project description
SignXML is an implementation of the W3C XML Signature standard in Python. This standard (also known as “XMLDSig”) is used to provide payload security in SAML 2.0, XAdES, and WS-Security, among other uses. The standard is defined in the W3C Recommendation XML Signature Syntax and Processing Version 1.1. SignXML implements all of the required components of the Version 1.1 standard, and most recommended ones. Its features are:
Use of a libxml2-based XML parser configured to defend against common XML attacks when verifying signatures
Extensions to allow signing with and verifying X.509 certificate chains, including hostname/CN validation
Extensions to sign and verify XAdES signatures
Support for exclusive XML canonicalization with inclusive prefixes (InclusiveNamespaces PrefixList, required to verify signatures generated by some SAML implementations)
Modern Python compatibility (3.7-3.11+ and PyPy)
Well-supported, portable, reliable dependencies: lxml, cryptography, pyOpenSSL
Comprehensive testing (including the XMLDSig interoperability suite) and continuous integration
Simple interface with useful, ergonomic, and secure defaults (no network calls, XSLT or XPath transforms)
Compactness, readability, and extensibility
Installation
pip install signxml
Note: SignXML depends on lxml and cryptography, which in turn depend on OpenSSL, LibXML, and Python tools to interface with them. You can install those as follows:
OS |
Command |
|---|---|
Ubuntu |
apt-get install --no-install-recommends python3-pip python3-wheel python3-setuptools python3-openssl python3-lxml |
Red Hat, Amazon Linux, CentOS |
yum install python3-pip python3-pyOpenSSL python3-lxml |
Mac OS |
Install Homebrew, then run brew install python. |
Synopsis
SignXML uses the lxml ElementTree API to work with XML data.
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_xmlTo make this example self-sufficient for test purposes:
Generate a test certificate and key using openssl req -x509 -nodes -subj "/CN=test" -days 1 -newkey rsa -keyout privkey.pem -out cert.pem (run yum install openssl on Red Hat).
Pass the x509_cert=cert keyword argument to XMLVerifier.verify(). (In production, ensure this is replaced with the correct configuration for the trusted CA or certificate - this determines which signatures your application trusts.)
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_xmlXML 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_xmlFor 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:
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 propertiesLinks
W3C Recommendation: XML Signature Syntax and Processing Version 1.1
W3C Working Group Note: Test Cases for C14N 1.1 and XMLDSig Interoperability
W3C Working Group Note: XML Signature Syntax and Processing Version 2.0 (This draft standard proposal was never finalized and is not in general use.)
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 pip-tools or similar. For library developers, pinning the major version is recommended.
License
Copyright 2014-2023, Andrey Kislyuk and SignXML contributors. Licensed under the terms of the Apache License, Version 2.0. Distribution of the LICENSE and NOTICE files with source copies of this package and derivative works is REQUIRED as specified by the Apache License.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file signxml-3.1.1.tar.gz.
File metadata
- Download URL: signxml-3.1.1.tar.gz
- Upload date:
- Size: 58.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7b9aa930c9840bbc02081cbda43a19400cbb08c0baa23e6c0a71bf99cadb1cf4 |
|
| MD5 | 88b51c085c920c95a485d0ac6067f74e |
|
| BLAKE2b-256 | 8a6f64aa3a1a67abe8f00b4fed3f85f64a24a6915e720a8bfbf0cde19e1f48d0 |
File details
Details for the file signxml-3.1.1-py3-none-any.whl.
File metadata
- Download URL: signxml-3.1.1-py3-none-any.whl
- Upload date:
- Size: 57.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1f7c8de222915441a358eab8e7a09f75ecea17ec147361791df99291565e367f |
|
| MD5 | eb384fdd4cbe199558829bfff4b10b0f |
|
| BLAKE2b-256 | 9318c00b545c53b8156b962d30941963b4e0acc33d82f1dc2636a02f4375dc25 |
