hanko_xml 0.1.0

data/lib/hanko_xml/key.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module HankoXml
+  # Explicit wrapper around key/certificate material. See
+  # API_CONTRACT.md §5.6.
+  #
+  # Everything crossing into the native layer is PEM, always -- Key
+  # normalizes with OpenSSL::PKey#to_pem / OpenSSL::X509::Certificate#to_pem.
+  #
+  # A Key never appears in #inspect or #to_s, and its constructor filters
+  # any value coming from a Key out of exception messages (see errors.rb).
+  class Key
+    # The label of each `-----BEGIN <label>-----` line.
+    PEM_LABEL = /^-----BEGIN ([A-Z0-9 ]+)-----\s*$/
+
+    class << self
+      # Decides certificate vs key from the PEM block labels, not from
+      # substrings anywhere in the text (S-15). A PEM holding both a
+      # certificate and a key raises instead of silently keeping one.
+      def from_pem(pem, password: nil)
+        pem = pem.to_s
+        material =
+          if certificate_pem?(pem)
+            begin
+              ::OpenSSL::X509::Certificate.new(pem)
+            rescue ::OpenSSL::X509::CertificateError => e
+              raise HankoXml::KeyLoadError, "could not parse certificate PEM: #{e.message}"
+            end
+          else
+            begin
+              read_pkey(pem, password)
+            rescue ::OpenSSL::PKey::PKeyError => e
+              raise HankoXml::KeyLoadError,
+                    "could not parse key PEM: #{e.message}#{encrypted_hint(pem, password)}#{path_hint(pem)}"
+            end
+          end
+
+        new(material)
+      end
+
+      # OpenSSL::PKey.read with a nil password falls back to OpenSSL's
+      # default callback, which prompts "Enter PEM pass phrase:" on the
+      # controlling terminal and blocks the process until someone types.
+      # An empty String never prompts: an encrypted key just fails to load.
+      def read_pkey(material, password)
+        ::OpenSSL::PKey.read(material, password.nil? ? "" : password.to_s)
+      end
+
+      def encrypted_hint(pem, password)
+        return "" unless password.nil?
+        return "" unless pem.include?("ENCRYPTED")
+
+        ". The key is encrypted; pass password: (HankoXml::Key.from_pem(pem, password: ...))"
+      end
+      private :encrypted_hint
+
+      # A String is always key material, never a filename (S-21): accepting
+      # both would make "which one was meant" a guess. The hint never echoes
+      # the input, which may be (malformed) key material.
+      def path_hint(pem)
+        return "" if pem.include?("-----BEGIN")
+
+        ". A String is read as PEM/DER content, not a file path; to load a file, pass " \
+          "Pathname.new(path) or use HankoXml::Key.from_file(path)"
+      end
+      private :path_hint
+
+      def certificate_pem?(pem)
+        labels = pem.scan(PEM_LABEL).flatten
+        certificates = labels.count { |label| label.end_with?("CERTIFICATE") }
+        keys = labels.count { |label| label.end_with?("KEY") }
+        return false if certificates.zero?
+        return true if keys.zero?
+
+        raise HankoXml::KeyLoadError,
+              "PEM contains both a certificate and a key; pass them separately as key: and certificate:"
+      end
+      private :certificate_pem?
+
+      def from_der(der)
+        material =
+          begin
+            ::OpenSSL::X509::Certificate.new(der)
+          rescue ::OpenSSL::X509::CertificateError
+            begin
+              read_pkey(der, nil)
+            rescue ::OpenSSL::PKey::PKeyError => e
+              raise HankoXml::KeyLoadError, "could not parse DER key/certificate: #{e.message}"
+            end
+          end
+
+        new(material)
+      end
+
+      def from_file(path, password: nil)
+        from_pem(::File.binread(path.respond_to?(:to_path) ? path.to_path : path), password: password)
+      end
+
+      def from_pkcs12(path, password:)
+        bytes = ::File.binread(path.respond_to?(:to_path) ? path.to_path : path)
+        pkcs12 =
+          begin
+            ::OpenSSL::PKCS12.new(bytes, password)
+          rescue ::OpenSSL::PKCS12::PKCS12Error => e
+            raise HankoXml::KeyLoadError, "could not read PKCS#12 bundle: #{e.message}"
+          end
+
+        Bundle.new(
+          key: new(pkcs12.key),
+          certificate: new(pkcs12.certificate),
+          certificates: [new(pkcs12.certificate), *Array(pkcs12.ca_certs).map { |c| new(c) }]
+        )
+      end
+    end
+
+    # key: / certificate: / certificates: -- coerces any of the accepted
+    # input shapes (OpenSSL object, PEM String, path-like, or an existing
+    # Key) into a Key. Returns +input+ unchanged if it is already a Key.
+    def self.coerce(input, password: nil)
+      case input
+      when Key
+        input
+      when ::OpenSSL::PKey::PKey, ::OpenSSL::X509::Certificate
+        new(input)
+      when String
+        from_pem(input, password: password)
+      when ->(obj) { obj.respond_to?(:to_path) }
+        from_file(input, password: password)
+      else
+        raise ArgumentError,
+              "expected an OpenSSL::PKey::PKey, OpenSSL::X509::Certificate, PEM String, " \
+              "path-like object, or HankoXml::Key, got #{input.class}"
+      end
+    end
+
+    def initialize(material)
+      @material = material
+      @disposed = false
+    end
+
+    def certificate?
+      @material.is_a?(::OpenSSL::X509::Certificate)
+    end
+
+    # True only for a key that has its private half (S-15). A public-only
+    # OpenSSL::PKey::PKey is false.
+    def private_key?
+      return false unless @material.is_a?(::OpenSSL::PKey::PKey)
+      return @material.private? if @material.respond_to?(:private?)
+
+      # Generic PKey (e.g. Ed25519) has no #private?; only a private key
+      # serializes its private half.
+      @material.private_to_der
+      true
+    rescue ::OpenSSL::PKey::PKeyError
+      false
+    end
+
+    def to_pem
+      raise HankoXml::KeyLoadError, "this key has been disposed" if @disposed
+
+      @material.to_pem
+    end
+
+    def to_openssl
+      raise HankoXml::KeyLoadError, "this key has been disposed" if @disposed
+
+      @material
+    end
+
+    # Drops this Key's reference to its OpenSSL object and makes #to_pem /
+    # #to_openssl raise from then on. It does NOT zeroize anything (S-15):
+    # the key bytes live in OpenSSL-owned memory freed whenever Ruby's GC
+    # collects the object, and every String #to_pem already returned is the
+    # caller's, untouched. Use it to stop later accidental use, not as a
+    # memory-hygiene guarantee.
+    def dispose!
+      return if @disposed
+
+      @disposed = true
+      @material = nil
+    end
+
+    def disposed?
+      @disposed
+    end
+
+    def inspect
+      "#<#{self.class} #{certificate? ? "certificate" : "key"}=[FILTERED]>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    # key:, certificate:, certificates: bundle returned by .from_pkcs12.
+    class Bundle
+      attr_reader :key, :certificate, :certificates
+
+      def initialize(key:, certificate:, certificates:)
+        @key = key
+        @certificate = certificate
+        @certificates = certificates
+      end
+
+      def to_h
+        { key: key, certificate: certificate, certificates: certificates }
+      end
+    end
+  end
+end

