Skip to main content

Crate ribergshamra_dsig

Crate ribergshamra_dsig 

Source
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 — the NodeId of the <Signature> element that was verified.
  • references — a Vec<VerifiedReference>, one per <Reference> in <SignedInfo>. Each entry contains the uri string and the resolved_node (an Option<NodeId>) that the URI resolved to, plus digest_verified to 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 the KeysManager. 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 returning VerifyResult::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.

ⓘ
// 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;

Modules§

context
DSig context — holds keys and configuration for signature operations.
sign
XML-DSig signature creation.
verify
XML-DSig signature verification.