python-xmlsec

xmlsec is a CPython extension that binds directly to libxmlsec1, the C reference implementation of the W3C XML Digital Signature (XMLDSig) and XML Encryption (XMLEnc) standards. Rather than reimplementing XML crypto in Python, it exposes libxmlsec1’s signing, verification, encryption, and decryption routines as a small set of typed Python classes that operate directly on lxml _Element objects, so callers work with the same tree they already parsed instead of shuttling serialized XML through a subprocess or separate library.

The package is most often reached for by SAML, WS-Security, and XML-based invoicing or e-signature integrations, where a counterparty demands standards-compliant XMLDSig signatures or XMLEnc-encrypted payloads rather than an ad-hoc signing scheme. It ships prebuilt wheels for Linux, macOS, and Windows across current CPython versions so most installs don’t require a local libxmlsec1/libxml2 toolchain, while still supporting source builds against system libraries when a specific crypto backend is required.

What You Get

• A SignatureContext class for signing and verifying lxml element trees or raw bytes, with support for enabling specific reference and signature transforms and registering ID attributes for enveloped signatures.
• An EncryptionContext class covering XML, binary, and URI-based encryption/decryption, plus a KeysManager for looking up decryption keys by certificate or key name.
• A Key class with classmethods for loading keys and certificates from files, memory, binary data, PKCS#11 engines, or by generating new keys, covering the common real-world key-management entry points.
• Full type stubs (py.typed, .pyi files) validated against the compiled extension in CI, so IDEs and mypy get accurate signatures for a native binding rather than falling back to Any.
• Prebuilt wheels for manylinux, macOS (Intel + Apple Silicon), and Windows across current CPython versions, avoiding a local libxmlsec1/libxml2 build in the common case.

Common Use Cases

• Signing and verifying SAML assertions and metadata for single sign-on integrations that require XMLDSig-conformant signatures.
• Implementing WS-Security message signing/encryption for SOAP-based enterprise and government interoperability APIs.
• Producing digitally signed XML documents for e-invoicing, e-signature, or regulatory filing systems that mandate the XMLDSig standard.
• Encrypting sensitive XML payload fragments (XMLEnc) before transmission to a partner system that only accepts standards-based XML encryption.

Under The Hood

Architecture xmlsec is organized as a set of C translation units under src/ (main.c, keys.c, ds.c, enc.c, tree.c, template.c, constants.c, exception.c, lxml.c, utils.c) that map one-to-one onto libxmlsec1’s own module boundaries — signature contexts, encryption contexts, key/key-manager handling, tree utilities, and template helpers each get their own file, with lxml.c/lxml.h providing the bridge that converts lxml’s _Element Python objects into the raw xmlNode pointers libxmlsec1 expects. setup.py globs every .c file under src/ into a single xmlsec Extension built via a custom build_ext in build_support/, which locates libxmlsec1/libxml2 through pkgconfig or, for wheel builds, a vendored static build (build_support/static_build.py, lib_xmlsec_dependency_builder.py). Because every operation depends on the lxml-to-libxml2 node bridge, that bridging layer is effectively the single point of failure the whole extension is built around.

Tech Stack The project targets CPython 3.9-3.14, depends at the Python level only on lxml>=3.8, and requires libxml2>=2.9.1 and libxmlsec1>=1.2.33 at the system level. Packaging uses setuptools with setuptools_scm for version derivation and pkgconfig for native-library discovery; releases are built with cibuildwheel across manylinux (x86_64/aarch64/riscv64), macOS (x86_64/arm64), and Windows (AMD64), driven by a set of GitHub Actions workflows (manylinux.yml, macosx.yml, linuxbrew.yml, wheels.yml, sdist.yml, cache_libs.yml) that separately validate Homebrew, Linuxbrew, and static-linked builds.

Code Quality The test suite under tests/ covers signatures, encryption, keys, templates, tree helpers, constants, PKCS#11, and the type stubs themselves (test_type_stubs.py), and a custom TestMemoryLeaks base class in tests/base.py re-runs each test many times while watching resource.getrusage and GC object counts to catch native memory leaks and reference-count growth — a scrutiny level uncommon in typical C-extension bindings. Type checking is enforced with a strict mypy configuration (disallow_untyped_defs, disallow_any_generics, warn_return_any, and friends) against the .pyi stubs, and ruff runs a broad rule set (pycodestyle, pyflakes, isort, bugbear, pyupgrade, simplify) via pre-commit.ci. Coverage is tracked through Codecov.

API Design The public surface is deliberately small: Key, KeysManager, SignatureContext, and EncryptionContext, with classmethods like from_file, from_memory, and generate covering the common ways a key arrives, and verbs like sign, verify, encrypt_xml, and decrypt operating directly on lxml elements already in hand. There’s no intermediate serialization step or separate template-building DSL beyond the template submodule used to construct the initial signature/encryption skeleton, keeping the amount of boilerplate needed to sign or verify a document low for a binding to a fairly involved native library.