hanko_xml 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c179727024902245d166e6754fbc184637057182cc1c8e44eab643b0c69bb344
-  data.tar.gz: 50a2ec96ba76f3bb2888639ea18f730c95e1e8c0b21b83d8223716ec7054693b
+  metadata.gz: 241e74065f571d268cad6511824328bc09678c65b016fef414a7ac6998007624
+  data.tar.gz: be22bc7e10619a4dbfc10df005f9d9b42dde710037482237f8b0306c837b8722
 SHA512:
-  metadata.gz: f6f5636282fbce016d2409cf7f2327259c16ec5ff3c9b2b6983656fdab9d6984828be47cc07e61001f2f941a44e58bc142d585e608e9cf0b1ec1d07f59b3bc92
-  data.tar.gz: d4737956455e23fc4edf6ff830d1765402e926b3976247f1c58089a91f0019a447ad57f0337c633e2994522efbddd623201fe238a8bb95a663e66a621b96ef31
+  metadata.gz: aaffd58bef9c74f6ae5f7c08a9f48cb1bbf0799b3e4ed16566875fd89056c4852a655bf2a71d95b38803d6f145d45219c530875a790d07aa4b1e7aee03a097fd
+  data.tar.gz: e3121dfe4e80797e154cee91b18cedb4dbbdced16a5ea6abdddd2d36ac593718b838c596186b4e73b20954b270b4a2bea9f0b5c6367b4c554059f3e79562b8ca

data/CHANGELOG.md

