hanko_xml 0.1.0-x86_64-linux

data/lib/hanko_xml/template.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # Builds the unsigned <ds:Signature> Nokogiri tree for a Signer's
+  # configuration -- DigestValue/SignatureValue/certificate leaves are left
+  # empty for the native layer (Phase 2+) to fill in. See API_CONTRACT.md
+  # §5.2, §6.4.
+  #
+  # Needs a DOM: this is the one thing that cannot be built DOM-free,
+  # because doing it by string concatenation would put attacker-influenced
+  # values into hand-assembled markup (§6.1).
+  class Template
+    def self.build(doc, config)
+      new(doc, config).build
+    end
+
+    def initialize(doc, config)
+      Dom.require!("HankoXml::Template")
+
+      @doc = doc
+      @config = config
+    end
+
+    def build
+      signature = element("Signature")
+      signature.default_namespace = HankoXml::NS["ds"]
+      signature["Id"] = @config.signature_id.to_s if @config.signature_id
+
+      signature.add_child(build_signed_info)
+      signature.add_child(element("SignatureValue"))
+
+      key_info = build_key_info
+      signature.add_child(key_info) if key_info
+
+      signature
+    end
+
+    private
+
+    def build_signed_info
+      signed_info = element("SignedInfo")
+
+      c14n = element("CanonicalizationMethod")
+      c14n["Algorithm"] = Algorithms.uri_for(:canonicalization, @config.canonicalization_method)
+      signed_info.add_child(c14n)
+
+      signature_method = element("SignatureMethod")
+      signature_method["Algorithm"] = Algorithms.uri_for(:signature, @config.signature_method)
+      signed_info.add_child(signature_method)
+
+      effective_references.each { |ref| signed_info.add_child(build_reference(ref)) }
+
+      signed_info
+    end
+
+    def effective_references
+      refs = @config.references
+      refs = [Reference.new(uri: "", digest_method: @config.digest_method)] if refs.empty?
+      refs
+    end
+
+    def build_reference(ref)
+      reference = element("Reference")
+      reference["URI"] = ref.uri
+      reference["Id"] = ref.id.to_s if ref.id
+      reference["Type"] = ref.type.to_s if ref.type
+
+      unless ref.transforms.empty?
+        transforms = element("Transforms")
+        ref.transforms.each { |t| transforms.add_child(build_transform(t)) }
+        reference.add_child(transforms)
+      end
+
+      digest_method = element("DigestMethod")
+      digest_method["Algorithm"] = ref.digest_method_uri
+      reference.add_child(digest_method)
+
+      reference.add_child(element("DigestValue"))
+
+      reference
+    end
+
+    def build_transform(transform)
+      node = element("Transform")
+      node["Algorithm"] = transform.uri
+
+      if transform.xpath
+        xpath_node = element("XPath")
+        xpath_node.content = transform.xpath
+        node.add_child(xpath_node)
+      end
+
+      prefixes = transform.inclusive_prefixes
+      node.add_child(build_inclusive_namespaces(prefixes)) unless prefixes.empty?
+
+      node
+    end
+
+    def build_inclusive_namespaces(prefixes)
+      node = element("InclusiveNamespaces")
+      node.namespace = node.add_namespace_definition("ec", Transform::EXC_C14N_NS)
+      node["PrefixList"] = prefixes.join(" ")
+      node
+    end
+
+    X509_CHILDREN = {
+      x509_certificate: "X509Certificate",
+      x509_subject_name: "X509SubjectName",
+      x509_issuer_serial: "X509IssuerSerial",
+      x509_ski: "X509SKI"
+    }.freeze
+    private_constant :X509_CHILDREN
+
+    def build_key_info
+      clauses = @config.key_info
+      return nil if clauses.empty?
+
+      key_info = element("KeyInfo")
+
+      x509_children = clauses.filter_map { |c| X509_CHILDREN[c.name] }.uniq
+      unless x509_children.empty?
+        # xmlsec writes only the X509Data children the template names (an
+        # empty <X509Data/> means "certificate"), so each clause needs its
+        # own placeholder (#52 E8).
+        x509_data = element("X509Data")
+        x509_children.each { |name| x509_data.add_child(element(name)) }
+        key_info.add_child(x509_data)
+      end
+
+      clauses.each do |c|
+        case c.name
+        when :key_name
+          # xmlsec writes the xmlSecKey's own name, and a key loaded from
+          # PEM has none, so the name comes from the clause (#67).
+          key_name = element("KeyName")
+          key_name.content = c.value if c.value
+          key_info.add_child(key_name)
+        when :key_value
+          key_info.add_child(element("KeyValue"))
+        end
+      end
+
+      key_info
+    end
+
+    def element(name)
+      @doc.create_element(name)
+    end
+  end
+end