data/lib/hanko_xml/key_info.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # KeyInfo clauses a Signer emits into <ds:KeyInfo>, and the parsed,
+  # unauthenticated view a Verification exposes as what the document
+  # *claimed*. See API_CONTRACT.md §5.2, §5.4.
+  module KeyInfo
+    # Recognised clause names, and which <ds:X509Data> child (if any) they
+    # map to when building a template.
+    CLAUSES = %i[
+      x509_certificate
+      x509_subject_name
+      x509_issuer_serial
+      x509_ski
+      key_name
+      key_value
+    ].freeze
+
+    # A single clause a Signer will emit, e.g. :x509_certificate. +value+ is
+    # the text a clause writes itself rather than leaving to xmlsec: only
+    # :key_name has one, the name for <KeyName> (#67).
+    Clause = Struct.new(:name, :value) do
+      def initialize(name, value = nil)
+        name = name.to_sym
+        unless KeyInfo::CLAUSES.include?(name)
+          raise HankoXml::ConfigurationError,
+                "unknown key_info clause #{name.inspect}, expected one of #{KeyInfo::CLAUSES.inspect}"
+        end
+        if !value.nil? && name != :key_name
+          raise HankoXml::ConfigurationError, "key_info clause #{name.inspect} takes no value"
+        end
+
+        super(name, value&.to_s&.freeze)
+        freeze
+      end
+    end
+
+    class << self
+      # Normalizes a Signer's key_info: value (an Array of Symbols/Clauses,
+      # or a single one) into a frozen Array<Clause>. A Hash names a clause
+      # with its value, e.g. `{ key_name: "idp-1" }`.
+      def coerce(value)
+        value = [value] if value.is_a?(Hash) # Array(hash) would split it into pairs
+        Array(value).flat_map do |v|
+          case v
+          when Clause then v
+          when Hash then v.map { |name, clause_value| Clause.new(name, clause_value) }
+          else Clause.new(v)
+          end
+        end.freeze
+      end
+    end
+
+    # What a document's <ds:KeyInfo> actually contained, read out but never
+    # authenticated (Verification#key_info, API_CONTRACT.md §5.4): its
+    # <KeyName> texts and <X509Certificate>s as PEM Strings.
+    class Parsed
+      attr_reader :key_names, :certificates
+
+      def initialize(key_names: [], certificates: [])
+        @key_names = key_names.freeze
+        @certificates = certificates.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/hanko_xml/native_version.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # Guards the one failure mode a bindgen-built extension cannot detect on its
+  # own: being loaded against a libxmlsec1 whose structs are laid out
+  # differently from the headers the bindings were generated from.
+  #
+  # +ext/hanko_xml/build.rs+ runs bindgen at compile time, which bakes xmlsec's
+  # and libxml2's struct layouts into the compiled extension. Nothing about a
+  # later layout change is visible to the dynamic linker: every symbol still
+  # resolves, the library still loads, and then a field is read at the offset
+  # our headers claimed rather than the one the loaded library actually used.
+  # In a library whose entire job is deciding whether a signature can be
+  # trusted, that has to be a hard failure at require time rather than a wrong
+  # answer at verify time.
+  #
+  # For a source-installed gem this check passes by construction -- the machine
+  # that compiled the extension is the machine loading it. It earns its keep
+  # for precompiled platform gems, and for an extension that outlives an OS
+  # package upgrade of libxmlsec1.
+  module NativeVersion
+    # Downgrades a mismatch from a raise to a warning when set to any non-empty
+    # value. This is an escape hatch for someone who has established that their
+    # two versions really are compatible; it is not a supported configuration,
+    # and a wrong call here is silent memory corruption rather than an error.
+    SKIP_ENV = "HANKO_XML_SKIP_VERSION_CHECK"
+
+    class << self
+      # Verifies the loaded libxmlsec1 against the compiled-in one.
+      #
+      # @return [Symbol] +:ok+ when they match exactly, +:abi_compatible+ when
+      #   they differ only in a way xmlsec considers ABI safe, or +:skipped+
+      #   when {SKIP_ENV} suppressed the check.
+      # @raise [HankoXml::NativeVersionMismatch] when they are not ABI compatible.
+      def check!
+        return :ok if Native.check_version
+
+        unless Native.abi_compatible?
+          raise NativeVersionMismatch, mismatch_message if skip.nil?
+
+          warn("hanko_xml: #{mismatch_message}")
+          return :skipped
+        end
+
+        :abi_compatible
+      end
+
+      # The xmlsec1, libxml2, and crypto backend versions this extension was
+      # compiled against.
+      #
+      # @return [Hash{Symbol => String}]
+      def build_versions
+        Native.versions
+      end
+
+      private
+
+      def skip
+        value = ENV[SKIP_ENV]
+        value unless value.nil? || value.empty?
+      end
+
+      def mismatch_message
+        built = build_versions
+        "the loaded libxmlsec1 is not ABI compatible with the one this " \
+          "extension was compiled against (xmlsec1 #{built[:xmlsec]}, " \
+          "libxml2 #{built[:libxml2]}). Reinstall hanko_xml so the extension " \
+          "is rebuilt against the libxmlsec1 currently on this machine " \
+          "(`gem pristine hanko_xml`, or `bundle exec rake compile` from a " \
+          "checkout). Set #{SKIP_ENV}=1 to downgrade this to a warning if you " \
+          "have established the two are compatible."
+      end
+    end
+  end
+end

