pybergshamra

Python bindings for the Bergshamra XML Security library -- a pure-Rust implementation of XML Digital Signatures (XML-DSig), XML Encryption (XML-Enc), C14N canonicalization, and cryptographic primitives.

pybergshamra gives you a fast, correct, and memory-safe XML security toolkit from Python with no C dependencies to compile and no transitive native libraries to audit.

Features

• XML Digital Signatures -- sign and verify (RSA, EC, Ed25519, HMAC, post-quantum)
• XML Encryption -- encrypt and decrypt (AES-CBC/GCM, RSA-OAEP key transport)
• C14N canonicalization -- inclusive, exclusive, with/without comments
• Key management -- RSA, EC, Ed25519, X25519, HMAC, AES, 3DES, PKCS#12, X.509
• Certificate validation -- X.509 chain building and verification with CRL support
• Cryptographic primitives -- digest, PBKDF2, HKDF, ConcatKDF
• Post-quantum signatures -- ML-DSA-44/65/87, SLH-DSA
• HSM / PKCS#11 -- sign, verify, encrypt and decrypt with keys that never leave a hardware token (or SoftHSM2)
• Anti-XSW protection -- strict verification mode
• Zero Python dependencies -- ships as a single native extension

Security note: weak-digest X.509 policy

Starting with Bergshamra 0.5.x, X.509 certificate chains signed with weak digests (MD5, SHA-1, SHA-224) are rejected by default. pybergshamra is built with Bergshamra's legacy-algorithms feature enabled, so validate_cert_chain() and signature verification that builds an X.509 chain accept these legacy digests for backward compatibility with existing certificates. The policy is fixed at build time -- there is no per-call runtime toggle. To get strict, secure-by-default rejection of weak digests, build the extension yourself with the legacy-algorithms feature removed from the bergshamra-keys dependency in Cargo.toml.

PBKDF2 also now enforces the RFC 8018 minimum salt length of 8 bytes; shorter salts raise CryptoError.

Installation

python3 -m pip install pybergshamra

Or with uv:

uv add pybergshamra

Wheels are compiled from Rust via maturin. Python 3.10+ is required.

Quick start

Verify a signed XML document

import pybergshamra

xml = open("signed.xml").read()

manager = pybergshamra.KeysManager()
key = pybergshamra.load_x509_cert_pem(open("cert.pem", "rb").read())
manager.add_key(key)

ctx = pybergshamra.DsigContext(manager)
result = pybergshamra.verify(ctx, xml)

if result:
    print("Valid!", result.key_info.algorithm)
else:
    print("Invalid:", result.reason)

Sign an XML template

import pybergshamra

template = open("sign-template.xml").read()

manager = pybergshamra.KeysManager()
key = pybergshamra.load_rsa_private_pem(open("rsakey.pem", "rb").read())
manager.add_key(key)

ctx = pybergshamra.DsigContext(manager)
signed_xml = pybergshamra.sign(ctx, template)

Encrypt and decrypt

import pybergshamra

# Encrypt
manager = pybergshamra.KeysManager()
key = pybergshamra.load_x509_cert_pem(open("cert.pem", "rb").read())
manager.add_key(key)

ctx = pybergshamra.EncContext(manager)
encrypted_xml = pybergshamra.encrypt(ctx, template_xml, b"secret data")

# Decrypt
manager = pybergshamra.KeysManager()
key = pybergshamra.load_rsa_private_pem(open("rsakey.pem", "rb").read())
manager.add_key(key)

ctx = pybergshamra.EncContext(manager)
decrypted_xml = pybergshamra.decrypt(ctx, encrypted_xml)

Canonicalize XML

import pybergshamra
from pybergshamra import C14nMode

result = pybergshamra.canonicalize(xml_string, C14nMode.Exclusive)

Compute a digest

from pybergshamra import digest, Algorithm

h = digest(Algorithm.SHA256, b"hello world")
print(h.hex())

