Expand description
XML Digital Signature (XML-DSig) implementation.
Provides signature verification and creation per the W3C XML-DSig spec.
§Security Hardening
XML Digital Signatures are a frequent target of attack. ribergshamra provides several layered protections that you should understand and enable as appropriate for your application.
§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.
ribergshamra always 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::verify and sign::sign return
Err(Error::XmlStructure("duplicate ID: …")) if a duplicate is found.
No opt-in is required — this protection is unconditional.
§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 theuristring and theresolved_node(anOption<NodeId>) that the URI resolved to, plusdigest_verifiedto report whether ribergshamra locally computed and checked that reference digest.
If digest_verified is false, the reference is currently a cid:
attachment reference: its URI, transforms, and declared digest are
integrity-protected by the signed <SignedInfo>, but the external
attachment bytes were not hashed by ribergshamra. 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. Match on
VerifyResult::Valid and inspect references 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 validate attachment bytes out-of-band can opt
out by calling DsigContext::with_require_reference_digests with false.
§Trust Anchors and Inline Keys
When trusted certificates are configured, raw inline keys from <KeyValue>
or <DEREncodedKeyValue> are rejected because they have no certificate chain
to validate against those anchors. Inline <X509Data> remains supported, but
its chain must validate to a configured trust anchor.
Library callers that must reproduce xmlsec compatibility behavior can opt
back into raw inline keys with
DsigContext::with_allow_raw_inline_keyinfo_with_trust_anchors. Do not
enable that flag for normal verification of untrusted XML: it means a raw
document-controlled key may verify even though trust anchors are configured.
Use DsigContext::trusted_keys_only when the accepted signing keys are
known ahead of time and all document-supplied keys should be ignored.
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:
use ribergshamra_dsig::VerifyResult;
let result = ribergshamra_dsig::verify::verify(&ctx, &xml)?;
match result {
VerifyResult::Valid { references, .. } => {
let covers_assertion = references.iter().any(|r| {
r.resolved_node.is_some_and(|n| {
doc.element(n).is_some_and(|e| {
&*e.name.local_name == "Assertion"
})
})
});
assert!(covers_assertion, "signature must cover the Assertion");
}
VerifyResult::Invalid { reason } => panic!("invalid: {reason}"),
}§Strict Verification Mode (opt-in)
Set DsigContext::strict_verification to true 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 with
Err(Error::XmlStructure("strict mode: …")).
This is the strongest defence against XSW attacks and is recommended for SAML and WS-Security consumers where the document structure is well-known.
let ctx = DsigContext::new(keys_manager); // secure defaults: strict + trusted_keys_only
let result = ribergshamra_dsig::verify::verify(&ctx, &xml)?;The CLI exposes this as ribergshamra verify --strict --trusted-keys-only.
§Secure Defaults (DsigContext::new)
DsigContext::new() enables secure defaults out of the box:
trusted_keys_only = true— ignores inline keys in<KeyInfo>(<KeyValue>,<X509Certificate>, etc.) and only uses keys from theKeysManager. Without this, an attacker who controls the XML can embed their own key and forge a valid signature.strict_verification = true— rejects references to nodes that are not ancestors, siblings, or the document element (XSW protection).hmac_min_out_len = 160— enforces a minimum HMAC output length of 160 bits to prevent truncation attacks (CVE-2009-0217).require_reference_digests = true— requires at least one<Reference>and requires every<Reference>digest to be locally verified before returningVerifyResult::Valid.
Use DsigContext::new_permissive() when you need inline-key and relaxed
structural behavior for self-contained signatures. It still requires local
reference-digest coverage unless you explicitly disable that policy.
§Recommended Configuration for SAML
// DsigContext::new() already has secure defaults — just add cert validation:
let mut ctx = DsigContext::new(keys_manager);
ctx.verify_keys = true;Re-exports§
pub use context::DsigContext;pub use verify::VerifiedKeyInfo;pub use verify::VerifiedReference;pub use verify::VerifyResult;