hanko_xml 0.1.0-arm64-darwin

data/lib/hanko_xml/algorithms.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # Registry of algorithm URIs, keyed by short Symbol names, per slot
+  # (:canonicalization, :digest, :signature, :transform). See
+  # API_CONTRACT.md §5.7.
+  #
+  # Every algorithm slot elsewhere in the library accepts either a Symbol
+  # (looked up here) or a String URI (used verbatim, subject to Policy).
+  #
+  # Registration is process-global and additive. It does NOT grant use --
+  # a Policy allowlist must separately permit the algorithm. Built-in names
+  # and URIs cannot be re-pointed, even with replace: true (S-16).
+  module Algorithms # rubocop:disable Metrics/ModuleLength
+    Entry = Struct.new(:slot, :name, :uri, :secure, keyword_init: true) do
+      def secure?
+        !!secure
+      end
+    end
+
+    # Name/URI lookup for a single algorithm slot (e.g. :digest).
+    class Table
+      def initialize(slot)
+        @slot = slot
+        @by_name = {}
+        @by_uri = {}
+        @builtin_names = {}.freeze
+        @builtin_uris = {}.freeze
+      end
+
+      def register(name, uri, secure:, replace: false)
+        name = name.to_sym
+        uri = uri.to_s
+        check_not_builtin!(name, uri)
+
+        if @by_name.key?(name) && !replace
+          raise ArgumentError,
+                "#{@slot} algorithm #{name.inspect} is already registered " \
+                "(pass replace: true to override)"
+        end
+
+        previous = @by_name[name]
+        @by_uri.delete(previous.uri) if previous && @by_uri[previous.uri].equal?(previous)
+
+        entry = Entry.new(slot: @slot, name: name, uri: uri, secure: secure).freeze
+        @by_name[name] = entry
+        @by_uri[uri] = entry
+        entry
+      end
+
+      # Marks everything registered so far as built-in (S-16): those names
+      # and URIs are what Policy presets are written in terms of, so
+      # re-pointing one would silently change what, e.g., Policy.strict
+      # accepts for every caller in the process.
+      def seal_builtins!
+        @builtin_names = @by_name.keys.to_h { |name| [name, true] }.freeze
+        @builtin_uris = @by_uri.keys.to_h { |uri| [uri, true] }.freeze
+        self
+      end
+
+      def [](name_or_uri)
+        case name_or_uri
+        when Symbol
+          @by_name[name_or_uri]
+        when String
+          @by_uri[name_or_uri] || @by_name[name_or_uri.to_sym]
+        end
+      end
+
+      def uri_for(name_or_uri)
+        return name_or_uri if name_or_uri.is_a?(String) && !@by_name.key?(name_or_uri.to_sym)
+
+        entry = self[name_or_uri]
+        entry&.uri || (name_or_uri.is_a?(String) ? name_or_uri : nil)
+      end
+
+      def name_for(uri)
+        @by_uri[uri.to_s]&.name
+      end
+
+      def secure?(name_or_uri)
+        entry = self[name_or_uri]
+        entry.nil? ? false : entry.secure?
+      end
+
+      def names
+        @by_name.keys
+      end
+
+      private
+
+      def check_not_builtin!(name, uri)
+        if @builtin_names.key?(name)
+          raise ArgumentError, "#{@slot} algorithm #{name.inspect} is built in and cannot be replaced"
+        end
+        return unless @builtin_uris.key?(uri)
+
+        raise ArgumentError,
+              "#{@slot} URI #{uri} is built in as #{@by_uri[uri].name.inspect} and cannot be re-registered"
+      end
+    end
+
+    class << self
+      def canonicalization
+        @canonicalization ||= build_canonicalization_table
+      end
+
+      def digest
+        @digest ||= build_digest_table
+      end
+
+      def signature
+        @signature ||= build_signature_table
+      end
+
+      def transform
+        @transform ||= build_transform_table
+      end
+
+      def register(slot, name, uri, secure:, replace: false)
+        table_for(slot).register(name, uri, secure: secure, replace: replace)
+      end
+
+      def uri_for(slot, name_or_uri)
+        table_for(slot).uri_for(name_or_uri)
+      end
+
+      def name_for(slot, uri)
+        table_for(slot).name_for(uri)
+      end
+
+      def secure?(slot, name_or_uri)
+        table_for(slot).secure?(name_or_uri)
+      end
+
+      private
+
+      def table_for(slot)
+        case slot.to_sym
+        when :canonicalization then canonicalization
+        when :digest then digest
+        when :signature then signature
+        when :transform then transform
+        else
+          raise ArgumentError, "unknown algorithm slot #{slot.inspect}"
+        end
+      end
+
+      def build_canonicalization_table
+        table = Table.new(:canonicalization)
+        table.register(:c14n, "http://www.w3.org/TR/2001/REC-xml-c14n-20010315", secure: true)
+        table.register(:c14n_with_comments,
+                       "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments", secure: true)
+        table.register(:exc_c14n, "http://www.w3.org/2001/10/xml-exc-c14n#", secure: true)
+        table.register(:exc_c14n_with_comments,
+                       "http://www.w3.org/2001/10/xml-exc-c14n#WithComments", secure: true)
+        table.register(:c14n11, "http://www.w3.org/2006/12/xml-c14n11", secure: true)
+        table.register(:c14n11_with_comments,
+                       "http://www.w3.org/2006/12/xml-c14n11#WithComments", secure: true)
+        table.seal_builtins!
+      end
+
+      def build_digest_table
+        table = Table.new(:digest)
+        table.register(:sha1, "http://www.w3.org/2000/09/xmldsig#sha1", secure: false)
+        table.register(:sha224, "http://www.w3.org/2001/04/xmldsig-more#sha224", secure: true)
+        table.register(:sha256, "http://www.w3.org/2001/04/xmlenc#sha256", secure: true)
+        table.register(:sha384, "http://www.w3.org/2001/04/xmldsig-more#sha384", secure: true)
+        table.register(:sha512, "http://www.w3.org/2001/04/xmlenc#sha512", secure: true)
+        table.register(:ripemd160, "http://www.w3.org/2001/04/xmlenc#ripemd160", secure: false)
+        # RFC 6931 SHA-3. xmlsec 1.3 implements these; xmlsec 1.2 (Ubuntu CI)
+        # does not — Native.sign/verify then fails closed (#60).
+        table.register(:sha3_224, "http://www.w3.org/2007/05/xmldsig-more#sha3-224", secure: true)
+        table.register(:sha3_256, "http://www.w3.org/2007/05/xmldsig-more#sha3-256", secure: true)
+        table.register(:sha3_384, "http://www.w3.org/2007/05/xmldsig-more#sha3-384", secure: true)
+        table.register(:sha3_512, "http://www.w3.org/2007/05/xmldsig-more#sha3-512", secure: true)
+        table.seal_builtins!
+      end
+
+      def build_signature_table
+        table = Table.new(:signature)
+        table.register(:rsa_sha1, "http://www.w3.org/2000/09/xmldsig#rsa-sha1", secure: false)
+        table.register(:rsa_sha224, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha224", secure: true)
+        table.register(:rsa_sha256, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", secure: true)
+        table.register(:rsa_sha384, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384", secure: true)
+        table.register(:rsa_sha512, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512", secure: true)
+        # RFC 6931 RSA-PSS (MGF1, default salt = hash length). xmlsec 1.3
+        # implements these without <RSAPSSParams>; xmlsec 1.2 does not (#60).
+        table.register(:rsa_pss_sha256, "http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1",
+                       secure: true)
+        table.register(:rsa_pss_sha384, "http://www.w3.org/2007/05/xmldsig-more#sha384-rsa-MGF1",
+                       secure: true)
+        table.register(:rsa_pss_sha512, "http://www.w3.org/2007/05/xmldsig-more#sha512-rsa-MGF1",
+                       secure: true)
+        table.register(:ecdsa_sha256, "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256", secure: true)
+        table.register(:ecdsa_sha384, "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384", secure: true)
+        table.register(:ecdsa_sha512, "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512", secure: true)
+        # RFC 9231 put ECDSA-SHA3 under the 2021/04 namespace, not RFC 6931's
+        # 2007/05 one; xmlsec 1.3 uses the same URIs (#60).
+        table.register(:ecdsa_sha3_256, "http://www.w3.org/2021/04/xmldsig-more#ecdsa-sha3-256",
+                       secure: true)
+        table.register(:ecdsa_sha3_384, "http://www.w3.org/2021/04/xmldsig-more#ecdsa-sha3-384",
+                       secure: true)
+        table.register(:ecdsa_sha3_512, "http://www.w3.org/2021/04/xmldsig-more#ecdsa-sha3-512",
+                       secure: true)
+        table.register(:dsa_sha1, "http://www.w3.org/2000/09/xmldsig#dsa-sha1", secure: false)
+        table.register(:hmac_sha256, "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256", secure: true)
+        table.seal_builtins!
+      end
+
+      def build_transform_table
+        table = Table.new(:transform)
+        # Every canonicalization algorithm is also a valid transform.
+        canonicalization.names.each do |name|
+          entry = canonicalization[name]
+          table.register(entry.name, entry.uri, secure: entry.secure?)
+        end
+        table.register(:enveloped_signature, "http://www.w3.org/2000/09/xmldsig#enveloped-signature",
+                       secure: true)
+        table.register(:base64, "http://www.w3.org/2000/09/xmldsig#base64", secure: true)
+        table.register(:xpath, "http://www.w3.org/TR/1999/REC-xpath-19991116", secure: false)
+        table.register(:xpath_filter2, "http://www.w3.org/2002/06/xmldsig-filter2", secure: false)
+        table.register(:xslt, "http://www.w3.org/TR/1999/REC-xslt-19991116", secure: false)
+        table.seal_builtins!
+      end
+    end
+  end
+end

data/lib/hanko_xml/dom.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # The single place that probes for, or calls into, Nokogiri. Nothing else
+  # in the library references the Nokogiri constant directly -- see
+  # API_CONTRACT.md §6.1. spec/hanko_xml/dom_spec.rb enforces this, and that
+  # nothing in lib/ ever requires Nokogiri (the caller decides load order,
+  # §3.1).
+  #
+  # The DOM operations below take no decision of their own: each is the one
+  # Nokogiri call its caller needs, kept here so a DOM-free path (#102) has a
+  # single seam to replace or guard.
+  #
+  # The rule: a missing Nokogiri may remove a capability, it may never weaken
+  # one. Every check that runs with Nokogiri present runs identically in its
+  # absence; the capabilities that disappear are the ones that cannot be
+  # expressed at all without a DOM, and each of them raises
+  # HankoXml::NokogiriRequired rather than quietly returning a less careful
+  # answer.
+  #
+  # @api private
+  module Dom
+    class << self
+      def available?
+        defined?(::Nokogiri::XML::Document) ? true : false
+      end
+
+      def document?(obj)
+        available? && obj.is_a?(::Nokogiri::XML::Document)
+      end
+
+      def node?(obj)
+        available? && obj.is_a?(::Nokogiri::XML::Node)
+      end
+
+      def certificate?(obj)
+        defined?(::OpenSSL::X509::Certificate) && obj.is_a?(::OpenSSL::X509::Certificate)
+      end
+
+      def pkey?(obj)
+        defined?(::OpenSSL::PKey::PKey) && obj.is_a?(::OpenSSL::PKey::PKey)
+      end
+
+      # Raises HankoXml::NokogiriRequired, naming +capability+ and the fix,
+      # unless Nokogiri is loaded.
+      def require!(capability)
+        return if available?
+
+        raise HankoXml::NokogiriRequired,
+              "#{capability} needs a DOM, and Nokogiri is not loaded. Add `gem \"nokogiri\"` to your " \
+              "Gemfile and `require \"nokogiri\"` before using it. Verification, signature_present? and " \
+              "signing an existing <Signature> template work without it (API_CONTRACT.md §6.1)."
+      end
+
+      # Parses +source+ strict (no RECOVER) and nonet: the one way that does
+      # not break XML-DSig (API_CONTRACT.md §6.3). Returns the document and
+      # libxml2's errors, or nil and the SyntaxError strict mode raised.
+      def parse(source)
+        doc = ::Nokogiri::XML(source) { |config| config.strict.nonet }
+        [doc, doc.errors]
+      rescue ::Nokogiri::XML::SyntaxError => e
+        [nil, [e]]
+      end
+
+      # Byte-faithful serialization: AS_XML only, never FORMAT, which reindents
+      # the tree and invalidates any signature over it (§6.3).
+      def to_xml(node, declaration: true)
+        options = ::Nokogiri::XML::Node::SaveOptions::AS_XML
+        options |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION unless declaration
+        node.to_xml(save_with: options)
+      end
+
+      # Runs +expression+ against +node+. On an XPath syntax error, returns
+      # what the block returns (the block usually raises); without a block
+      # the error propagates.
+      def xpath(node, expression, namespaces)
+        node.xpath(expression, namespaces)
+      rescue ::Nokogiri::XML::XPath::SyntaxError
+        raise unless block_given?
+
+        yield
+      end
+
+      # Loads the XSD at +path+, with the path as the base URL so its
+      # relative imports resolve (#61).
+      def schema_from_file(path)
+        require!("XML Schema validation")
+
+        ::Nokogiri::XML::Schema.from_document(::Nokogiri::XML(::File.read(path), path))
+      end
+
+      # Validates a copy of +node+, as the root of a fresh document, against
+      # +schema+. Returns the validation errors.
+      def schema_errors(schema, node)
+        doc = ::Nokogiri::XML::Document.new
+        doc.add_child(node.dup)
+        schema.validate(doc)
+      end
+
+      # Mixes +mod+ into Nokogiri's Document and Node. A no-op without
+      # Nokogiri. Returns whether it was installed.
+      def extend_nodes(mod)
+        return false unless available?
+
+        ::Nokogiri::XML::Document.include(mod)
+        ::Nokogiri::XML::Node.include(mod)
+        true
+      end
+
+      # What works in this process (API_CONTRACT.md §6.1). Verification, and
+      # signing a template the document already holds, run on bytes through
+      # the native layer, so they never need Nokogiri; the rest need a DOM.
+      # #102.
+      #
+      # - verify: Verifier / HankoXml.valid? / verify! / signature_present?,
+      #   including `schema: :default`.
+      # - sign: Signer, HankoXml.sign / sign!.
+      # - sign_existing_template: Signer#sign / HankoXml.sign of a document
+      #   that already holds the <Signature> template, on bytes (#102).
+      # - coverage_checks: Verification#signed?, #signed_nodes, #at_signed.
+      # - schema: a caller's own Nokogiri::XML::Schema as `schema:`.
+      # - parse: HankoXml.parse / serialize.
+      # - template_build: Template, Signer#template.
+      def capabilities
+        {
+          verify: true,
+          sign: available?,
+          sign_existing_template: true,
+          coverage_checks: available?,
+          schema: available?,
+          parse: available?,
+          template_build: available?
+        }
+      end
+    end
+  end
+end

data/lib/hanko_xml/errors.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module HankoXml
+  # Base class for everything this gem raises. Rescue this to catch anything
+  # hanko_xml-specific. See API_CONTRACT.md §5.10 for the full hierarchy and
+  # the reasoning behind it (in particular: never KeyError/ArgumentError/
+  # TypeError/IOError, which would shadow core Ruby constants inside this
+  # module).
+  class Error < StandardError
+    # A private key in PEM form, including a truncated one. Redacted from
+    # every message and log line (API_CONTRACT.md §5.10, #96).
+    PRIVATE_KEY_PEM = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|\z)/m
+    FILTERED = "[FILTERED]"
+
+    # The xmlsec1 error log lines captured for this failure, or libxml2's
+    # diagnostics for a ParseError / SchemaError. Untrusted: they can quote
+    # the document.
+    attr_reader :xmlsec_errors
+
+    # The <ds:Signature> Nokogiri::XML::Element this error relates to, when
+    # one was located.
+    attr_accessor :signature_node
+
+    # Never carries key material: a HankoXml::Key or OpenSSL::PKey passed as
+    # +message+ becomes [FILTERED], and private-key PEM text is redacted.
+    # (NativeVersionMismatch can be raised before key.rb is loaded.)
+    def self.filter(value)
+      return nil if value.nil?
+      return FILTERED if value.is_a?(OpenSSL::PKey::PKey) || (defined?(HankoXml::Key) && value.is_a?(HankoXml::Key))
+
+      value.to_s.gsub(PRIVATE_KEY_PEM, FILTERED)
+    end
+
+    def initialize(message = nil, xmlsec_errors: [], signature_node: nil)
+      super(Error.filter(message))
+      self.xmlsec_errors = xmlsec_errors
+      @signature_node = signature_node
+    end
+
+    def xmlsec_errors=(lines)
+      @xmlsec_errors = Array(lines).map { |line| Error.filter(line) }
+    end
+  end
+
+  # Invalid Signer/Verifier construction.
+  class ConfigurationError < Error; end
+
+  # A Policy allowlist was violated.
+  class PolicyError < ConfigurationError; end
+
+  # A Placement XPath matched zero or more than one node.
+  class PlacementError < ConfigurationError; end
+
+  # The requested capability needs a DOM, and Nokogiri is not loaded. See
+  # API_CONTRACT.md §6.1.
+  class NokogiriRequired < ConfigurationError; end
+
+  # <Signature> failed XSD validation (Verifier schema: option).
+  class SchemaError < ConfigurationError; end
+
+  # The XML would not parse.
+  class ParseError < Error; end
+
+  # A key or certificate was unreadable or in an unsupported format.
+  class KeyLoadError < Error; end
+
+  # A Reference target does not exist, is ambiguous, or has no ID attribute.
+  class ReferenceError < Error
+    attr_accessor :reference_uri
+
+    def initialize(message = nil, reference_uri: nil, **kwargs)
+      super(message, **kwargs)
+      @reference_uri = reference_uri
+    end
+  end
+
+  # libxmlsec1 could not produce a signature.
+  class SigningError < Error; end
+
+  # Verification did not succeed (raised by #verify!).
+  class VerificationError < Error; end
+
+  # The signature verified as XML-DSig, but its XAdES signed properties do not
+  # hold: they are not the ones xmlsec digested, or they do not commit to the
+  # certificate that verified (#58).
+  class XadesError < VerificationError; end
+
+  # Cryptographic mismatch.
+  class SignatureInvalid < VerificationError; end
+
+  # No <ds:Signature> in the document.
+  class SignatureMissing < VerificationError; end
+
+  # Verifier#signature was :only and the document has more than one.
+  class MultipleSignatures < VerificationError; end
+
+  # Certificate/key trust resolution (chain or pinning) failed.
+  class UntrustedCertificate < VerificationError; end
+
+  # Certificate is outside notBefore/notAfter as of verification_time.
+  class CertificateExpired < VerificationError; end
+
+  # One <Reference>'s digest did not match.
+  class DigestMismatch < VerificationError
+    attr_accessor :reference_uri
+
+    def initialize(message = nil, reference_uri: nil, **kwargs)
+      super(message, **kwargs)
+      @reference_uri = reference_uri
+    end
+  end
+
+  # A caller-supplied `resolver:` and xmlsec's ID table disagreed on what a
+  # Reference URI points to. See API_CONTRACT.md §5.9.
+  class ResolutionMismatch < VerificationError; end
+
+  # Verification#at_signed found a node the signature does not cover.
+  class NotSignedError < Error; end
+
+  # A mutator was called on a HankoXml::SignedDocument.
+  class FrozenSignatureError < Error; end
+
+  # libxmlsec1 failed in an unexpected way.
+  class NativeError < Error; end
+
+  # The loaded libxmlsec1 is not ABI compatible with the headers this
+  # extension was compiled against. Raised at require time by
+  # {HankoXml::NativeVersion}; see that file for why this cannot be a warning.
+  class NativeVersionMismatch < NativeError; end
+end

data/lib/hanko_xml/exc-c14n.xsd

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Schema for Exclusive XML Canonicalization InclusiveNamespaces
+    http://www.w3.org/2001/10/xml-exc-c14n#
+    As published in https://www.w3.org/TR/xml-exc-c14n/#sec-Schema
+
+    Copyright 2002 The Internet Society and W3C (Massachusetts Institute
+    of Technology, Institut National de Recherche en Informatique et en
+    Automatique, Keio University). All Rights Reserved.
+    http://www.w3.org/Consortium/Legal/
+
+    This document is governed by the W3C Software License [1] as described
+    in the FAQ [2].
+
+    [1] http://www.w3.org/Consortium/Legal/copyright-software-19980720
+    [2] http://www.w3.org/Consortium/Legal/IPR-FAQ-20000620.html#DTD
+-->
+<schema xmlns="http://www.w3.org/2001/XMLSchema"
+        xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
+        targetNamespace="http://www.w3.org/2001/10/xml-exc-c14n#"
+        version="0.1" elementFormDefault="qualified">
+
+  <element name="InclusiveNamespaces" type="ec:InclusiveNamespaces"/>
+  <complexType name="InclusiveNamespaces">
+    <attribute name="PrefixList" type="NMTOKENS"/>
+  </complexType>
+</schema>

data/lib/hanko_xml/input.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module HankoXml
+  # A document on its way to the native layer: always its bytes, plus the
+  # caller's DOM when there is one (API_CONTRACT.md §6.1, #102).
+  #
+  # Every security check reads the bytes, through the native layer, so it
+  # runs the same with or without Nokogiri. The DOM only serves what cannot
+  # exist without one: Verification#signed? and friends, XPath signature
+  # selection, a caller's own Nokogiri schema, a resolver:.
+  #
+  # @api private
+  class Input
+    attr_reader :bytes, :document
+
+    # +source+ is anything §6.2 accepts. A Nokogiri Document or Node is
+    # serialized; anything else is read as bytes (+policy+'s
+    # +max_document_size+ applies first, S-12) and, when Nokogiri is loaded,
+    # also parsed, so the result carries a DOM either way.
+    def self.read(source, policy: nil)
+      if Dom.document?(source) || Dom.node?(source)
+        document = Dom.document?(source) ? source : source.document
+        return new(HankoXml.serialize(document).b, document, dom: true)
+      end
+
+      raw = HankoXml.read_source(source, policy: policy)
+      document = Dom.available? ? HankoXml.parse(raw) : nil
+      new(raw.b, document, dom: false)
+    end
+
+    def initialize(bytes, document, dom:)
+      @bytes = bytes.frozen? ? bytes : bytes.dup.freeze
+      @document = document
+      @dom = dom
+    end
+
+    # Whether the caller handed over a DOM (rather than bytes).
+    def dom?
+      @dom
+    end
+
+    # Native.scan of the bytes, memoized per ID-attribute list. Input that
+    # arrived as bytes is parsed strictly, as HankoXml.parse does with
+    # Nokogiri; a DOM the caller already holds is taken as it is.
+    def scan(id_attributes)
+      @scans ||= {}
+      @scans[id_attributes] ||= Native.scan(bytes, id_attributes, !dom?)
+    end
+  end
+end