@@ -8,6 +8,72 @@ tracked separately, and is reported by `HankoXml::NativeVersion.build_versions`.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-19
+
+### Added
+
+- **#162:** XAdES-T signing. `Xades::Signer.new(timestamper: ->(request_der) { response_der })`
+  adds a `<xades:SignatureTimeStamp>`: an RFC 3161 token over the
+  `<ds:SignatureValue>`, canonicalized by xmlsec (#161). The callable does the
+  TSA exchange, so the library never opens a connection. The response must
+  grant the timestamp and carry the request's imprint and nonce, otherwise
+  signing raises `SigningError`. `timestamp_digest_method:` (default: the
+  Signer's `digest_method:`) and `timestamp_canonicalization_method:` (default
+  `:exc_c14n`) go through the Signer's policy.
+- **#163:** XAdES-T verification. `Xades::Verifier` checks every
+  `<xades:SignatureTimeStamp>` of the signature against the TSA trust in
+  `tsa_store:` or `tsa_certificates:`, which is kept separate from the signer's.
+  OpenSSL verifies the token, and its imprint must cover the `<ds:SignatureValue>`
+  as xmlsec canonicalizes it. `Xades::Verification#signature_timestamps` lists
+  them (time, serial, TSA certificate) and `#timestamp_time` gives the earliest.
+  `timestamps: :require` also fails a signature without one (S-22).
+- **#167:** XAdES-LT validation data. `Xades::Augmenter` adds unsigned
+  properties to an existing, signed XAdES signature: a `SignatureTimeStamp`
+  (`timestamper:`, B to T) and `CertificateValues` / `RevocationValues`
+  (`validation_data:`, T to LT), leaving everything signed byte-identical.
+  `Xades::Signer` takes `validation_data:` too, with `timestamper:`.
+  `Xades::ValidationData` holds caller-supplied certificates, CRLs and OCSP
+  responses, type-checked only; the library never fetches them, and nothing
+  embedded is trusted yet (#168).
+- **#168:** XAdES-LT verification. When a signature embeds `CertificateValues`
+  or `RevocationValues`, `Xades::Verifier` validates the signing certificate
+  at the time of its earliest verified SignatureTimeStamp: XML-DSig trust at
+  that time (an expired certificate still verifies; embedded certificates may
+  complete a `store:` chain), then embedded OCSP responses or CRLs for every
+  certificate below the anchor, verified by OpenSSL against the same anchor
+  and issued no earlier than that time (`revocation_grace:` widens it).
+  `long_term: :verify | :require | :ignore`; the result is
+  `Xades::Verification#long_term_validation`. Fail closed (S-23).
+- **#169:** XAdES-LTA. `Xades::Augmenter.new(timestamper:, archive_timestamp: true)`
+  appends a `<xades141:ArchiveTimeStamp>` over the EN 319 132-1 input (the
+  References' data as xmlsec digested it, SignedInfo, SignatureValue, KeyInfo,
+  every unsigned property before it and the other `ds:Object`s); running it
+  again renews it. `Xades::Verifier` verifies every ArchiveTimeStamp against
+  the TSA trust, failing closed, and lists them in
+  `Xades::Verification#archive_timestamps`. `Native.reference_data` returns
+  each Reference's digested octets from xmlsec. SignXML's DSS-produced
+  HU_POL-3 ArchiveTimeStamp verifies.
+
+### Changed
+
+- **#163:** `Xades::Verifier` no longer ignores unsigned SignatureTimeStamps.
+  A signature that carries one now fails verification unless the timestamp
+  verifies, which needs `tsa_store:` or `tsa_certificates:`. Pass
+  `timestamps: :ignore` to keep the XAdES-B-only behavior.
+- **#168:** `Xades::Verifier` no longer ignores embedded `CertificateValues` /
+  `RevocationValues`. A signature that carries them is validated at its
+  timestamp time and fails when that evidence does not hold, which can also
+  make a signature fail that verified before (and one whose certificate has
+  expired pass). Pass `long_term: :ignore` to keep the XAdES-T behavior.
+- **#169:** `Xades::Verifier` no longer ignores `xades141:ArchiveTimeStamp`s:
+  one that does not verify, or one present without TSA trust, fails the
+  signature. `timestamps: :ignore` leaves them unread.
+
+### Fixed
+
+- **#158:** Without Nokogiri, `Signer#sign!` and `Signer#template` given a String
+  now raise `NokogiriRequired` naming themselves instead of `HankoXml.parse`.
+
 ## [0.1.0] - 2026-10-15
 
 First release.

data/Cargo.lock

@@ -138,7 +138,7 @@ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
 [[package]]
 name = "hanko_xml"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "bindgen 0.73.1",
  "magnus",

data/README.md

@@ -18,9 +18,10 @@ It works nicely with Nokogiri, signing and verifying the documents you already h
 - **Full XML-DSig Support:** Sign and verify Enveloped, Enveloping, and Detached signatures.
 - **Nokogiri Native, Nokogiri Optional:** Signs and verifies the Nokogiri documents you already hold, with opt-in `doc.sign!` / `doc.signature_valid?` shorthands (`require "hanko_xml/nokogiri_ext"`), and verifies Strings, files and IOs without Nokogiri.
 - **XSW Defense:** Provides a robust `Policy` engine and structural `signed?(node)` checks to defeat XML Signature Wrapping (XSW) attacks.
+- **XAdES, B to LTA:** `HankoXml::Xades::Signer`, `Augmenter` and `Verifier` sign, timestamp (RFC 3161, through a TSA exchange you supply), embed validation data and add renewable archive timestamps, and verify all of it fail closed. See the [XAdES guide](docs/src/content/guide/xades.md).
 - **Rust-Backed:** Memory-safe FFI boundaries, zero shell-outs to CLI binaries, and massive performance gains over pure-Ruby cryptography.
 
-A feature and security comparison with Python [SignXML](https://pypi.org/project/signxml/), including a plan to close the remaining gaps (XAdES first), lives in [`docs/src/content/guide/comparison-signxml.md`](docs/src/content/guide/comparison-signxml.md).
+A feature and security comparison with Python [SignXML](https://pypi.org/project/signxml/), including the plan that closed the XAdES gap, lives in [`docs/src/content/guide/comparison-signxml.md`](docs/src/content/guide/comparison-signxml.md).
 
 ## Requirements
 

data/ext/hanko_xml/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hanko_xml"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 authors = ["Danimar Ribeiro <danimaribeiro@gmail.com>"]
 license = "MIT"

data/ext/hanko_xml/src/dsig.rs

@@ -647,6 +647,18 @@ impl<'mngr> DsigCtx<'mngr> {
         }
     }
 
+    /// Keeps each SignedInfo Reference's transform output, the octets
+    /// xmlsec digested, for `reference_octets` (XAdES ArchiveTimeStamp,
+    /// #169).
+    fn store_references(&mut self) {
+        // SAFETY: self.ptr is a live xmlSecDSigCtx we exclusively own; flags
+        // is application-settable and read when each Reference context is
+        // initialized. Same ABI caveat as the signKey write.
+        unsafe {
+            (*self.ptr).flags |= sys::XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES;
+        }
+    }
+
     /// By default xmlsec also resolves and digests the references inside
     /// every `<Object><Manifest>`, whose URIs, transforms and digest methods
     /// never reach Ruby Policy, which reads only `<SignedInfo>` (#75). XML-DSig
@@ -933,6 +945,45 @@ impl<'mngr> DsigCtx<'mngr> {
     }
 }
 
+impl DsigCtx<'_> {
+    /// Per SignedInfo `<Reference>`, in document order, the octets xmlsec
+    /// digested (its pre-digest buffer), after `verify()` ran with
+    /// `store_references()`. `None` for a reference it did not process.
+    fn reference_octets(&self) -> Vec<Option<Vec<u8>>> {
+        // SAFETY: as in reference_statuses: signedInfoReferences is an
+        // embedded xmlSecPtrList that verify() populated.
+        let list = unsafe { ptr::addr_of!((*self.ptr).signedInfoReferences) as sys::xmlSecPtrListPtr };
+        // SAFETY: list is a valid, initialized xmlSecPtrList for self's lifetime.
+        let size = unsafe { sys::xmlSecPtrListGetSize(list) };
+        (0..size)
+            .map(|pos| {
+                // SAFETY: pos is in [0, size).
+                let item = unsafe { sys::xmlSecPtrListGetItem(list, pos) };
+                if item.is_null() {
+                    return None;
+                }
+                // SAFETY: item is a live xmlSecDSigReferenceCtx owned by the
+                // list; the buffer it returns (or null) lives as long as it.
+                let buffer = unsafe {
+                    sys::xmlSecDSigReferenceCtxGetPreDigestBuffer(item as sys::xmlSecDSigReferenceCtxPtr)
+                };
+                if buffer.is_null() {
+                    return None;
+                }
+                // SAFETY: buffer is a valid xmlSecBuffer; data points at size
+                // initialized bytes (or is null when size is 0).
+                let (data, len) = unsafe { (sys::xmlSecBufferGetData(buffer), sys::xmlSecBufferGetSize(buffer)) };
+                let len = usize::try_from(len).ok()?;
+                if data.is_null() || len == 0 {
+                    return Some(Vec::new());
+                }
+                // SAFETY: data is non-null and points at len bytes owned by buffer.
+                Some(unsafe { std::slice::from_raw_parts(data, len) }.to_vec())
+            })
+            .collect()
+    }
+}
+
 impl Drop for DsigCtx<'_> {
     fn drop(&mut self) {
         // SAFETY: we're the exclusive owner of this context.
@@ -1027,6 +1078,9 @@ pub struct VerifyResult {
     /// (`Verification#certificate`), which `certificates:` otherwise leaves
     /// ambiguous.
     pub trusted_index: Option<usize>,
+    /// Per SignedInfo `<Reference>`, the octets xmlsec digested, when
+    /// `verify_document` was asked to store them; empty otherwise (#169).
+    pub reference_octets: Vec<Option<Vec<u8>>>,
 }
 
 const DSIG_NS: &str = "http://www.w3.org/2000/09/xmldsig#";
@@ -1372,6 +1426,158 @@ pub fn validate_signature_schema(
     result
 }
 
+// ---------------------------------------------------------------------------
+// Element canonicalization (#161)
+// ---------------------------------------------------------------------------
+
+/// One step from an element to one of its child elements: namespace href,
+/// local name, and which of the children with that name. `None` means there
+/// must be exactly one.
+pub type ChildStep = (String, String, Option<usize>);
+
+/// The only transforms a [`TransformCtx`] reads: the six canonicalization
+/// methods `restrict_transforms` also allows.
+const C14N_TRANSFORMS: &[unsafe extern "C" fn() -> sys::xmlSecTransformId] = &[
+    sys::xmlSecTransformInclC14NGetKlass,
+    sys::xmlSecTransformInclC14NWithCommentsGetKlass,
+    sys::xmlSecTransformInclC14N11GetKlass,
+    sys::xmlSecTransformInclC14N11WithCommentsGetKlass,
+    sys::xmlSecTransformExclC14NGetKlass,
+    sys::xmlSecTransformExclC14NWithCommentsGetKlass,
+];
+
+/// An owned xmlsec transforms chain that accepts only the C14N transforms.
+struct TransformCtx(sys::xmlSecTransformCtxPtr);
+
+impl TransformCtx {
+    fn c14n_only() -> Result<Self, &'static str> {
+        // SAFETY: creates and initializes a context we own; freed on drop.
+        let ptr = unsafe { sys::xmlSecTransformCtxCreate() };
+        if ptr.is_null() {
+            return Err("failed to create xmlsec transform context");
+        }
+        let ctx = Self(ptr);
+        for get_klass in C14N_TRANSFORMS {
+            // SAFETY: ctx.0 is live and its enabledTransforms list was
+            // initialized by xmlSecTransformCtxCreate. A non-empty list makes
+            // xmlSecTransformNodeRead refuse any transform not in it, which is
+            // how xmlSecDSigCtxEnableReferenceTransform restricts a DSig context.
+            let rc = unsafe {
+                sys::xmlSecPtrListAdd(&mut (*ctx.0).enabledTransforms, get_klass() as *mut c_void)
+            };
+            if rc < 0 {
+                return Err("failed to enable a canonicalization transform");
+            }
+        }
+        Ok(ctx)
+    }
+}
+
+impl Drop for TransformCtx {
+    fn drop(&mut self) {
+        // SAFETY: we're the exclusive owner of this context.
+        unsafe { sys::xmlSecTransformCtxDestroy(self.0) }
+    }
+}
+
+/// An xmlsec node set, destroyed on drop. xmlSecTransformCtxXmlExecute
+/// leaves the set to its caller.
+struct NodeSet(sys::xmlSecNodeSetPtr);
+
+impl Drop for NodeSet {
+    fn drop(&mut self) {
+        // SAFETY: we're the exclusive owner of this node set.
+        unsafe { sys::xmlSecNodeSetDestroy(self.0) }
+    }
+}
+
+/// Follows `path` from `start`, one child element per step. A step with no
+/// index fails unless exactly one child matches, so an ambiguous document is
+/// refused instead of resolved to its first match.
+fn follow_path(start: sys::xmlNodePtr, path: &[ChildStep]) -> Result<sys::xmlNodePtr, DsigError> {
+    let mut node = start;
+    for (ns_href, name, index) in path {
+        // SAFETY: node is a valid element of the document being walked.
+        let matches = unsafe { find_children(node, name, ns_href) };
+        node = match index {
+            None if matches.len() == 1 => matches[0],
+            None => return Err(DsigError::native("a canonicalize path step does not match exactly one element")),
+            Some(i) => *matches
+                .get(*i)
+                .ok_or(DsigError::native("a canonicalize path step index is out of range"))?,
+        };
+    }
+    Ok(node)
+}
+
+/// Canonicalizes one element of the nth `<ds:Signature>` with xmlsec's own
+/// C14N transforms (#161): the bytes a digest over that element covers.
+///
+/// `target` and `method` are paths from the `<ds:Signature>`. `method` must
+/// lead to a `CanonicalizationMethod`-shaped element: xmlsec reads its
+/// `Algorithm` and, for exclusive c14n, its `InclusiveNamespaces`, exactly as
+/// it reads a `<SignedInfo>`'s. Only the six c14n algorithms are accepted.
+/// Comments in the element are kept or dropped as the algorithm says.
+pub fn canonicalize_element(
+    xml: &[u8],
+    signature_index: usize,
+    target: &[ChildStep],
+    method: &[ChildStep],
+) -> Result<Vec<u8>, DsigError> {
+    errors::clear_errors();
+
+    let doc = OwnedXmlDoc::parse(xml).map_err(DsigError::parse)?;
+    let root = doc
+        .root_element()
+        .ok_or(DsigError::parse("XML document has no root element"))?;
+    let sig_node = doc
+        .find_nth_signature(root, signature_index)
+        .ok_or(DsigError::native("signature index out of range"))?;
+    let target_node = follow_path(sig_node, target)?;
+    let method_node = follow_path(sig_node, method)?;
+
+    errors::clear_errors();
+    let ctx = TransformCtx::c14n_only().map_err(DsigError::native)?;
+    // SAFETY: ctx.0 is a fresh context; method_node is valid in doc, which
+    // outlives ctx. The transform read is appended to ctx and freed with it.
+    let transform = unsafe {
+        sys::xmlSecTransformCtxNodeRead(ctx.0, method_node, sys::xmlSecTransformUsageC14NMethod as _)
+    };
+    if transform.is_null() {
+        return Err(DsigError::native("the canonicalization method is not a supported c14n algorithm"));
+    }
+
+    // SAFETY: doc.0 and target_node are valid; withComments = 1 puts comments
+    // in the set so the transform decides whether they are rendered.
+    let nodes = unsafe { sys::xmlSecNodeSetGetChildren(doc.0, target_node, 1, 0) };
+    if nodes.is_null() {
+        return Err(DsigError::native("failed to select the element to canonicalize"));
+    }
+    let nodes = NodeSet(nodes);
+
+    // SAFETY: ctx.0 has its one c14n transform and no URI; nodes belongs to
+    // doc. The result buffer is owned by ctx.
+    let rc = unsafe { sys::xmlSecTransformCtxXmlExecute(ctx.0, nodes.0) };
+    // SAFETY: ctx.0 is live; result is set by a successful execute.
+    let result = unsafe { (*ctx.0).result };
+    if rc < 0 || result.is_null() {
+        return Err(DsigError::native("canonicalization failed"));
+    }
+
+    // SAFETY: result is a live xmlSecBuffer owned by ctx; its data is size
+    // bytes long. The bytes are copied out before ctx is dropped.
+    let (data, size) = unsafe { (sys::xmlSecBufferGetData(result), sys::xmlSecBufferGetSize(result)) };
+    let size = usize::try_from(size).map_err(|_| DsigError::native("canonicalization failed"))?;
+    if size == 0 {
+        return Ok(Vec::new());
+    }
+    if data.is_null() {
+        return Err(DsigError::native("canonicalization failed"));
+    }
+    // SAFETY: see above.
+    Ok(unsafe { std::slice::from_raw_parts(data as *const u8, size) }.to_vec())
+}
+
 /// Signs the document's nth `<ds:Signature>` template.
 ///
 /// The XML must already contain a `<ds:Signature>` skeleton with empty
@@ -1428,6 +1634,10 @@ pub fn sign_document(
 /// Returns a `VerifyResult` with status and captured error messages.
 /// Only raises (returns `Err`) for conditions that are not a verification
 /// verdict (unparseable input, out-of-range index, unreadable key).
+#[allow(
+    clippy::too_many_arguments,
+    reason = "one positional argument per Native.verify parameter, plus store_references (#169)"
+)]
 pub fn verify_document(
     xml: &[u8],
     trusted_pems: &[Vec<u8>],
@@ -1436,6 +1646,7 @@ pub fn verify_document(
     signature_index: usize,
     referenced_documents: HashMap<Vec<u8>, Vec<u8>>,
     allow_xpath_filter2: bool,
+    store_references: bool,
 ) -> Result<VerifyResult, DsigError> {
     errors::clear_errors();
     let serves_external = !referenced_documents.is_empty();
@@ -1489,6 +1700,7 @@ pub fn verify_document(
             reference_valid: vec![None; reference_element_indexes.len()],
             reference_element_indexes,
             trusted_index: None,
+            reference_octets: Vec::new(),
         });
     }
 
