hanko_xml 0.1.0-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0b6411c7bfd43b93201dc27a5be27486692c17b795591a79794e32ad044c6cc
-  data.tar.gz: 5de806837fa525410a6218de1afad38878cc5a1f2314174de1200ed745dbe0fa
+  metadata.gz: 5dbc235211e7031b7bf4d32375716b790a0cdd3d57866babc430c7f861edaff7
+  data.tar.gz: ef42208f4f0fe811c8e5b02ddcb3da813758be210de357f5e4ce6abe0c83fe5a
 SHA512:
-  metadata.gz: 19f8fc0233cb84d1742f855fb7f4a0b92a21ebc2eb5f8add186b6ab5e1d035abf3b896682f09fda890be684017c5564c64b9a3e7f35121441582248a54427d68
-  data.tar.gz: 8da69665c5dc95bb05a68cd320c1c40289b0b3d9784ecde1ec8193a24b28404fa449cdddd037f37c8badd4eccfcc419ff842f5a4b382150fc87291faf3b8c930
+  metadata.gz: 7be04c955748de9852f05046f65ae21e566f17fd6672ec33c62c58d3d95b92226987d7f48afacab96da9586adf80523ee19f0adc3e03f526292ff5b95335c635
+  data.tar.gz: fbe9e82aaa66c5a0c5aa00a4b138618135c622a7ca1eb11f181d12045c49c1523bfbb234107ec6a3fe23acbedd3626ae33e592cd5ba6517516b8fae12f22c112

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