data/lib/hanko_xml/nokogiri_ext.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../hanko_xml"
+
+# Core extensions for Nokogiri::XML::Document and Nokogiri::XML::Node to
+# support direct #sign, #sign!, #signature_valid?, #signatures, and #signed?
+# See API_CONTRACT.md §6.6.
+module HankoXml
+  # Mixed into Nokogiri::XML::Document and Nokogiri::XML::Node to provide the
+  # signing and verification shorthands described in API_CONTRACT.md §6.6.
+  module NokogiriExt
+    def sign(**kwargs)
+      HankoXml.sign(self, **kwargs)
+    end
+
+    def sign!(**kwargs)
+      HankoXml.sign!(self, **kwargs)
+    end
+
+    def signature_valid?(**kwargs)
+      HankoXml.valid?(self, **kwargs)
+    end
+
+    def signatures
+      xpath(".//ds:Signature", ds: NS["ds"])
+    end
+
+    def signature_present?
+      HankoXml.signature_present?(self)
+    end
+  end
+end
+
+HankoXml::Dom.extend_nodes(HankoXml::NokogiriExt)

data/lib/hanko_xml/placement.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # Where the <Signature> element goes. Frozen value object; Symbols coerce.
+  # See API_CONTRACT.md §5.5.
+  class Placement
+    MODES = %i[append_to_root prepend_to_root append_to prepend_to after before detached custom].freeze
+
+    attr_reader :mode, :target, :namespaces, :block
+
+    def initialize(mode, target: nil, namespaces: {}, &block)
+      mode = mode.to_sym
+      raise HankoXml::ConfigurationError, "unknown placement mode #{mode.inspect}" unless MODES.include?(mode)
+
+      @mode = mode
+      @target = target
+      @namespaces = namespaces
+      @block = block
+      freeze
+    end
+
+    def detached?
+      mode == :detached
+    end
+
+    class << self
+      def append_to_root
+        new(:append_to_root)
+      end
+
+      def prepend_to_root
+        new(:prepend_to_root)
+      end
+
+      def append_to(node_or_xpath, namespaces: {})
+        new(:append_to, target: node_or_xpath, namespaces: namespaces)
+      end
+
+      def prepend_to(node_or_xpath, namespaces: {})
+        new(:prepend_to, target: node_or_xpath, namespaces: namespaces)
+      end
+
+      def after(node_or_xpath, namespaces: {})
+        new(:after, target: node_or_xpath, namespaces: namespaces)
+      end
+
+      def before(node_or_xpath, namespaces: {})
+        new(:before, target: node_or_xpath, namespaces: namespaces)
+      end
+
+      def detached
+        new(:detached)
+      end
+
+      def custom(&block)
+        new(:custom, &block)
+      end
+
+      # Coerces a Placement, a recognised Symbol (:append_to_root,
+      # :prepend_to_root, :detached), or leaves nil as-is.
+      def coerce(value)
+        case value
+        when Placement then value
+        when Symbol then new(value)
+        when nil then nil
+        else
+          raise ArgumentError, "expected a HankoXml::Placement or Symbol, got #{value.class}"
+        end
+      end
+    end
+
+    # Resolves +target+ to exactly one Nokogiri::XML::Node within +doc+.
+    # The XPath sees HankoXml::NS, then the Signer's +namespaces:+, then
+    # Placement#namespaces, each merged over the last (#96). Raises
+    # HankoXml::PlacementError if the XPath matches zero or more than one
+    # node.
+    def resolve(doc, namespaces: {})
+      return doc.root if target.nil?
+      return target if HankoXml::Dom.node?(target)
+
+      ns = HankoXml::NS.merge((namespaces || {}).transform_keys(&:to_s)).merge(self.namespaces.transform_keys(&:to_s))
+      matches = HankoXml::Dom.xpath(doc, target, ns) do
+        raise HankoXml::PlacementError,
+              "placement XPath #{target.inspect} is not valid XPath; bind every prefix it uses in namespaces:"
+      end
+
+      if matches.empty?
+        raise HankoXml::PlacementError, "placement XPath #{target.inspect} matched no nodes"
+      elsif matches.size > 1
+        raise HankoXml::PlacementError,
+              "placement XPath #{target.inspect} matched #{matches.size} nodes, expected exactly one"
+      end
+
+      matches.first
+    end
+
+    # Inserts +signature_node+ into +doc+ per this placement's mode.
+    # +namespaces+ are the Signer's, see #resolve. Returns +signature_node+.
+    def insert(doc, signature_node, namespaces: {})
+      case mode
+      when :append_to_root
+        doc.root.add_child(signature_node)
+      when :prepend_to_root
+        if doc.root.children.first
+          doc.root.children.first.add_previous_sibling(signature_node)
+        else
+          doc.root.add_child(signature_node)
+        end
+      when :append_to
+        resolve(doc, namespaces: namespaces).add_child(signature_node)
+      when :prepend_to
+        node = resolve(doc, namespaces: namespaces)
+        node.children.first ? node.children.first.add_previous_sibling(signature_node) : node.add_child(signature_node)
+      when :after
+        resolve(doc, namespaces: namespaces).add_next_sibling(signature_node)
+      when :before
+        resolve(doc, namespaces: namespaces).add_previous_sibling(signature_node)
+      when :detached
+        # Caller does not insert; Signer#template returns the built node.
+      when :custom
+        block.call(doc, signature_node)
+      end
+
+      signature_node
+    end
+  end
+end