hanko_xml 0.1.0-x86_64-linux

data/lib/hanko_xml/policy.rb

@@ -0,0 +1,502 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module HankoXml
+  # A frozen allowlist, enforced in Ruby before anything reaches
+  # libxmlsec1, on both signing and verification. See API_CONTRACT.md §5.8.
+  class Policy # rubocop:disable Metrics/ClassLength
+    FIELDS = %i[
+      signature_methods digest_methods canonicalization_methods transforms
+      allow_external_references allow_retrieval_method allow_same_document_xpointer
+      max_references require_references
+      require_signed_root reject_duplicate_ids max_document_size max_transforms_per_reference
+      min_rsa_key_bits min_ec_key_bits min_dsa_key_bits allow_hmac check_certificate_validity clock_skew
+      require_signing_key_usage schema
+    ].freeze
+
+    STRICT_DEFAULTS = {
+      signature_methods: %i[rsa_sha256 rsa_sha384 rsa_sha512 ecdsa_sha256 ecdsa_sha384 ecdsa_sha512],
+      digest_methods: %i[sha256 sha384 sha512],
+      canonicalization_methods: %i[c14n exc_c14n c14n11 c14n_with_comments exc_c14n_with_comments],
+      transforms: %i[enveloped_signature base64 c14n exc_c14n c14n11 c14n_with_comments
+                     exc_c14n_with_comments],
+
+      allow_external_references: false,
+      allow_retrieval_method: false,
+      allow_same_document_xpointer: false,
+      max_references: 8,
+      require_references: true,
+
+      require_signed_root: true,
+      reject_duplicate_ids: true,
+      max_document_size: 16 * 1024 * 1024,
+      max_transforms_per_reference: 4,
+
+      min_rsa_key_bits: 2048,
+      min_ec_key_bits: 256,
+      min_dsa_key_bits: 2048,
+      allow_hmac: false,
+      check_certificate_validity: true,
+      clock_skew: 60,
+      # store: only -- the signing certificate's KeyUsage, when present, must
+      # allow digitalSignature or nonRepudiation (#63).
+      require_signing_key_usage: true,
+
+      schema: :default
+    }.freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**overrides)
+      unknown = overrides.keys - FIELDS
+      raise ArgumentError, "unknown Policy field(s): #{unknown.inspect}" unless unknown.empty?
+
+      values = STRICT_DEFAULTS.merge(overrides)
+      FIELDS.each { |f| instance_variable_set(:"@#{f}", values[f]) }
+      @allowed_uris = snapshot_allowed_uris
+      freeze
+    end
+
+    def with(**overrides)
+      self.class.new(**to_h.merge(overrides))
+    end
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = public_send(f) }
+    end
+
+    class << self
+      def strict
+        @strict ||= new
+      end
+
+      # strict, minus require_signed_root -- for protocols that sign a
+      # fragment (SAML assertions).
+      def fragment
+        @fragment ||= strict.with(require_signed_root: false)
+      end
+
+      # strict + SHA-1 digest and RSA-SHA1 signature.
+      def legacy_sha1
+        @legacy_sha1 ||= strict.with(
+          digest_methods: strict.digest_methods + [:sha1],
+          signature_methods: strict.signature_methods + [:rsa_sha1]
+        )
+      end
+
+      # strict + RSA-PSS (RFC 6931 MGF1) and SHA-3 digest / ECDSA-SHA3
+      # signature methods, the algorithms EU XAdES profiles often want (#60).
+      # Kept out of Policy.strict the same way SHA-1 is. xmlsec 1.3 (vendored
+      # / platform gems) implements them; xmlsec 1.2 (Ubuntu CI) does not —
+      # Native.sign/verify then fails closed.
+      def xades
+        @xades ||= strict.with(
+          # EU DSS's enveloped form, in the one shape Policy accepts (#85).
+          transforms: strict.transforms + [:xpath_filter2],
+          digest_methods: strict.digest_methods + %i[sha3_256 sha3_384 sha3_512],
+          signature_methods: strict.signature_methods + %i[
+            rsa_pss_sha256 rsa_pss_sha384 rsa_pss_sha512
+            ecdsa_sha3_256 ecdsa_sha3_384 ecdsa_sha3_512
+          ]
+        )
+      end
+
+      # fragment + what the W3C interop signatures (merlin-xmldsig-twenty-three,
+      # phaos-xmldsig-three) need: SHA-1 with RSA or DSA, and 1024-bit RSA and
+      # DSA keys.
+      # For verifying legacy signatures from other implementations (#62), never
+      # as a default. External references, RetrievalMethod, HMAC and
+      # XPath/XSLT stay off, as in strict.
+      def interop
+        @interop ||= fragment.with(
+          transforms: fragment.transforms + [:xpath_filter2],
+          digest_methods: fragment.digest_methods + [:sha1],
+          signature_methods: fragment.signature_methods + %i[rsa_sha1 dsa_sha1],
+          min_rsa_key_bits: 1024,
+          min_dsa_key_bits: 1024
+        )
+      end
+
+      # Allows everything the Ruby checks cover. Documented as unsafe. The
+      # native layer still refuses XPath and XSLT transforms (S-10) and reads
+      # an external URI only from referenced_documents: (#74), whatever this
+      # says. XPath Filter 2.0 still passes only in the subtract-the-signatures
+      # shape (#85).
+      def permissive
+        @permissive ||= new(
+          signature_methods: Algorithms.signature.names,
+          digest_methods: Algorithms.digest.names,
+          canonicalization_methods: Algorithms.canonicalization.names,
+          transforms: Algorithms.transform.names,
+          allow_external_references: true,
+          allow_retrieval_method: true,
+          allow_same_document_xpointer: true,
+          max_references: Float::INFINITY,
+          require_references: false,
+          require_signed_root: false,
+          reject_duplicate_ids: false,
+          max_document_size: Float::INFINITY,
+          max_transforms_per_reference: Float::INFINITY,
+          min_rsa_key_bits: 0,
+          min_ec_key_bits: 0,
+          min_dsa_key_bits: 0,
+          allow_hmac: true,
+          check_certificate_validity: false,
+          clock_skew: 0,
+          require_signing_key_usage: false,
+          schema: nil
+        )
+      end
+    end
+
+    # Validates +signature_info+ (a SignatureInfo) against this policy.
+    # Returns an Array<HankoXml::PolicyError>, empty when compliant. Never
+    # raises for a policy violation -- that is #enforce!'s job.
+    #
+    # +signature_info+ alone is enough for every algorithm/structural check
+    # (works without a DOM, per API_CONTRACT.md §6.1). The keyword
+    # arguments are optional context that only Signer/Verifier -- which
+    # always have a DOM and trust material -- can supply, for the handful
+    # of fields that genuinely need it (S-06):
+    #
+    # @param document [Nokogiri::XML::Document, nil] the document, when the
+    #   caller has only a DOM: it is serialized for the checks below.
+    # @param sig_node [Nokogiri::XML::Node, nil] internal (@api private):
+    #   accepted for compatibility; no check needs it any more (#102).
+    # @param id_attributes [Array<String>, nil] the caller's `id_attributes:`,
+    #   needed by +reject_duplicate_ids+ and +require_signed_root+.
+    # @param xml_bytes [String, nil] the document's bytes, for
+    #   +max_document_size+, +require_signed_root+ and +reject_duplicate_ids+.
+    #   Both structural checks read the native layer's parse of these bytes
+    #   (Native.scan), so they run identically with or without Nokogiri
+    #   (#102). Without +xml_bytes+ or +document+ an enabled check reports a
+    #   violation rather than being skipped (#96).
+    # @param check_root_signed [Boolean] internal (@api private), for
+    #   {Signer}: whether to apply
+    #   +require_signed_root+ here. `require_signed_root` (API_CONTRACT.md
+    #   §5.8.1) is a *verification*-time XSW defence -- it says nothing
+    #   about what is legitimate to produce, so {Signer} deliberately signs
+    #   a caller-chosen fragment (opted into via `references:`, R5) without
+    #   tripping it; only {Verifier} checks it.
+    # @param referenced_uris [Array<String>] internal (@api private), for
+    #   {Verifier}: URIs the caller serves through
+    #   `referenced_documents:` (#74). An external reference to one of them
+    #   is allowed whatever +allow_external_references+ says: it is read from
+    #   the caller's map, never fetched.
+    #
+    # +min_rsa_key_bits+ / +min_ec_key_bits+ are not checked here -- they
+    # need the actual signing/trust key material, which is only available
+    # once Signer/Verifier have resolved it. See #enforce_key_size!.
+    # sig_node: stays in the signature for callers that pass it (#102).
+    def violations(signature_info, document: nil, sig_node: nil, id_attributes: nil, xml_bytes: nil, # rubocop:disable Lint/UnusedMethodArgument
+                   check_root_signed: true, referenced_uris: [])
+      errors = []
+
+      errors << algorithm_violation(:signature, signature_info.signature_method)
+      errors << algorithm_violation(:canonicalization, signature_info.canonicalization_method)
+      errors << hmac_violation(signature_info)
+      errors << retrieval_method_violation(signature_info)
+
+      if require_references && signature_info.references.empty?
+        errors << HankoXml::PolicyError.new(
+          "this policy requires at least one <Reference>, but <SignedInfo> has none " \
+          "(require_references)"
+        )
+      end
+
+      if signature_info.references.size > max_references
+        errors << HankoXml::PolicyError.new(
+          "<SignedInfo> has #{signature_info.references.size} references, more than this " \
+          "policy's max_references (#{max_references})"
+        )
+      end
+
+      errors.concat(reference_violations(signature_info.references, referenced_uris))
+
+      # The structural checks parse the document natively, so an oversized
+      # one is reported and never parsed (S-12). A DOM is measured by its
+      # serialized bytes, as Signer and Verifier measure it.
+      xml_bytes ||= HankoXml.serialize(document) if document
+      size_error = document_size_violation(xml_bytes&.bytesize)
+      if size_error
+        errors << size_error
+      else
+        structure = DocumentStructure.new(xml_bytes, id_attributes)
+        errors << root_signed_violation(structure, signature_info) if check_root_signed
+        errors << duplicate_id_violation(structure)
+      end
+
+      errors.compact
+    end
+
+    # Raises HankoXml::PolicyError (with all violations joined into the
+    # message) if +signature_info+ violates this policy. Accepts the same
+    # optional context keywords as #violations.
+    def enforce!(signature_info, document: nil, sig_node: nil, id_attributes: nil, xml_bytes: nil,
+                 check_root_signed: true, referenced_uris: [])
+      errors = violations(signature_info, document: document, sig_node: sig_node, id_attributes: id_attributes,
+                                          xml_bytes: xml_bytes, check_root_signed: check_root_signed,
+                                          referenced_uris: referenced_uris)
+      return if errors.empty?
+
+      raise HankoXml::PolicyError, errors.map(&:message).join("; ")
+    end
+
+    # Raises HankoXml::PolicyError if +bytesize+ exceeds
+    # +max_document_size+. Separate from #enforce! so Signer/Verifier can
+    # apply it before parsing and before any native call -- #enforce! needs
+    # Native.inspect_sig output, which already means a native parse (S-12).
+    # Raises HankoXml::PolicyError unless +uri_or_name+ is in this policy's
+    # allowlist for +slot+ (:signature, :digest, :canonicalization,
+    # :transform). For algorithms named outside <SignedInfo>, such as a XAdES
+    # certificate digest.
+    # Whether +uri_or_name+ is in this policy's allowlist for +slot+.
+    def allows?(slot, uri_or_name)
+      algorithm_violation(slot, uri_or_name).nil?
+    end
+
+    def enforce_algorithm!(slot, uri_or_name)
+      error = algorithm_violation(slot, uri_or_name)
+      raise error if error
+    end
+
+    def enforce_document_size!(bytesize)
+      error = document_size_violation(bytesize)
+      raise error if error
+    end
+
+    # Raises HankoXml::PolicyError if any of +keys+
+    # (OpenSSL::PKey::PKey / OpenSSL::X509::Certificate) is smaller than
+    # this policy's min_rsa_key_bits / min_ec_key_bits / min_dsa_key_bits (S-06). Separate from
+    # #enforce! because the real signing/trust key is only known once
+    # Signer/Verifier have resolved it (Signer's own key; Verifier's
+    # resolved trust material) -- after SignatureInfo has already been
+    # policy-checked.
+    def enforce_key_size!(keys)
+      errors = Array(keys).filter_map { |key| key_size_violation(key) }
+      return if errors.empty?
+
+      raise HankoXml::PolicyError, errors.map(&:message).join("; ")
+    end
+
+    private
+
+    def reference_violations(references, referenced_uris)
+      references.flat_map do |ref|
+        errors = [
+          algorithm_violation(:digest, ref.digest_method, reference_uri: ref.uri)
+        ]
+
+        if ref.transforms.size > max_transforms_per_reference
+          errors << HankoXml::PolicyError.new(
+            "reference #{ref.uri.inspect} has #{ref.transforms.size} transforms, more than this " \
+            "policy's max_transforms_per_reference (#{max_transforms_per_reference})"
+          )
+        end
+
+        ref.transforms.each do |transform_uri|
+          errors << algorithm_violation(:transform, transform_uri, reference_uri: ref.uri)
+        end
+        errors << xpath_filter2_violation(ref)
+
+        if !allow_external_references && ref.external? && !referenced_uris.include?(ref.document_uri)
+          errors << HankoXml::PolicyError.new(
+            "reference URI #{ref.uri.inspect} is external, and allow_external_references is false"
+          )
+        end
+
+        if !allow_same_document_xpointer && ref.same_document_xpointer?
+          errors << HankoXml::PolicyError.new(
+            "reference URI #{ref.uri.inspect} is a same-document XPointer, and " \
+            "allow_same_document_xpointer is false"
+          )
+        end
+
+        errors
+      end
+    end
+
+    # An allowed XPath Filter 2.0 transform must be the standard enveloped
+    # form, "the whole document minus the signatures" (#85): arbitrary
+    # filters can select a node set #signed? does not model (signature
+    # wrapping), and are a denial-of-service vector (S-10). xmlsec evaluates
+    # the accepted shape; nothing here evaluates XPath.
+    def xpath_filter2_violation(ref)
+      return nil unless ref.xpath_filter2? && allows?(:transform, :xpath_filter2)
+      return nil if ref.signature_exclusion
+
+      expressions = ref.xpath_filters.map { |f| f.transform_keys(&:to_sym).values_at(:filter, :expression).join(" ") }
+      found = expressions.empty? ? "no filter <XPath>" : expressions.join("; ").inspect
+      HankoXml::PolicyError.new(
+        "reference #{ref.uri.inspect} has an XPath Filter 2.0 transform other than a single subtract of " \
+        "/descendant::ds:Signature or /*/ds:Signature on the whole document (#{found})"
+      )
+    end
+
+    def hmac_violation(signature_info)
+      return nil if allow_hmac
+
+      name = Algorithms.name_for(:signature, signature_info.signature_method)
+      return nil unless name.to_s.start_with?("hmac")
+
+      HankoXml::PolicyError.new(
+        "signature method #{signature_info.signature_method} (#{name.inspect}) is HMAC-based, " \
+        "and allow_hmac is false"
+      )
+    end
+
+    def retrieval_method_violation(signature_info)
+      return nil if allow_retrieval_method
+      return nil unless signature_info.retrieval_method?
+
+      HankoXml::PolicyError.new(
+        "<KeyInfo> contains a <RetrievalMethod>, and allow_retrieval_method is false"
+      )
+    end
+
+    # The document facts +require_signed_root+ and +reject_duplicate_ids+
+    # need, from the native layer's parse of the same bytes xmlsec verifies
+    # (Native.scan). Scanned at most once, and only when a check asks.
+    class DocumentStructure
+      def initialize(xml_bytes, id_attributes)
+        @xml_bytes = xml_bytes
+        @id_attributes = id_attributes
+      end
+
+      def available?
+        !@xml_bytes.nil?
+      end
+
+      def id_attributes?
+        !@id_attributes.nil?
+      end
+
+      def id_names
+        (@id_attributes || []).map { |attr| attr.is_a?(Array) ? attr[1].to_s : attr.to_s }
+      end
+
+      def scan
+        @scan ||= Native.scan(@xml_bytes.b, id_names, false)
+      end
+    end
+    private_constant :DocumentStructure
+
+    def missing_context_violation(field)
+      HankoXml::PolicyError.new(
+        "#{field} needs the document to check; pass xml_bytes: (or document:) and id_attributes:, " \
+        "or use a policy with #{field}: false"
+      )
+    end
+
+    # Structural check: does any Reference cover the document root? An empty
+    # URI or `#xpointer(/)` is the whole document (#85); a bare `#id` covers the root when xmlsec's
+    # ID table resolves it to the root element (Native.scan's root_ids).
+    # Runs before any cryptography, and does not wait for a real
+    # Verification#covers_root? (S-06).
+    def root_signed_violation(structure, signature_info)
+      return nil unless require_signed_root
+      # Without the document this cannot be checked, and an unchecked
+      # structural rule must fail closed, not pass (#96).
+      return missing_context_violation(:require_signed_root) unless structure.available?
+
+      return nil if signature_info.references.any? { |ref| SignatureInfo::WHOLE_DOCUMENT_URIS.include?(ref.uri.to_s) }
+
+      root_ids = structure.id_attributes? ? structure.scan[:root_ids] : []
+      return nil if signature_info.references.any? { |ref| ref.fragment? && root_ids.include?(ref.uri[1..]) }
+
+      HankoXml::PolicyError.new(
+        "this policy requires the root element to be signed (require_signed_root), but no " \
+        "<Reference> covers it"
+      )
+    end
+
+    # Whole-document duplicate-ID scan (S-06), as coarse as xmlSecAddIDs
+    # (S-03): any attribute whose local name is an ID attribute counts,
+    # whatever its namespace, because xmlsec registers all of them.
+    def duplicate_id_violation(structure)
+      return nil unless reject_duplicate_ids
+      return missing_context_violation(:reject_duplicate_ids) unless structure.available? && structure.id_attributes?
+      return nil if structure.id_names.empty?
+      return nil unless structure.scan[:duplicate_ids]
+
+      HankoXml::PolicyError.new(
+        "document has more than one element with the same ID attribute value, and " \
+        "reject_duplicate_ids is true"
+      )
+    end
+
+    def document_size_violation(bytesize)
+      return nil if bytesize.nil?
+      return nil if bytesize <= max_document_size
+
+      HankoXml::PolicyError.new(
+        "document is #{bytesize} bytes, more than this policy's max_document_size " \
+        "(#{max_document_size})"
+      )
+    end
+
+    def key_size_violation(key)
+      kind, bits = key_bits(key)
+      return nil if kind.nil?
+
+      field = :"min_#{kind}_key_bits"
+      minimum = public_send(field)
+      return nil if bits >= minimum
+
+      HankoXml::PolicyError.new("#{kind} key is #{bits} bits, less than this policy's #{field} (#{minimum})")
+    end
+
+    def key_bits(key)
+      public_key = key.is_a?(::OpenSSL::X509::Certificate) ? key.public_key : key
+      case public_key
+      when ::OpenSSL::PKey::RSA
+        [:rsa, public_key.n.num_bits]
+      when ::OpenSSL::PKey::EC
+        [:ec, public_key.group.degree]
+      when ::OpenSSL::PKey::DSA
+        [:dsa, public_key.p.num_bits]
+      else
+        [nil, nil]
+      end
+    end
+
+    ALGORITHM_FIELDS = {
+      signature: :signature_methods,
+      digest: :digest_methods,
+      canonicalization: :canonicalization_methods,
+      transform: :transforms
+    }.freeze
+    private_constant :ALGORITHM_FIELDS
+
+    # The allowlists resolved to URIs once, at construction (S-16), so a
+    # later Algorithms.register cannot change what an existing Policy --
+    # Policy.strict included -- accepts.
+    def snapshot_allowed_uris
+      ALGORITHM_FIELDS.to_h do |slot, field|
+        uris = Array(public_send(field)).filter_map { |entry| Algorithms.uri_for(slot, entry) }
+        [slot, uris.to_h { |uri| [uri, true] }.freeze]
+      end.freeze
+    end
+
+    def algorithm_violation(slot, uri_or_name, reference_uri: nil)
+      return nil if uri_or_name.nil?
+
+      field_name = ALGORITHM_FIELDS.fetch(slot)
+
+      # A String from the document is compared verbatim: resolving it through
+      # the registry would let Algorithm="sha256" stand in for the real URI.
+      candidate = uri_or_name.is_a?(String) ? uri_or_name : Algorithms.uri_for(slot, uri_or_name)
+      return nil if @allowed_uris.fetch(slot).key?(candidate)
+
+      name = Algorithms.name_for(slot, uri_or_name)
+      location = reference_uri ? " on reference #{reference_uri.inspect}" : ""
+
+      HankoXml::PolicyError.new(
+        "#{slot} method #{uri_or_name}#{name ? " (#{name.inspect})" : ""}#{location} is not in " \
+        "this policy's #{field_name}. Use a preset such as HankoXml::Policy.legacy_sha1, " \
+        "HankoXml::Policy.xades or Policy#with(#{field_name}: …) if this document genuinely requires it."
+      )
+    end
+  end
+end

data/lib/hanko_xml/reference.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # A single <ds:Reference> a Signer will emit. Frozen value object. See
+  # API_CONTRACT.md §5.2.
+  class Reference
+    attr_reader :uri, :transforms, :digest_method, :id, :type
+
+    # +uri+: "" for the whole document (enveloped), "#id" for a fragment,
+    #   or nil to default to "" when this is the only/default reference.
+    # +transforms+: Array of Transform / Symbol / String, in order.
+    # +digest_method+: Symbol or URI String, defaults to :sha256.
+    def initialize(uri: "", transforms: [:enveloped_signature], digest_method: :sha256, id: nil, type: nil)
+      @uri = uri.nil? ? "" : uri.to_s
+      @transforms = Array(transforms).map { |t| Transform.coerce(t) }
+      @digest_method = digest_method
+      @id = id
+      @type = type
+      freeze
+    end
+
+    def digest_method_uri
+      Algorithms.uri_for(:digest, digest_method)
+    end
+
+    def enveloped?
+      transforms.any?(&:enveloped_signature?)
+    end
+
+    def fragment?
+      uri.start_with?("#")
+    end
+
+    def target_id
+      fragment? ? uri.sub(/\A#/, "") : nil
+    end
+
+    def self.coerce(value)
+      case value
+      when Reference then value
+      when String then new(uri: value)
+      when Hash then new(**value)
+      else
+        raise ArgumentError, "expected a HankoXml::Reference, URI String, or Hash of Reference " \
+                              "keywords, got #{value.class}"
+      end
+    end
+  end
+end

data/lib/hanko_xml/signature_info.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # DOM-free, unauthenticated view of a <ds:Signature>'s <SignedInfo> --
+  # exactly the shape HankoXml::Native.inspect returns (§7 of
+  # API_CONTRACT.md), and nothing more. Policy is checked against this, not
+  # against Nokogiri nodes, so Policy enforcement works identically whether
+  # or not Nokogiri is loaded (§6.1).
+  #
+  # Everything here is "what the document claims" -- it runs before any
+  # cryptography, and is not proof of anything until a Verification says so.
+  #
+  # The library builds these; callers only read them, through
+  # Verification#signed_info / #signature_info. The constructors are not
+  # part of the public API.
+  class SignatureInfo
+    XPATH_FILTER2 = "http://www.w3.org/2002/06/xmldsig-filter2"
+    # The whole document: without comments (""), and with them ("#xpointer(/)",
+    # which allow_same_document_xpointer still governs).
+    WHOLE_DOCUMENT_URIS = ["", "#xpointer(/)"].freeze
+    DSIG_NS = "http://www.w3.org/2000/09/xmldsig#"
+
+    ReferenceInfo = Struct.new(:uri, :digest_method, :transforms, :id, :type, :xpath_filters, keyword_init: true) do
+      def initialize(uri:, digest_method:, transforms: [], id: nil, type: nil, xpath_filters: [])
+        super
+      end
+
+      # Which <ds:Signature> elements an XPath Filter 2.0 transform takes out
+      # of this Reference, for the one shape HankoXml accepts (#85): a
+      # whole-document reference (WHOLE_DOCUMENT_URIS) whose first transform is a single `subtract` of
+      # `/descendant::P:Signature` (every signature, :all) or `/*/P:Signature`
+      # (the root's signature children, :root_children), with P bound to the
+      # XML-DSig namespace on the <XPath> element. nil for anything else, which
+      # Policy refuses. The expression is matched token for token (XPath
+      # allows whitespace between tokens), never by its prefix's spelling:
+      # `name()='ds:Signature'` would match any namespace bound to `ds`.
+      def signature_exclusion
+        return nil unless WHOLE_DOCUMENT_URIS.include?(uri.to_s) && transforms.first == XPATH_FILTER2
+        return nil unless transforms.count(XPATH_FILTER2) == 1 && xpath_filters.size == 1
+
+        filter = xpath_filters.first.transform_keys(&:to_sym)
+        return nil unless filter[:filter] == "subtract"
+
+        match = filter[:expression].to_s.gsub(/\s+/, "").match(%r{\A/(descendant::|\*/)([A-Za-z_][\w.-]*):Signature\z})
+        return nil unless match && filter[:namespaces].to_h[match[2]] == DSIG_NS
+
+        match[1] == "descendant::" ? :all : :root_children
+      end
+
+      def xpath_filter2?
+        transforms.include?(XPATH_FILTER2)
+      end
+
+      def digest_method_name
+        Algorithms.name_for(:digest, digest_method)
+      end
+
+      def transform_names
+        transforms.map { |uri| Algorithms.name_for(:transform, uri) }
+      end
+
+      def fragment?
+        uri.to_s.start_with?("#")
+      end
+
+      def external?
+        !(uri.to_s.empty? || fragment?)
+      end
+
+      # The URI xmlsec reads an external reference from: everything before
+      # any `#` fragment.
+      def document_uri
+        uri.to_s.split("#", 2).first.to_s
+      end
+
+      # Same-document XPointer, e.g. `#xpointer(/)` or `#xpointer(id('x'))` --
+      # not a bare `#id` fragment (S-06, `allow_same_document_xpointer`).
+      def same_document_xpointer?
+        fragment? && uri[1..].to_s.include?("(")
+      end
+    end
+
+    attr_reader :signature_method, :canonicalization_method, :signature_count,
+                :key_names, :certificates, :references
+
+    # @api private
+    def initialize(signature_method:, canonicalization_method:, references:,
+                   signature_count: 1, key_names: [], certificates: [], has_retrieval_method: false)
+      @signature_method = signature_method
+      @canonicalization_method = canonicalization_method
+      @signature_count = signature_count
+      @key_names = key_names.freeze
+      @certificates = certificates.freeze
+      @references = references.map { |r| r.is_a?(ReferenceInfo) ? r : ReferenceInfo.new(**r) }.freeze
+      @has_retrieval_method = has_retrieval_method
+      freeze
+    end
+
+    # Whether `<KeyInfo>` contains a `<RetrievalMethod>` (S-06,
+    # `allow_retrieval_method`).
+    def retrieval_method?
+      @has_retrieval_method
+    end
+
+    def signature_method_name
+      Algorithms.name_for(:signature, signature_method)
+    end
+
+    def canonicalization_method_name
+      Algorithms.name_for(:canonicalization, canonicalization_method)
+    end
+
+    # Builds a SignatureInfo from the native Native.inspect Hash shape
+    # (String keys/URIs throughout).
+    #
+    # @api private
+    def self.from_native(hash)
+      new(
+        signature_method: fetch(hash, :signature_method),
+        canonicalization_method: fetch(hash, :canonicalization_method),
+        signature_count: fetch(hash, :signature_count) || 1,
+        key_names: fetch(hash, :key_names) || [],
+        certificates: fetch(hash, :certificates) || [],
+        references: fetch(hash, :references) || [],
+        has_retrieval_method: fetch(hash, :has_retrieval_method) || false
+      )
+    end
+
+    def self.fetch(hash, key)
+      hash[key] || hash[key.to_s]
+    end
+    private_class_method :fetch
+  end
+end