Bergshamra
XML Security library implementing the W3C XML Digital Signatures (XML-DSig), XML Encryption (XML-Enc), and XML Canonicalization (C14N) specifications. Document cryptography is selectable between RustCrypto and AWS-LC through Kryptering; XML parsing uses Uppsala 0.12.1. Bergshamra 0.12.0 is released on November 9, 2026, and requires Rust 1.88.
Features
- XML Digital Signatures — sign and verify (enveloped, enveloping, detached)
- XML Encryption — encrypt and decrypt (element, content, key wrapping, key transport, multi-recipient)
- XML Canonicalization — all 6 W3C C14N variants (inclusive/exclusive, with/without comments, 1.0/1.1) with document-subset filtering via XPath
- X.509 certificate chain — validation with expiry, trust anchors, CRL revocation, chain building
- Post-quantum signatures — ML-DSA (FIPS 204) and SLH-DSA (FIPS 205) with context strings
- EdDSA — Ed25519 signatures (RFC 8032)
- Key agreement — ECDH-ES (P-256/P-384/P-521), X25519, DH-ES (X9.42 finite-field)
- Key derivation — ConcatKDF, HKDF (SHA-256/384/512), PBKDF2
- RSA-OAEP — configurable digest (SHA-1/224/256/384/512), MGF1, and OAEPparams
- HMAC truncation — HMACOutputLength with CVE-2009-0217 minimum length protection
- SAML support — SAML v1.1
AssertionIDattribute as default ID,cid:URI scheme for WS-Security MIME references - CipherReference — resolve encrypted content via URI with XPath and Base64 transforms
- XPath — XPath, XPath Filter 2.0, XPointer for reference processing
- XSLT — identity transform and minimal XSLT for document-subset operations
- OPC Relationship Transform — for Office Open XML signatures (ECMA-376 Part 2)
- Key formats — PEM, DER, PKCS#8 (plain and encrypted), PKCS#12, X.509 (PEM and DER), xmlsec keys.xml, raw symmetric keys
- KeyInfo resolution — KeyName, X509Certificate (multi-cert chain with leaf detection), X509IssuerSerial, RSA/EC/DSA KeyValue, DEREncodedKeyValue, RetrievalMethod, EncryptedKey, KeyInfoReference
#![forbid(unsafe_code)]in each Bergshamra workspace crate; dependencies may use unsafe Rust
Supported algorithms
| Category | Algorithms |
|---|---|
| Digest | SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512, MD5†, RIPEMD-160† |
| Signature (RSA) | RSA PKCS#1 v1.5 (SHA-1/224/256/384/512, MD5†, RIPEMD-160†), RSA-PSS (SHA-1/224/256/384/512, SHA3-224/256/384/512) |
| Signature (EC) | ECDSA (P-256/P-384/P-521 × SHA-1/224/256/384/512, SHA3-224/256/384/512, RIPEMD-160†) |
| Signature (other) | DSA (SHA-1, SHA-256), Ed25519, HMAC (SHA-1/224/256/384/512, MD5†, RIPEMD-160†) |
| Post-quantum | ML-DSA-44/65/87 (FIPS 204) and SLH-DSA SHA2-128f/128s/192f/192s/256f/256s (FIPS 205), each under the xmlsec and the W3C 2026/08/xmldsig-more identifiers |
| Block cipher | AES-128/192/256-CBC, AES-128/192/256-GCM, 3DES-CBC |
| Key wrap | AES-KW-128/192/256 (RFC 3394), 3DES-KW (RFC 3217) |
| Key transport | RSA PKCS#1 v1.5, RSA-OAEP (SHA-1/224/256/384/512 digest, MGF1-SHA-1/224/256/384/512) |
| Key agreement | ECDH-ES (P-256/P-384/P-521), X25519, DH-ES (X9.42) |
| Key derivation | ConcatKDF, HKDF (SHA-256/384/512), PBKDF2 |
| C14N | Inclusive 1.0/1.1, Exclusive 1.0, each ± comments |
| Transforms | Enveloped signature, Base64, XPath, XPath Filter 2.0, XSLT (identity), OPC Relationship |
| Key formats | PEM, DER, PKCS#8, PKCS#12, X.509, xmlsec keys.xml, raw HMAC/AES/3DES |
† MD5 and RIPEMD-160 are behind the legacy-algorithms feature flag.
Exact support depends on the selected provider. See the provider capability table; unsupported parameter combinations fail deterministically and never fall back to another provider.
Cryptographic provider features
The default feature set is rustcrypto, legacy-algorithms, post-quantum,
and pkcs11, preserving the 0.7 software/PQ/HSM surface. Select alternate
document providers with --no-default-features:
Exactly one of rustcrypto or aws-lc is required. The fips feature
selects AWS-LC, is incompatible with RustCrypto, and requires explicit
initialize_backend() before cryptographic use. --all-features is
intentionally invalid. AWS-LC builds are initially supported on Linux
x86_64/aarch64.
Bergshamra ships no C code: every crate in the default dependency graph is
Rust. Benchmarks, methodology, and measured trade-offs are recorded in
performance.md.
xmlsec test suite compatibility
Bergshamra's default RustCrypto configuration is tested against the full xmlsec interoperability test suite. These are the same tests used by the xmlsec1 C library, covering test vectors from the W3C, Merlin, Aleksey, IAIK, NIST, and Phaos interop suites.
| Suite | Passed | Failed | Skipped |
|---|---|---|---|
| Enc | 700 | 0 | 1 |
| DSig | 364 | 0 | 86 |
| Total | 1064 | 0 | 87 |
Three skipped DSig cases are GOST signature transform fixtures (GOST R 34.10-2001, GOST R 34.10-2012-256, GOST R 34.10-2012-512) which require special OS cryptographic libraries not available in the RustCrypto ecosystem, thus outside Kryptering's algorithm contract. Alternate providers use focused capability and policy tests rather than this XMLSEC compatibility gate.
The other 83 skipped DSig phases use historical 512-bit RSA certificates
(the ca2cert intermediate or the RSA-MD5 fixture's signer). RSA 0.10 rejects
RSA keys below 1024 bits, including with legacy-algorithms. The runner
executes those verification commands and records only their known key-import
failures as skips; signature creation and negative tests still run. Positive
certificate-chain tests use RSA-2048/SHA-256 rollover fixtures with both
providers. See dependency status.
The skipped Enc case is existing-document decryption of the
xmlenc11-interop-2012 DH-1024 fixture. Its subgroup order q is even and
composite, which Kryptering rejects even with legacy-algorithms. The
fixture's encryption and round-trip decryption phases use valid RFC 5114
parameters and still run. Prime-subgroup validation remains enforced.
A Python shim (tests/xmlsec1-shim.py) translates xmlsec1 CLI flags to
bergshamra flags. The test runner explicitly skips the incompatible DH-1024
decryption phase when using this shim; running against xmlsec1 retains the
original fixture behavior.
Workspace crates
| Crate | Purpose |
|---|---|
bergshamra-core |
Error types, algorithm URIs, XML namespace/element constants |
bergshamra-xml |
DOM abstraction over Uppsala, NodeSet, XPath, XML writer |
bergshamra-c14n |
All 6 W3C C14N variants with document-subset filtering |
bergshamra-crypto |
Digest, signature, cipher, key wrap, key transport operations |
bergshamra-keys |
Key loading (PEM/DER/PKCS#8/PKCS#12), KeysManager, KeyInfo resolution |
bergshamra-transforms |
Transform pipeline (base64, enveloped, XPath, XSLT, URI handling) |
bergshamra-dsig |
XML Digital Signature verification and creation |
bergshamra-enc |
XML Encryption and decryption |
bergshamra |
CLI binary and re-exports |
Dependency flow: core → xml → c14n → crypto → keys → transforms → dsig/enc → bergshamra
Build & test
Integration tests (xmlsec test suite)
# Enc tests
# DSig tests
CLI usage
# Verify a signed document
# Sign a template
# Decrypt
# Encrypt
Key loading options: -k (auto-detect PEM/DER), -K NAME:FILE (named key),
--pkcs12, --cert, --hmac-key, --aes-key, --keys-file (xmlsec keys.xml),
--trusted (CA cert), --pwd (password).
Library usage
let signed = sign?;
let signed = sign_owned?;
Document-native APIs use Uppsala 0.12 types. Callers that pass an
uppsala::Document directly must also use Uppsala 0.12; the same types are
available through the bergshamra::xml re-exports.
Use sign_owned when the caller already owns a generated template String and
wants to avoid the initial clone that the borrowed sign convenience wrapper
performs.
The 0.8.0 key, digest, and client changes are summarized in the migration guide.
Security hardening
XML Digital Signatures are a frequent target of attack. Bergshamra provides several layered protections — some always-on, some opt-in.
Duplicate ID rejection (always on)
XML Signature Wrapping (XSW) attacks often rely on injecting a second element
with the same Id attribute so that the signature verifies against one element
while the application processes another. Bergshamra unconditionally rejects
documents that contain duplicate ID values across any registered ID attribute
(Id, ID, id, AssertionID, xml:id, and any names added via
DsigContext::add_id_attr). Both verify and sign return an error if a
duplicate is found.
The lower-level XmlDocument::build_id_map helper also rejects duplicate ID
values and returns Err(Error::XmlStructure("duplicate ID: ...".into()))
instead of silently overwriting the earlier element.
Inspecting what was signed (VerifyResult metadata)
A successful verification returns VerifyResult::Valid which carries:
signature_node— theNodeIdof the<Signature>element that was verified.references— aVec<VerifiedReference>, one per<Reference>in<SignedInfo>. Each entry contains the URI string, the resolved target node, anddigest_verified.
When digest_verified is false, the reference is currently a cid:
attachment reference: its URI, transforms, and declared digest are still
integrity-protected by the signed <SignedInfo>, but Bergshamra did not hash
the external attachment bytes. When local digest coverage is explicitly disabled
for detached-content workflows, use
VerifyResult::all_reference_digests_verified() or
VerifyResult::has_unverified_references() to check whether all reference
digests were verified locally or whether any were not. Inspect the references
list when you need per-reference detail.
By default, verification requires local digest coverage: an otherwise valid
SignatureValue is reported invalid when <SignedInfo> has no <Reference>
elements or when any reference digest was not computed locally. Detached-content
profiles that verify attachment bytes out-of-band can opt out with
DsigContext::with_require_reference_digests(false) or the CLI flag
--allow-missing-reference-digests.
Detached bytes that Bergshamra should hash locally must be mapped explicitly
with DsigContext::add_url_map("URI", "file") or CLI --url-map URI=FILE.
Mappings match the URI exactly, or the same URI with a #fragment suffix.
For XML-DSig compatibility, simple relative local file references are also
resolved against the input directory/current working directory. Absolute paths
URI schemes, and parent-directory traversal are rejected for local-file
fallback, and detached bytes are redacted from verifier debug output so an
invalid signature cannot print local file contents.
You should always check that the signature covers the element you intend to
consume. For example, a SAML Service Provider should verify that one of the
references points to the <Assertion> it will process.
Strict verification mode (opt-in)
Set DsigContext::strict_verification = true (or pass --strict on the CLI)
to enforce positional constraints on reference targets. In strict mode every
same-document reference must resolve to a node that is:
- the document element (root), or
- an ancestor of the
<Signature>(the signed element wraps the signature — the common enveloped pattern), or - a sibling of the
<Signature>(both are children of the same parent).
Any other position causes verification to fail. This is the strongest defence against XSW attacks and is recommended for SAML and WS-Security consumers where the document structure is well-known.
Trusted keys only (opt-in)
Set DsigContext::trusted_keys_only = true to ignore inline keys embedded in
<KeyInfo> (<KeyValue>, <X509Certificate>, etc.) and only use keys
pre-loaded into the KeysManager. Without this, an attacker who controls the
XML can embed their own key and sign with it — the signature will verify, but
against the wrong key. This is essential for SAML Service Providers and any
deployment where the signing key is known ahead of time.
Every key in the KeysManager that fits the SignatureMethod is tried, and
the signature is valid when any one of them verifies it. This makes
certificate rollover seamless: load the signer's current and next certificate
together, and documents signed with either verify. <KeyInfo> only decides
which trusted key is tried first; keys embedded in the document are never
used. Each key still has to pass its own chain and expiry checks when trust
anchors are configured, and VerifyResult::Valid.key_info reports which key
verified.
let mut keys = new;
keys.add_keys;
let ctx = new; // trusted_keys_only = true
let result = verify?;
A KeysManager is therefore one trust set: every entry is an accepted signer,
including unnamed HMAC secrets and raw public keys that previously only
verified when they were first. Audit managers when upgrading, and put keys for
signers that must not vouch for each other (two IdPs, two countries) in
separate managers. See
docs/adr/0013-trusted-key-set-verification.md.
When trust anchors are configured, Bergshamra rejects raw inline <KeyValue>
and <DEREncodedKeyValue> keys because they have no certificate chain to
validate. Inline <X509Data> remains supported, but the certificate chain must
validate to a configured anchor.
Library callers that need xmlsec compatibility fixtures where trusted CA
settings are combined with raw inline KeyValue test signatures can explicitly
chain .with_allow_raw_inline_keyinfo_with_trust_anchors(true) on the
DsigContext value. Do not enable that flag for normal verification of
untrusted XML; prefer DsigContext::new for known-key protocols, or
DsigContext::new_permissive(keys).with_enabled_key_data_x509(true) when
inline signer certificates should chain to configured anchors. See
docs/adr/0007-raw-inline-keyinfo-trust-anchors.md for the full policy.
HMAC output truncation (CVE-2009-0217)
Set DsigContext::hmac_min_out_len to enforce a minimum <HMACOutputLength>
in bits. A zero-length or very short HMAC is trivially forgeable.
XML Encryption PBKDF2 iteration limit
XML Encryption documents can carry <xenc11:IterationCount> inside PBKDF2
key-derivation parameters. Bergshamra caps that XML-controlled work factor
before invoking PBKDF2. EncContext::new() uses
bergshamra_enc::context::DEFAULT_MAX_PBKDF2_ITERATIONS; set
EncContext::max_pbkdf2_iterations or use
EncContext::with_max_pbkdf2_iterations() when a deployment needs a lower or
higher CPU budget. A value of 0 rejects XML Encryption PBKDF2 usage.
Recommended configuration for SAML
let mut ctx = new;
ctx.trusted_keys_only = true; // reject inline keys
ctx.strict_verification = true; // reject unexpected reference positions
ctx.verify_keys = true; // validate the IdP certificate chain
Or on the CLI:
Security examples
The secexample repository contains runnable demonstrations of three XML signature attacks and how bergshamra detects and rejects each one:
- XML Signature Wrapping (XSW) — relocates signed content to fool the application
- Key Injection — attacker signs with their own key embedded in
<KeyInfo> - HMAC Truncation (CVE-2009-0217) — reduces HMAC output to a brute-forceable length
Each demo shows both a naive verifier that is vulnerable and a secure verifier using the defences described above.
License
BSD-2-Clause License. See LICENSE for details.