@@ -1496,6 +1708,7 @@ pub fn verify_document(
     let mut captured_errors = Vec::new();
     let mut reference_valid = Vec::new();
     let mut trusted_index = None;
+    let mut reference_octets = Vec::new();
     for (key, index) in keys_to_try.into_iter().zip(tried_indexes) {
         errors::clear_errors();
         let mut ctx = DsigCtx::for_signing(&mngr, key).map_err(DsigError::native)?;
@@ -1505,11 +1718,17 @@ pub fn verify_document(
         if allow_xpath_filter2 {
             ctx.enable_xpath_filter2().map_err(DsigError::native)?;
         }
+        if store_references {
+            ctx.store_references();
+        }
         status = ctx.verify(sig_node);
         captured_errors = errors::drain_errors();
         reference_valid = ctx.reference_statuses();
         if status == VerifyStatus::Succeeded {
             trusted_index = Some(index);
+            if store_references {
+                reference_octets = ctx.reference_octets();
+            }
             break;
         }
     }
@@ -1520,6 +1739,7 @@ pub fn verify_document(
         reference_element_indexes,
         reference_valid,
         trusted_index,
+        reference_octets,
     })
 }
 

data/ext/hanko_xml/src/lib.rs

@@ -1,4 +1,4 @@
-//! Magnus glue: 5 functions on `HankoXml::Native`, matching the §7 contract.
+//! Magnus glue: the functions on `HankoXml::Native`, matching the §7 contract.
 //!
 //! Every argument from Ruby is copied into a Rust-owned `Vec<u8>` or `String`
 //! **before** any native call, so there is no `unsafe` in this file — no