data/lib/hanko_xml/xades/augmenter.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module HankoXml
+  module Xades
+    # Adds unsigned properties to a XAdES signature that already exists
+    # (#167): a <xades:SignatureTimeStamp> (B to T), the validation data of
+    # XAdES-LT (T to LT), and a <xades141:ArchiveTimeStamp> (LT to LTA,
+    # #169; again later to renew it). Revocation data is best collected after the
+    # signature timestamp exists, so LT is usually added later, by the
+    # holder of the signed document rather than the signer.
+    #
+    #   augmenter = HankoXml::Xades::Augmenter.new(
+    #     validation_data: { certificates: chain, ocsp_responses: [ocsp_der] }
+    #   )
+    #   lt = augmenter.augment(signed_xml)
+    #
+    # Nothing a Reference covers changes: the new elements go into
+    # UnsignedSignatureProperties, found along the same fixed path
+    # Xades::Verifier reads (Xades::Locator), and the document is written
+    # back with HankoXml.serialize, so the existing digests and
+    # SignatureValue still verify.
+    #
+    # The Augmenter does not verify the signature it extends, and embedding
+    # material vouches for nothing: verify first, and a verifier treats the
+    # embedded values as untrusted (S-22). It never fetches: the timestamper:
+    # callable and the caller's validation data are its only inputs.
+    #
+    # Writes XAdES 1.3.2 only, and needs Nokogiri.
+    class Augmenter
+      attr_reader :timestamper, :timestamp_digest_method, :timestamp_canonicalization_method, :validation_data,
+                  :archive_timestamp, :archive_canonicalization_method, :policy
+
+      # @param timestamper [#call, nil] As for {Xades::Signer}: adds a SignatureTimeStamp.
+      # @param timestamp_digest_method [Symbol] The imprint digest.
+      # @param timestamp_canonicalization_method [Symbol] How <ds:SignatureValue> is canonicalized for the
+      #   imprint.
+      # @param validation_data [ValidationData, Hash, nil] Adds CertificateValues and RevocationValues; the
+      #   signature must have a SignatureTimeStamp, or timestamper: adds one first.
+      # @param archive_timestamp [Boolean] Adds an ArchiveTimeStamp, last, from timestamper:, over the signature
+      #   and all its validation data. timestamper: then adds a SignatureTimeStamp only when the signature has
+      #   none. The signature must carry LT values, or validation_data: adds them first.
+      # @param archive_canonicalization_method [Symbol] The ArchiveTimeStamp's CanonicalizationMethod. Inclusive
+      #   c14n by default: a Reference that leaves a node set (as Xades::Signer's enveloped one does) is
+      #   covered with xmlsec's inclusive c14n, so any other method is refused for such a signature.
+      # @param policy [Policy] Checks the imprint algorithms and limits the document size.
+      def initialize(timestamper: nil, timestamp_digest_method: :sha256, timestamp_canonicalization_method: :exc_c14n,
+                     validation_data: nil, archive_timestamp: false, archive_canonicalization_method: :c14n,
+                     policy: HankoXml::Policy.strict)
+        SignatureTimeStamper.check_timestamper!(timestamper)
+        @timestamper = timestamper
+        @timestamp_digest_method = timestamp_digest_method
+        @timestamp_canonicalization_method = timestamp_canonicalization_method
+        @validation_data = ValidationData.coerce(validation_data)
+        @policy = policy
+        @archive_timestamp = archive_timestamp ? true : false
+        @archive_canonicalization_method = archive_canonicalization_method
+        nothing = !timestamper && !@validation_data
+        raise HankoXml::ConfigurationError, "pass timestamper:, validation_data: or both" if nothing
+        if @archive_timestamp && !timestamper
+          raise HankoXml::ConfigurationError, "archive_timestamp: needs timestamper:, which obtains it"
+        end
+
+        if timestamper
+          SignatureTimeStamper.check_algorithms!(policy, digest: timestamp_digest_method,
+                                                         canonicalization: timestamp_canonicalization_method)
+        end
+        check_archive_canonicalization_method! if @archive_timestamp
+        freeze
+      end
+
+      # A copy of the document with the nth signature augmented.
+      #
+      # @param source [String, Nokogiri::XML::Document, IO, Pathname] The signed document.
+      # @param signature [Integer, nil] The document-order index of the <ds:Signature>; nil when the
+      #   document has exactly one.
+      # @return [SignedDocument]
+      # @raise [XadesError] when the signature's XAdES structure cannot take the properties.
+      # @raise [SigningError] when the TSA's answer does not hold (as for Xades::Signer).
+      def augment(source, signature: nil)
+        Dom.require!("HankoXml::Xades::Augmenter")
+        doc = HankoXml.coerce_document(source, policy: policy).dup
+        signatures = doc.xpath("//ds:Signature", "ds" => HankoXml::NS["ds"])
+        index = signature_index(signatures.size, signature)
+        node = signatures[index]
+        value = node.at_xpath("ds:SignatureValue", "ds" => HankoXml::NS["ds"])
+        if value.nil? || value.text.strip.empty?
+          raise HankoXml::ConfigurationError, "the <Signature> is not signed yet; augment a signed document"
+        end
+
+        augment_signature(doc, node, index)
+        SignedDocument.new(doc)
+      end
+
+      def inspect
+        "#<#{self.class} timestamper=#{!timestamper.nil?} validation_data=#{!validation_data.nil?}>"
+      end
+
+      private
+
+      def check_archive_canonicalization_method!
+        unless HankoXml::Algorithms.uri_for(:canonicalization, archive_canonicalization_method)
+          raise HankoXml::ConfigurationError, "archive_canonicalization_method: " \
+                                              "#{archive_canonicalization_method.inspect} is not a registered " \
+                                              "canonicalization algorithm"
+        end
+
+        policy.enforce_algorithm!(:canonicalization, archive_canonicalization_method)
+      end
+
+      def signature_index(count, signature)
+        raise HankoXml::ConfigurationError, "the document has no <ds:Signature> to augment" if count.zero?
+
+        if signature.nil?
+          return 0 if count == 1
+
+          raise HankoXml::ConfigurationError, "the document has #{count} signatures; pass signature: (an index)"
+        end
+        unless signature.is_a?(Integer) && signature.between?(-count, count - 1)
+          raise HankoXml::ConfigurationError, "signature: #{signature.inspect} not found"
+        end
+
+        signature % count
+      end
+
+      def augment_signature(doc, signature, index)
+        qualifying, ns = Locator.qualifying_properties(signature)
+        Locator.fail!("Xades::Augmenter writes only XAdES 1.3.2 QualifyingProperties") unless ns["xades"] == NS
+
+        properties = Locator.unsigned_signature_properties(qualifying, ns) || create_unsigned(qualifying)
+        timestamped = properties.at_xpath("xades:SignatureTimeStamp", ns)
+        if timestamper && !(archive_timestamp && timestamped)
+          add_signature_timestamp(doc, signature, index, qualifying, properties)
+        end
+        add_validation_data(properties, qualifying, ns) if validation_data
+        add_archive_timestamp(doc, signature, index, qualifying, properties) if archive_timestamp
+      end
+
+      def add_validation_data(properties, qualifying, ns)
+        unless properties.at_xpath("xades:SignatureTimeStamp", ns)
+          raise HankoXml::ConfigurationError,
+                "XAdES-LT builds on XAdES-T: the signature has no <xades:SignatureTimeStamp>; pass timestamper: too"
+        end
+
+        validation_data.append_to(properties, qualifying.namespace)
+      end
+
+      # The skeleton goes in first, so xmlsec reads its CanonicalizationMethod;
+      # its input (ArchiveTimeStampCheck.input) is everything before it. The
+      # References' data comes from xmlsec verifying the signature with a
+      # certificate of its own KeyInfo: that vouches for nothing, but a signature
+      # that does not hold is not archived.
+      def add_archive_timestamp(doc, signature, index, qualifying, properties)
+        if properties.xpath("xades:CertificateValues | xades:RevocationValues", "xades" => NS).empty?
+          raise HankoXml::ConfigurationError,
+                "XAdES-LTA builds on XAdES-LT: the signature has no CertificateValues or RevocationValues; " \
+                "pass validation_data: too"
+        end
+
+        position = properties.xpath("xades141:ArchiveTimeStamp", "xades141" => NS141).size
+        archive = properties.add_child(element(doc, "ArchiveTimeStamp"))
+        attach(archive, archive.add_namespace_definition("xades141", NS141))
+        archive["Id"] = unique_id(doc, "#{signature["Id"]}-ats")
+        method = attach(archive.add_child(element(doc, "CanonicalizationMethod")), signature.namespace)
+        method["Algorithm"] = HankoXml::Algorithms.uri_for(:canonicalization, archive_canonicalization_method)
+        encapsulated = attach(archive.add_child(element(doc, "EncapsulatedTimeStamp")), qualifying.namespace)
+
+        bytes = HankoXml.serialize(doc)
+        path = Locator.unsigned_path(signature, qualifying, NS)
+        method_path = [*path, [NS141, "ArchiveTimeStamp", position],
+                       [HankoXml::NS["ds"], "CanonicalizationMethod", nil]]
+        check_node_set_references!(bytes, index, method["Algorithm"])
+        input = ArchiveTimeStampCheck.input(bytes, index, reference_data(bytes, index, signature),
+                                            ArchiveTimeStampCheck.element_paths(signature, qualifying, properties,
+                                                                                archive, path),
+                                            method_path)
+        encapsulated.content = [SignatureTimeStamper.new(self).token_for(input)].pack("m0")
+      end
+
+      def check_node_set_references!(bytes, index, method)
+        info = HankoXml::SignatureInfo.from_native(Native.inspect_sig(bytes, index))
+        unless ArchiveTimeStampCheck.node_set_references?(info) && method != ArchiveTimeStampCheck::INCLUSIVE_C14N
+          return
+        end
+
+        raise HankoXml::ConfigurationError,
+              "a Reference of this signature leaves a node set, which an ArchiveTimeStamp covers with inclusive " \
+              "c14n only: pass archive_canonicalization_method: :c14n"
+      end
+
+      def reference_data(bytes, index, signature)
+        certificates = signature.xpath("ds:KeyInfo/ds:X509Data/ds:X509Certificate", "ds" => HankoXml::NS["ds"])
+                                .map { |node| OpenSSL::X509::Certificate.new(node.text.gsub(/\s/, "").unpack1("m")).to_pem }
+        Native.reference_data(bytes, certificates, %w[Id ID id], index, [], policy.allows?(:transform, :xpath_filter2))
+      rescue HankoXml::NativeError, OpenSSL::X509::CertificateError, ArgumentError
+        Locator.fail!("an ArchiveTimeStamp needs the signature to verify with a <ds:X509Certificate> of its KeyInfo")
+      end
+
+      # UnsignedProperties (last in QualifyingProperties) and its
+      # UnsignedSignatureProperties (first in UnsignedProperties).
+      def create_unsigned(qualifying)
+        doc = qualifying.document
+        namespace = qualifying.namespace
+        unsigned = qualifying.at_xpath("xades:UnsignedProperties", "xades" => NS) ||
+                   attach(qualifying.add_child(element(doc, "UnsignedProperties")), namespace)
+        properties = element(doc, "UnsignedSignatureProperties")
+        first = unsigned.children.first
+        attach(first ? first.add_previous_sibling(properties) : unsigned.add_child(properties), namespace)
+      end
+
+      # The skeleton goes in first, so xmlsec reads its CanonicalizationMethod
+      # (#161) from the bytes, as for Xades::Signer; then the token is filled in.
+      def add_signature_timestamp(doc, signature, index, qualifying, properties)
+        position = properties.xpath("xades:SignatureTimeStamp", "xades" => NS).size
+        timestamp = attach(properties.add_child(element(doc, "SignatureTimeStamp")), qualifying.namespace)
+        timestamp["Id"] = unique_id(doc, "#{signature["Id"]}-sigts")
+        method = attach(timestamp.add_child(element(doc, "CanonicalizationMethod")), signature.namespace)
+        method["Algorithm"] = HankoXml::Algorithms.uri_for(:canonicalization, timestamp_canonicalization_method)
+        encapsulated = attach(timestamp.add_child(element(doc, "EncapsulatedTimeStamp")), qualifying.namespace)
+
+        path = [*Locator.unsigned_path(signature, qualifying, NS), [NS, "SignatureTimeStamp", position],
+                [HankoXml::NS["ds"], "CanonicalizationMethod", nil]]
+        token = SignatureTimeStamper.new(self).token(HankoXml.serialize(doc), index, path)
+        encapsulated.content = [token].pack("m0")
+      end
+
+      def unique_id(doc, base)
+        taken = ->(id) { doc.at_xpath("//*[@Id=$id]", nil, id: id) }
+        return base unless taken.call(base)
+
+        (2..).each do |n|
+          candidate = "#{base}-#{n}"
+          return candidate unless taken.call(candidate)
+        end
+      end
+
+      def element(doc, name)
+        doc.create_element(name)
+      end
+
+      # The namespace is set once the node is in the tree, as
+      # QualifyingProperties#xades does, so no redundant declaration appears.
+      def attach(node, namespace)
+        node.namespace = namespace
+        node
+      end
+    end
+  end
+end