Sign with a key on an HSM (PKCS#11)

Key material stays on the token; pybergshamra talks to it over PKCS#11 (tested against SoftHSM2). Algorithms are given as W3C URIs from Algorithm; ECDSA also needs an ec_curve because the URI does not encode the curve.

import pybergshamra
from pybergshamra import Algorithm

provider = pybergshamra.Pkcs11Provider.with_token(
    "/usr/lib/softhsm/libsofthsm2.so",
    "production-signing-token",
    token_serial="11429933786539",  # optional when the label is unique
)
session = provider.open_session("1234")  # user PIN

# Sign an XML template with an RSA key on the token
manager = pybergshamra.KeysManager()
sign_ctx = pybergshamra.DsigContext(manager)
sign_ctx.set_hsm_signer(
    pybergshamra.Pkcs11Signer(session, "my-rsa-key", Algorithm.RSA_SHA256)
)
signed_xml = pybergshamra.sign(sign_ctx, template_xml)

# Verify with the matching public key on the token
verify_ctx = pybergshamra.DsigContext(manager)
verify_ctx.set_hsm_verifier(
    pybergshamra.Pkcs11Verifier(session, "my-rsa-key", Algorithm.RSA_SHA256)
)
assert bool(pybergshamra.verify(verify_ctx, signed_xml))

Use Pkcs11Provider.with_slot_id(module, slot_id) when the deployment pins slots directly. The plain Pkcs11Provider(module) constructor remains available for single-token deployments and fails closed if multiple initialized tokens are visible. provider.slot_id reports the selected slot.

EncContext exposes the same idea for encryption via set_hsm_decryptor(), set_hsm_key_unwrapper(), set_hsm_encryptor(), and set_hsm_key_wrapper(), each taking an allow-list of permitted algorithm URIs. The HSM operation classes (Pkcs11Signer, Pkcs11Verifier, Pkcs11Decryptor, Pkcs11Encryptor, Pkcs11KeyWrapper) also expose direct sign()/verify()/decrypt()/ encrypt()/wrap()/unwrap() methods for standalone use.

Run bash hsm-test/setup.sh to provision a local SoftHSM2 token, then SOFTHSM2_CONF=hsm-test/softhsm2.local.conf pytest tests/test_hsm.py to exercise the PKCS#11 path. The CI hsm job does the same on every PR.

API overview

The *_document APIs require pyuppsala 0.11.0 or newer. They serialize at the Python-extension boundary and safely import successful signing results back into the original document, including a preserved DOCTYPE; no Rust DOM pointers cross shared libraries. Install both packages with pip install 'pybergshamra[documents]'.

DsigContext(manager) uses secure defaults (trusted_keys_only, strict_verification, hmac_min_out_len=160, and required local reference digests) recommended for federated identity. Use DsigContext(manager, secure_defaults=False) or DsigContext.permissive(manager) only when inline KeyInfo and relaxed structure checks are intentional. Each VerifiedReference now also reports digest_verified so callers can tell whether a reference's digest was actually checked. | load_key_file(path) | Load a key from file (auto-detect format) | | load_rsa_private_pem(data) | Load an RSA private key from PEM | | load_x509_cert_pem(data) | Load an X.509 certificate from PEM | | load_hmac_key(data) | Create an HMAC key from raw bytes | | load_aes_key(data) | Create an AES key from raw bytes | | load_pem_auto(data) | Auto-detect PEM type and load |

See the full API reference for all 28 key loaders, algorithm constants, and configuration options.

Exceptions

All exceptions inherit from BergshamraError, which inherits from Exception.

Migrating from python-xmlsec

pybergshamra (together with pyuppsala for XML building) is a complete replacement for python-xmlsec with zero C dependencies. See the migration guide for side-by-side examples.

Type stubs

A pybergshamra.pyi file is included for full IDE auto-completion and type-checking with mypy/pyright.

Development

# Clone the repository
git clone https://github.com/kushaldas/pybergshamra.git
cd pybergshamra

# Set up the environment with uv
uv sync

# Build the native extension in development mode
uv run maturin develop

# Run the test suite
uv run pytest

# Build a release wheel
uv run maturin build --release

License

BSD-2-Clause