@@ -124,6 +124,18 @@ fn rarray_to_strings(ruby: &Ruby, arr: RArray) -> Result<Vec<String>, Error> {
     Ok(result)
 }
 
+/// Extracts an RArray of `[ns_href, local_name, index]` steps (`index` nil
+/// or an Integer) for [`dsig::canonicalize_element`].
+fn rarray_to_steps(ruby: &Ruby, arr: RArray) -> Result<Vec<dsig::ChildStep>, Error> {
+    let mut result = Vec::new();
+    for item in arr.into_iter() {
+        let step: (String, String, Option<usize>) = TryConvert::try_convert(item)
+            .map_err(|_| native_error(ruby, "path step is not a [ns_href, name, index] triple".into()))?;
+        result.push(step);
+    }
+    Ok(result)
+}
+
 // ---------------------------------------------------------------------------
 // Native functions — the §7 contract
 // ---------------------------------------------------------------------------
@@ -201,6 +213,7 @@ fn native_verify(
         signature_index,
         referenced,
         allow_xpath_filter2,
+        false,
     ) {
         Ok(result) => {
             let hash = ruby.hash_new();
@@ -308,6 +321,80 @@ fn native_validate_schema(
     string_slice_to_rarray(ruby, &messages)
 }
 
+/// `HankoXml::Native.canonicalize(xml, signature_index, target_path, method_path)`
+///
+/// Returns the element at `target_path` (from the nth `<ds:Signature>`)
+/// canonicalized by xmlsec with the `CanonicalizationMethod` at
+/// `method_path`, as a binary String (#161).
+fn native_canonicalize(
+    ruby: &Ruby,
+    xml: RString,
+    signature_index: usize,
+    target_path: RArray,
+    method_path: RArray,
+) -> Result<RString, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let target = rarray_to_steps(ruby, target_path)?;
+    let method = rarray_to_steps(ruby, method_path)?;
+    let bytes = dsig::canonicalize_element(&xml_bytes, signature_index, &target, &method)
+        .map_err(|err| dsig_error(ruby, err))?;
+    Ok(ruby.str_from_slice(&bytes))
+}
+
+/// `HankoXml::Native.reference_data(xml, trusted_pems, id_attributes, signature_index, referenced_documents,
+/// allow_xpath_filter2)`
+///
+/// Verifies the nth `<ds:Signature>` as `verify` does and returns, per
+/// SignedInfo `<Reference>` in document order, the octets xmlsec digested
+/// (String, or nil when it did not process that reference). Raises
+/// NativeError when the signature does not verify: those octets are only
+/// worth anything for a signature that holds (#169).
+fn native_reference_data(
+    ruby: &Ruby,
+    xml: RString,
+    trusted_pems: RArray,
+    id_attributes: RArray,
+    signature_index: usize,
+    referenced_documents: RArray,
+    allow_xpath_filter2: bool,
+) -> Result<RArray, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let trusted = rarray_to_byte_vecs(ruby, trusted_pems)?;
+    let id_attrs = rarray_to_strings(ruby, id_attributes)?;
+    let referenced = rarray_to_byte_pairs(ruby, referenced_documents)?;
+
+    let result = dsig::verify_document(
+        &xml_bytes,
+        &trusted,
+        &[],
+        &id_attrs,
+        signature_index,
+        referenced,
+        allow_xpath_filter2,
+        true,
+    )
+    .map_err(|err| dsig_error(ruby, err))?;
+    if result.status != dsig::VerifyStatus::Succeeded {
+        return Err(native_error(ruby, "the signature does not verify, so its reference data is not read".into()));
+    }
+
+    let octets = ruby.ary_new();
+    for entry in &result.reference_octets {
+        let value = match entry {
+            Some(bytes) => ruby.str_from_slice(bytes).as_value(),
+            None => ruby.qnil().as_value(),
+        };
+        octets
+            .push(value)
+            .map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+    }
+    Ok(octets)
+}
+
 /// `HankoXml::Native.inspect_sig(xml, signature_index)`
 ///
 /// Returns metadata about the nth `<ds:Signature>` without performing
