pybergshamra documentation

pybergshamra is a Python binding 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.

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 held on a hardware token (or SoftHSM2)

• Anti-XSW protection – strict verification mode

• Zero Python dependencies – ships as a single native extension

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 pybergshamra.validate_cert_chain() (and signature verification that builds an X.509 chain) accepts these legacy digests for backward compatibility with existing certificates and the xmlsec test corpus. There is no per-call runtime toggle – the policy is fixed at build time. If you need 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.

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

Contents

• Quick start
  • Installation
  • Load a key
  • Verify a signed XML document
  • Sign an XML template
  • Encrypt data
  • Decrypt data
  • Canonicalize XML
• API reference
  • Algorithm constants
  • Key management
  • Key loaders
  • X509 KeyInfo builders
  • Digital signatures
  • XML encryption
  • Canonicalization
  • Cryptographic primitives
  • Certificate validation
  • PKCS#12 container parsing
  • HSM / PKCS#11
• Exceptions
  • BergshamraError
  • XmlError
  • CryptoError
  • KeyLoadError
  • AlgorithmError
  • EncryptionError
  • CertificateError
  • Exception hierarchy
• Examples
  • Verify a SAML Response
  • Sign an XML document (enveloped)
  • Sign with HMAC
  • Sign with ECDSA
  • Encrypt XML with AES-256-GCM + RSA-OAEP
  • Decrypt an EncryptedAssertion
  • Canonicalize a subtree
  • Certificate chain validation
  • Key derivation
  • Ed25519 signatures
• Migrating from python-xmlsec
  • Why migrate?
  • Key differences
  • Key loading
  • KeysManager
  • Certificate management
  • Signature verification
  • Signature verification with ID registration
  • Signing an XML document
  • XML Encryption
  • Encryption with template
  • Canonicalization
  • Algorithm constants
  • Symmetric key generation
  • Error handling
  • Features only in pybergshamra