data/lib/hanko_xml/transform.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # A single <ds:Transform>, resolved to a URI at construction. Frozen value
+  # object. See API_CONTRACT.md §5.2, §5.7.
+  class Transform
+    EXC_C14N_NS = "http://www.w3.org/2001/10/xml-exc-c14n#"
+    EXCLUSIVE = %i[exc_c14n exc_c14n_with_comments].freeze
+    # An NCName, or the "#default" token for the default namespace
+    # (Exclusive XML Canonicalization §3).
+    PREFIX = /\A(?:#default|[A-Za-z_][A-Za-z0-9_.-]*)\z/
+
+    attr_reader :name, :uri, :xpath, :inclusive_prefixes
+
+    # +algorithm+ is a Symbol looked up in Algorithms.transform, or a String
+    # URI used verbatim. +xpath+ is required for :xpath / :xpath_filter2
+    # transforms and carried through as the transform's textual content.
+    # +inclusive_prefixes+ (exclusive c14n only) becomes an
+    # <ec:InclusiveNamespaces PrefixList="..."/> child: namespace prefixes
+    # canonicalized as in inclusive c14n, e.g. %w[xs] for SAML xsi:type values.
+    def initialize(algorithm, xpath: nil, inclusive_prefixes: [])
+      @name = algorithm.is_a?(Symbol) ? algorithm : Algorithms.name_for(:transform, algorithm)
+      @uri = Algorithms.uri_for(:transform, algorithm)
+
+      raise HankoXml::ConfigurationError, "unknown transform #{algorithm.inspect}" if @uri.nil?
+
+      @xpath = xpath
+      @inclusive_prefixes = coerce_inclusive_prefixes(inclusive_prefixes)
+      freeze
+    end
+
+    # Exclusive c14n, optionally with an InclusiveNamespaces PrefixList.
+    def self.exc_c14n(inclusive_prefixes: [], with_comments: false)
+      new(with_comments ? :exc_c14n_with_comments : :exc_c14n, inclusive_prefixes: inclusive_prefixes)
+    end
+
+    def self.c14n
+      new(:c14n)
+    end
+
+    def self.enveloped_signature
+      new(:enveloped_signature)
+    end
+
+    def enveloped_signature?
+      name == :enveloped_signature
+    end
+
+    def secure?
+      Algorithms.secure?(:transform, uri)
+    end
+
+    def self.coerce(value)
+      value.is_a?(Transform) ? value : new(value)
+    end
+
+    def ==(other)
+      other.is_a?(Transform) && other.uri == uri && other.xpath == xpath &&
+        other.inclusive_prefixes == inclusive_prefixes
+    end
+    alias eql? ==
+
+    def hash
+      [uri, xpath, inclusive_prefixes].hash
+    end
+
+    private
+
+    def coerce_inclusive_prefixes(prefixes)
+      prefixes = Array(prefixes).map(&:to_s)
+      return prefixes.freeze if prefixes.empty?
+
+      unless EXCLUSIVE.include?(name)
+        raise HankoXml::ConfigurationError,
+              "inclusive_prefixes: applies only to exclusive c14n transforms, not #{uri}"
+      end
+
+      invalid = prefixes.grep_v(PREFIX)
+      unless invalid.empty?
+        raise HankoXml::ConfigurationError,
+              "inclusive_prefixes: #{invalid.inspect} are not namespace prefixes (NCName or \"#default\")"
+      end
+
+      prefixes.uniq.freeze
+    end
+  end
+end

data/lib/hanko_xml/verification.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # The result of a signature verification attempt.
+  # Provides methods to inspect which nodes were actually signed, defending against
+  # XML Signature Wrapping (XSW) attacks.
+  # See API_CONTRACT.md §5.4.
+  class Verification # rubocop:disable Metrics/ClassLength
+    # Details about a specific `<Reference>` inside the verified signature.
+    Reference = Struct.new(:uri, :node, :digest_method, :transforms, :valid?, :errors, :signature_exclusion,
+                           keyword_init: true) do
+      # @return [Boolean] True if the reference uses the enveloped-signature transform.
+      def enveloped?
+        transforms.include?(:enveloped_signature)
+      end
+
+      # Which <ds:Signature> subtrees this Reference leaves out: :this (the
+      # enveloped-signature transform), and for the accepted XPath Filter 2.0
+      # form (#85) :all (every signature) or :root_children (signatures that
+      # are children of the root).
+      def signature_exclusions
+        [(:this if enveloped?), signature_exclusion].compact
+      end
+    end
+
+    attr_reader :valid, :errors, :signature_info, :signature_node, :document, :certificate, :id_attributes, :resolver,
+                :references, :reference_element_indexes, :reference_valid, :namespaces,
+                :signature_element_index
+
+    # +document+ is nil when the input was bytes and Nokogiri is not loaded
+    # (#102). Everything that needs no DOM still works then; #signed?,
+    # #signed_nodes, #at_signed and #signed raise NokogiriRequired.
+    def initialize(valid:, errors:, signature_info:, signature_node:, document:, certificate: nil,
+                   id_attributes: %w[Id ID id], resolver: nil, reference_element_indexes: nil,
+                   reference_valid: nil, namespaces: {}, signature_element_index: nil, certificate_chain: nil,
+                   trusted: true, root_signature: nil)
+      @valid = valid
+      @errors = errors.dup
+      @signature_info = signature_info
+      @signature_node = signature_node
+      @document = document
+      @certificate = certificate
+      # The chain store: validated, leaf first; nil for the pinned trust sources.
+      @certificate_chain = certificate_chain&.dup&.freeze
+      # False only for Verifier.without_trust_verification (#103).
+      @trusted = trusted
+      # Whether the root element is a <ds:Signature>, for #covers_root?
+      # without a DOM; nil falls back to this signature being the root.
+      @root_signature = root_signature
+      @id_attributes = (id_attributes || []).dup.freeze
+      @resolver = resolver
+      @namespaces = (namespaces || {}).transform_keys(&:to_s).freeze
+      # Native.verify returns document-order element indexes from libxml2's ID
+      # table (the same table xmlsec used for `#id`). When present, those are
+      # authoritative for #references[].node / #signed? — Ruby does not
+      # re-resolve IDs (issues #28 / #34 / S-03).
+      @reference_element_indexes = reference_element_indexes&.dup&.freeze
+      # Native.verify's per-Reference digest status (S-09) -- authoritative
+      # when present. See #reference_valid_for.
+      @reference_valid = reference_valid&.dup&.freeze
+      # The <Signature>'s own document-order element index, in the same
+      # numbering, so #covers_root? can apply the enveloped exclusion without
+      # a DOM.
+      @signature_element_index = signature_element_index
+      # Resolution must happen, and #errors/#valid must be able to react to it
+      # (see detect_resolution_mismatches!), before we freeze below -- the object
+      # is immutable from here on, so #references can't be computed lazily on
+      # first access the way it used to be.
+      @references = build_references
+      detect_resolution_mismatches!
+      @errors.freeze
+      freeze
+    end
+
+    # @return [Boolean] True if the signature is completely valid.
+    def valid?
+      @valid
+    end
+
+    # --- Authenticated metadata ---
+    # Registry names (:rsa_sha256), as API_CONTRACT.md §5.4 shows, or the URI
+    # String for an algorithm the registry does not know (#96).
+    def signature_method
+      signature_info && (signature_info.signature_method_name || signature_info.signature_method)
+    end
+
+    def canonicalization_method
+      signature_info && (signature_info.canonicalization_method_name || signature_info.canonicalization_method)
+    end
+
+    def digest_methods
+      # nil signature_info: a verification that failed before inspection (#94).
+      return [] unless signature_info
+
+      signature_info.references.map { |ref| ref.digest_method_name || ref.digest_method }
+    end
+
+    def signed_nodes
+      require_document!("Verification#signed_nodes")
+      # Same rule as #signed?: nothing is covered unless the signature held (#91).
+      return [] unless valid?
+
+      # For each reference, get the nodes it covers
+      nodes = []
+      references.each do |ref|
+        next unless ref.node
+
+        # A reference covers the node and all its descendants.
+        # But if it's enveloped, it excludes the signature itself.
+        nodes << ref.node
+      end
+      nodes
+    end
+
+    def signed?(node)
+      require_document!("Verification#signed?")
+      return false unless valid?
+
+      # True if the node is equal to or a descendant of any reference's target
+      # node, EXCEPT inside a <ds:Signature> the reference leaves out: this
+      # one (enveloped-signature), or the ones an XPath Filter 2.0 subtract
+      # removes (#85).
+      references.any? do |ref|
+        next false unless ref.node
+        next false unless node.ancestors.include?(ref.node) || node == ref.node
+
+        ref.signature_exclusions.none? { |exclusion| excluded_by?(node, exclusion) }
+      end
+    end
+
+    # Whether the signature held AND the key came from trust material the
+    # caller supplied. False for every result of
+    # Verifier.without_trust_verification, which checks integrity only: its
+    # #valid? says the document was not changed, never who signed it (#103).
+    def trusted?
+      valid? && @trusted
+    end
+
+    # The <SignedInfo> that was verified: #signature_info once the signature
+    # held, nil otherwise, so it never stands for unauthenticated claims
+    # (#104). #signature_info is the same data before verification.
+    def signed_info
+      valid? ? signature_info : nil
+    end
+
+    # The certificates that established trust, leaf first, or [] unless
+    # trusted?. For store: it is the chain OpenSSL validated, up to the trust
+    # anchor; for certificate: / certificates: it is the pinned certificate;
+    # key: and keys: with a bare public key have none (#104).
+    def certificate_chain
+      return [] unless trusted?
+      return @certificate_chain if @certificate_chain
+
+      certificate ? [certificate] : []
+    end
+
+    # What the document's <KeyInfo> claimed, read out but never trusted: the
+    # Verifier pins its key from trust material and ignores <KeyInfo> (S-01).
+    # Available whether or not the signature held; nil when <SignedInfo> was
+    # never read (#104).
+    def key_info
+      return nil unless signature_info
+
+      KeyInfo::Parsed.new(key_names: signature_info.key_names, certificates: signature_info.certificates)
+    end
+
+    # Whether a Reference covers the root element. With a DOM this is
+    # #signed?(document.root); without one, the same rule over the native
+    # element indexes, where the root is index 0 (#102).
+    def covers_root?
+      return signed?(document.root) if document
+      return false unless valid? && reference_element_indexes
+
+      references.each_with_index.any? do |ref, index|
+        next false unless reference_element_indexes[index]&.zero?
+
+        # Only a <Signature> that is itself the root can take the root out:
+        # :this when it is this one, :all when it is any (#85).
+        exclusions = ref.signature_exclusions
+        !((exclusions.include?(:this) && signature_element_index&.zero?) ||
+          (exclusions.include?(:all) && root_signature))
+      end
+    end
+
+    def root_signature
+      @root_signature.nil? ? signature_element_index&.zero? : @root_signature
+    end
+    private :root_signature
+
+    def partial?
+      !covers_root?
+    end
+
+    # +ns+ is merged over the Verifier's +namespaces:+, which is merged over
+    # HankoXml::NS, so +ds:+ is always bound (#96).
+    def at_signed(xpath, ns = {})
+      require_document!("Verification#at_signed")
+      node = document.at_xpath(xpath, xpath_namespaces(ns))
+      raise HankoXml::NotSignedError, "No node found" unless node
+      raise HankoXml::NotSignedError, "Node is not signed" unless signed?(node)
+
+      node
+    end
+
+    def signed(xpath, ns = {})
+      require_document!("Verification#signed")
+      nodes = document.xpath(xpath, xpath_namespaces(ns)).to_a
+      raise HankoXml::NotSignedError, "Some nodes are not signed" unless nodes.all? { |n| signed?(n) }
+
+      nodes
+    end
+
+    private
+
+    def excluded_by?(node, exclusion)
+      chain = [node, *node.ancestors]
+      case exclusion
+      when :this then chain.include?(signature_node)
+      when :all then chain.any? { |n| dsig_signature?(n) }
+      when :root_children then chain.any? { |n| dsig_signature?(n) && n.parent == document.root }
+      end
+    end
+
+    def dsig_signature?(node)
+      node.respond_to?(:namespace) && node.name == "Signature" && node.namespace&.href == HankoXml::NS["ds"]
+    end
+
+    # Coverage questions are answered on the caller's nodes, so they need
+    # the DOM. Without it they raise rather than guess (§6.1).
+    def require_document!(capability)
+      return if document
+
+      raise HankoXml::NokogiriRequired,
+            "#{capability} needs a DOM: verify a Nokogiri document, or load Nokogiri before verifying, " \
+            "to use it (#102)."
+    end
+
+    def xpath_namespaces(ns)
+      HankoXml::NS.merge(namespaces).merge((ns || {}).transform_keys(&:to_s))
+    end
+
+    def build_references
+      return [] unless signature_info
+
+      signature_info.references.map.with_index do |ref, index|
+        target_node = resolve_reference(ref, index)
+
+        Reference.new(
+          uri: ref.uri,
+          node: target_node,
+          digest_method: ref.digest_method_name,
+          transforms: ref.transform_names,
+          valid?: reference_valid_for(index),
+          errors: reference_errors_for(ref, index),
+          signature_exclusion: ref.signature_exclusion
+        ).freeze
+      end
+    end
+
+    # Native.verify reports each SignedInfo Reference's own digest status,
+    # independent of the overall signature/key outcome (S-09): a
+    # harmless-fragment Reference and the payload Reference can genuinely
+    # disagree, so "the whole signature is valid" cannot stand in for "this
+    # Reference's digest matched". Falls back to the overall result only when
+    # there is no real per-reference answer -- a Verification built directly
+    # (specs, error paths that never reached crypto) or a reference xmlsec
+    # never got to because verification aborted earlier.
+    def reference_valid_for(index)
+      return valid? unless @reference_valid
+
+      status = @reference_valid[index]
+      status.nil? ? valid? : status
+    end
+
+    # A DigestMismatch only when xmlsec itself reported this Reference's
+    # digest as wrong; the fallback in #reference_valid_for proves nothing
+    # about one Reference (#96). The URI is document text, so it goes in
+    # #reference_uri, not the message.
+    def reference_errors_for(ref, index)
+      return [] unless @reference_valid && @reference_valid[index] == false
+
+      [HankoXml::DigestMismatch.new("a <Reference>'s digest does not match", reference_uri: ref.uri).freeze]
+    end
+
+    # When Native.verify supplied element indexes, those are the authority.
+    # A caller-supplied resolver: may only *agree* with them — disagreement is
+    # ResolutionMismatch (API_CONTRACT §5.9). Without native indexes (unit tests
+    # that construct Verification directly), fall back to resolver / id_attributes.
+    def detect_resolution_mismatches!
+      return unless resolver
+      return unless signature_info
+
+      # A resolver: is a check the caller asked for; without the DOM it
+      # cannot run, and it must never be skipped.
+      require_document!("resolver:")
+
+      signature_info.references.each_with_index do |ref, index|
+        next unless ref.uri&.start_with?("#")
+
+        id = ref.uri[1..]
+        resolver_node = resolver.call(document, id)
+        expected = if reference_element_indexes
+                     node_at_element_index(reference_element_indexes[index])
+                   elsif !id_attributes.empty?
+                     resolve_by_id_attributes(id)
+                   else
+                     next
+                   end
+
+        record_resolution_mismatch(id) unless same_node?(resolver_node, expected)
+      end
+    end
+
+    def record_resolution_mismatch(id)
+      @errors << HankoXml::ResolutionMismatch.new(
+        "resolver and xmlsec ID resolution disagree on a reference's target",
+        xmlsec_errors: ["reference: ##{id}"]
+      )
+      @valid = false
+    end
+
+    def same_node?(left, right)
+      return true if left.nil? && right.nil?
+      return false if left.nil? || right.nil?
+
+      left == right
+    end
+
+    def resolve_reference(ref, index)
+      return node_at_element_index(reference_element_indexes[index]) if reference_element_indexes
+
+      # Fallback for Verification constructed without a Native.verify result
+      # (specs / error paths that never reached crypto).
+      return nil unless document
+
+      if ref.uri.nil? || SignatureInfo::WHOLE_DOCUMENT_URIS.include?(ref.uri)
+        document.root
+      elsif ref.uri.start_with?("#")
+        resolve_fragment_reference(ref.uri[1..])
+      end
+    end
+
+    def node_at_element_index(index)
+      return nil if index.nil? || document.nil?
+
+      document.xpath("//*")[index]
+    end
+
+    def resolve_fragment_reference(id)
+      return resolver.call(document, id) if resolver
+
+      resolve_by_id_attributes(id)
+    end
+
+    def resolve_by_id_attributes(id)
+      predicates = []
+      bindings = { id: id }
+
+      id_attributes.each_with_index do |attr, index|
+        name_key = :"attr_name_#{index}"
+        if attr.is_a?(Array) && attr.size == 2
+          ns_key = :"attr_ns_#{index}"
+          bindings[name_key] = attr[1].to_s
+          bindings[ns_key] = attr[0].to_s
+          predicates << "@*[local-name()=$#{name_key} and namespace-uri()=$#{ns_key} and .=$id]"
+        else
+          bindings[name_key] = attr.to_s
+          predicates << "@*[local-name()=$#{name_key} and namespace-uri()='' and .=$id]"
+        end
+      end
+
+      return nil if predicates.empty?
+
+      document.at_xpath("//*[(#{predicates.join(" or ")})]", nil, bindings)
+    end
+  end
+end