@@ -485,6 +572,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_singleton_method("inspect_sig", function!(native_inspect, 2))?;
     native.define_singleton_method("scan", function!(native_scan, 3))?;
     native.define_singleton_method("validate_schema", function!(native_validate_schema, 3))?;
+    native.define_singleton_method("canonicalize", function!(native_canonicalize, 4))?;
+    native.define_singleton_method("reference_data", function!(native_reference_data, 6))?;
 
     Ok(())
 }

data/lib/hanko_xml/signer.rb

@@ -134,6 +134,7 @@ module HankoXml
     # it into +doc_or_xml+ and performs no cryptography -- for inspection
     # and testing (§5.2).
     def template(doc_or_xml)
+      Dom.require!("HankoXml::Signer#template")
       doc = HankoXml.coerce_document(doc_or_xml)
       HankoXml::Template.build(doc, self)
     end
@@ -185,8 +186,10 @@ module HankoXml
       node_signer = signer_for_node(doc_or_xml)
       return node_signer.sign!(doc_or_xml.document, force: force, signature: signature) if node_signer
 
-      doc = HankoXml.coerce_document(doc_or_xml, policy: policy)
+      # Before coercing: a String would otherwise fail inside HankoXml.parse
+      # and name that instead of the method the caller used.
       Dom.require!("HankoXml::Signer#sign!")