data/lib/hanko_xml/xades/locator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module HankoXml
+  module Xades
+    # Finds a signature's <xades:QualifyingProperties> and its unsigned
+    # containers along fixed paths from the <ds:Signature>, never by a search
+    # that a wrapped element elsewhere could satisfy (S-22). Xades::Verifier
+    # reads, and Xades::Augmenter writes, exactly the elements found here.
+    #
+    # @api private
+    module Locator
+      module_function
+
+      # This signature's single QualifyingProperties, in any XAdES namespace,
+      # and the namespaces to read it with.
+      def qualifying_properties(signature)
+        signature_id = signature["Id"].to_s
+        fail!("the <Signature> has no Id for QualifyingProperties to target") if signature_id.empty?
+
+        qualifying = signature.xpath("ds:Object/*[local-name()='QualifyingProperties']", "ds" => HankoXml::NS["ds"])
+                              .select { |node| NAMESPACES.include?(node.namespace&.href) }
+        fail!("a XAdES signature has exactly one <xades:QualifyingProperties>") unless qualifying.size == 1
+
+        qualifying = qualifying.first
+        fail!("<xades:QualifyingProperties> does not target this <Signature>") unless targets?(qualifying, signature_id)
+
+        [qualifying, { "ds" => HankoXml::NS["ds"], "xades" => qualifying.namespace.href }]
+      end
+
+      # Target is "#" + the Signature Id. The older namespaces also had
+      # signers write the bare Id (Target="Signature"). Either way the
+      # QualifyingProperties must sit in this <Signature>'s own <Object>.
+      def targets?(qualifying, signature_id)
+        target = qualifying["Target"]
+        return true if target == "##{signature_id}"
+
+        LEGACY_NAMESPACES.include?(qualifying.namespace.href) && target == signature_id
+      end
+
+      # The UnsignedSignatureProperties, or nil when there is none. More than
+      # one UnsignedProperties or UnsignedSignatureProperties is refused: which
+      # one a reader would pick is ambiguous.
+      def unsigned_signature_properties(qualifying, ns)
+        unsigned = qualifying.xpath("xades:UnsignedProperties", ns)
+        fail!("a XAdES signature has at most one <xades:UnsignedProperties>") if unsigned.size > 1
+        return nil if unsigned.empty?
+
+        properties = unsigned.first.xpath("xades:UnsignedSignatureProperties", ns)
+        fail!("a XAdES signature has at most one <xades:UnsignedSignatureProperties>") if properties.size > 1
+
+        properties.first
+      end
+
+      # The native path (Native.canonicalize) from the <ds:Signature> to its
+      # UnsignedSignatureProperties.
+      def unsigned_path(signature, qualifying, xades_ns)
+        object_index = signature.xpath("ds:Object", "ds" => HankoXml::NS["ds"]).index(qualifying.parent)
+        [[HankoXml::NS["ds"], "Object", object_index], [xades_ns, "QualifyingProperties", nil],
+         [xades_ns, "UnsignedProperties", nil], [xades_ns, "UnsignedSignatureProperties", nil]]
+      end
+
+      def fail!(message)
+        raise HankoXml::XadesError, message
+      end
+    end
+  end
+end