+      doc = HankoXml.coerce_document(doc_or_xml, policy: policy)
 
       signatures, adopted = find_or_build_signatures(doc)
       all_sigs_in_order = doc.xpath(".//ds:Signature", ds: NS["ds"])

data/lib/hanko_xml/verifier.rb

@@ -510,7 +510,7 @@ module HankoXml
                 HankoXml::UntrustedCertificate.new("No X509Certificate found in KeyInfo for store verification")]
       end
 
-      chain, error = verified_chain_from_store(embedded)
+      chain, error = verified_chain_from_store(embedded, chain_intermediates)
       leaf = chain&.first
       error ||= signing_certificate_violation(leaf)
       return [nil, nil, error] if error
@@ -549,9 +549,16 @@ module HankoXml
       sig_info.certificates.map { |pem| OpenSSL::X509::Certificate.new(pem) }
     end
 
+    # Untrusted certificates that may complete a store: chain besides those in
+    # <KeyInfo>; never candidates for the signing certificate. Xades::Verifier
+    # supplies a signature's embedded CertificateValues (#168).
+    def chain_intermediates
+      []
+    end
+
     # The chain OpenSSL built and verified for the one end-entity certificate
     # that chains to the store, leaf first, or an error.
-    def verified_chain_from_store(certificates)
+    def verified_chain_from_store(certificates, intermediates = [])
       candidates = end_entity_certificates(certificates)
       candidates = certificates if candidates.empty?
 
@@ -559,7 +566,7 @@ module HankoXml
       last_error = "Certificate chain validation failed"
 
       candidates.each do |leaf|
-        chain = certificates.reject { |cert| cert.equal?(leaf) }
+        chain = certificates.reject { |cert| cert.equal?(leaf) } + intermediates
         ctx = OpenSSL::X509::StoreContext.new(@store, leaf, chain)
         if @policy.check_certificate_validity
           ctx.time = @verification_time if @verification_time

data/lib/hanko_xml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HankoXml
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end