moxml 0.1.25 → 0.1.26

data/lib/moxml/signature/algorithms/base64_transform.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base64 decode transform (W3C §6.6.2).
+      #
+      # Input: octets or nodeset. For nodeset, logically applies self::text(),
+      # sorts nodes by document order, concatenates string values, then decodes.
+      # Output: octets.
+      class Base64Transform < TransformBase
+        identifier "http://www.w3.org/2000/09/xmldsig#base64"
+
+        def self.input_type; :octets; end
+        def self.output_type; :octets; end
+
+        def transform(input)
+          text = input.is_a?(Array) ? input.map { |n| text_of(n) }.join : input.to_s
+          stripped = text.gsub(/\s+/, "")
+          Base64.strict_decode64(stripped)
+        rescue ArgumentError => e
+          raise TransformError.new(
+            "base64 decode failed: #{e.message}",
+            algorithm: self.class.identifier_uri,
+          )
+        end
+
+        private
+
+        def text_of(node)
+          return node.text if node.is_a?(::Moxml::Node)
+
+          node.to_s
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/canonicalization_base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for canonicalization algorithms.
+      #
+      # Subclasses declare `identifier "http://..."` and implement #engine
+      # (returning a Moxml::C14n::* walker). Canonicalizers operate on a
+      # Moxml::Node subtree and return UTF-8 octets.
+      #
+      # Canonicalization algorithms can also be used as transforms per
+      # spec §6.6.1. The base class provides the #transform method that
+      # adapts the canonicalize interface to the transform pipeline.
+      class CanonicalizationBase
+        class << self
+          # Canonicalization presents the transform interface (spec §6.6.1).
+          # Input: octet stream or node-set. Output: octet stream.
+          def input_type; :nodeset; end
+
+          def output_type; :octets; end
+
+          def identifier(uri)
+            Algorithms.register(:canonicalization, uri, self)
+          end
+
+          def for_uri(uri, **opts)
+            new(identifier_uri: uri, **opts)
+          end
+        end
+
+        attr_reader :identifier_uri, :with_comments, :inclusive_namespaces,
+                    :context
+
+        # `context:` is required when this algorithm is used as a transform
+        # so that octet-stream input can be parsed with the same adapter
+        # the caller used for the rest of the document.
+        def initialize(identifier_uri: nil, with_comments: nil,
+                       inclusive_namespaces: [], context: nil, **_unused)
+          @identifier_uri = identifier_uri
+          @with_comments = with_comments.nil? ? uri_has_comments?(identifier_uri) : with_comments
+          @inclusive_namespaces = inclusive_namespaces || []
+          @context = context
+        end
+
+        def canonicalize(node)
+          engine.canonicalize(
+            node,
+            with_comments: @with_comments,
+            inclusive_namespaces: @inclusive_namespaces,
+          )
+        end
+
+        # Adapt to the transform interface (spec §6.6.1). Octet-stream
+        # input is parsed using the same Moxml::Context the caller used;
+        # this preserves the byte-exact invariant across adapters.
+        def transform(input)
+          return canonicalize(input) if input.is_a?(::Moxml::Node)
+
+          if context.nil?
+            raise TransformError,
+                  "canonicalization transform requires a context to parse " \
+                  "octet-stream input; none was provided"
+          end
+
+          parsed = context.parse(input.to_s)
+          canonicalize(parsed.root)
+        end
+
+        private
+
+        def uri_has_comments?(uri)
+          return false if uri.nil?
+
+          uri.end_with?("#WithComments")
+        end
+
+        def engine
+          raise NotImplementedError,
+                "#{self.class} must implement #engine"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/digest_base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for message digest algorithms (SHA family).
+      #
+      # Subclasses MUST declare:
+      #   - `identifier "http://..."` to register
+      #   - either `digest_bits N` and `openssl_digest_name "SHA256"` etc.,
+      #     OR override `#compute_digest`.
+      class DigestBase
+        class << self
+          attr_reader :identifier_uri, :digest_size_bits
+
+          def identifier(uri)
+            @identifier_uri = uri
+            Algorithms.register(:digest, uri, self)
+          end
+
+          def digest_bits(bits)
+            @digest_size_bits = bits
+          end
+
+          def openssl_digest_name(name)
+            define_method(:compute_digest) do |data|
+              OpenSSL::Digest.digest(name, data)
+            end
+          end
+        end
+
+        def digest(data)
+          compute_digest(data.to_s)
+        end
+
+        def digest_base64(data)
+          Base64.strict_encode64(digest(data))
+        end
+
+        def compute_digest(_data)
+          raise NotImplementedError,
+                "#{self.class} must implement #compute_digest " \
+                "or declare openssl_digest_name"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/dsa_sha.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # DSA signature methods per FIPS 186-3.
+      #
+      # Two URIs:
+      #   - SHA1 (1024-bit, q=160): wire format r‖s with 20-byte halves
+      #   - SHA256 (2048-bit, q=256): wire format r‖s with N-byte halves
+      #     where N = byte length of q (32 for SHA-256 case)
+      #
+      # OpenSSL returns DER; we convert to raw r‖s.
+      class DsaSha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2000/09/xmldsig#dsa-sha1" => "SHA1",
+          "http://www.w3.org/2009/xmldsig11#dsa-sha256" => "SHA256",
+        }.freeze
+
+        PAIRINGS.each_key { |uri| identifier uri }
+
+        def initialize(identifier_uri:, parameters: nil)
+          super(nil)
+          @identifier_uri = identifier_uri
+          @parameters = parameters
+        end
+
+        def compute_signature(data, key)
+          dsa = coerce_signing_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          der_signature = dsa.sign(digest_name, data)
+          der_to_raw(der_signature, coordinate_bytes_for(dsa))
+        end
+
+        def verify_signature(data, key, signature)
+          dsa = coerce_verify_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          n_bytes = coordinate_bytes_for(dsa)
+          der_signature = raw_to_der(signature, n_bytes)
+          dsa.verify(digest_name, der_signature, data)
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def coerce_signing_key(key)
+          case key
+          when OpenSSL::PKey::DSA
+            key
+          else
+            raise SignatureKeyError,
+                  "DSA signature method requires OpenSSL::PKey::DSA, " \
+                  "got #{key.class}"
+          end
+        end
+
+        def coerce_verify_key(key)
+          coerce_signing_key(key)
+        end
+
+        def coordinate_bytes_for(dsa)
+          # q is the subgroup order. byte length of q.
+          q_bits = dsa.q.num_bits
+          (q_bits + 7) / 8
+        end
+
+        def der_to_raw(der, n_bytes)
+          seq = OpenSSL::ASN1.decode(der)
+          r = seq.value[0].value
+          s = seq.value[1].value
+          i2osp(r, n_bytes) + i2osp(s, n_bytes)
+        end
+
+        def raw_to_der(raw, n_bytes)
+          raise ArgumentError, "raw signature has wrong size" if raw.bytesize != (2 * n_bytes)
+
+          r = raw.byteslice(0, n_bytes)
+          s = raw.byteslice(n_bytes, n_bytes)
+          seq = OpenSSL::ASN1::Sequence.new([
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(r)),
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(s)),
+                                            ])
+          seq.to_der
+        end
+
+        def i2osp(value, length)
+          n = value.to_i
+          raise ArgumentError, "I2OSP: integer too large" if n >= (1 << (8 * length))
+
+          bytes = Array.new(length, 0)
+          (length - 1).downto(0) do |i|
+            bytes[i] = n & 0xff
+            n >>= 8
+          end
+          bytes.pack("C*")
+        end
+
+        def asn1_integer_value(octets)
+          octets.bytes.reduce(0) { |acc, byte| (acc << 8) | byte }
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/ecdsa_sha.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # ECDSA signature methods per FIPS 186-3, bound to a digest.
+      #
+      # Spec §6.4.3 requires support for ECDSAwithSHA256 over the P-256
+      # curve. Recommended: P-384, P-521.
+      #
+      # The wire format is base64(I2OSP(r, n_bytes) || I2OSP(s, n_bytes))
+      # where n_bytes is the byte length of the base point order
+      # (32 for P-256, 48 for P-384, 66 for P-521).
+      #
+      # OpenSSL returns a DER-encoded ASN.1 sequence of (r, s). We convert
+      # to the raw r||s form on sign, and back from raw to DER on verify.
+      class EcdsaSha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1" => "SHA1",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224" => "SHA224",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" => "SHA256",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384" => "SHA384",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512" => "SHA512",
+        }.freeze
+
+        # Map OpenSSL curve name → byte length of base point order.
+        CURVE_ORDER_BYTES = {
+          "prime256v1" => 32,   # P-256
+          "secp384r1" => 48,    # P-384
+          "secp521r1" => 66,    # P-521 (ceil(521/8) = 66)
+        }.freeze
+
+        PAIRINGS.each_key { |uri| identifier uri }
+
+        def initialize(identifier_uri:, parameters: nil)
+          super(nil)
+          @identifier_uri = identifier_uri
+          @parameters = parameters
+        end
+
+        def compute_signature(data, key)
+          ec_key = coerce_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          der_signature = ec_key.sign(digest_name, data)
+          der_to_raw(der_signature, coordinate_bytes_for(ec_key))
+        end
+
+        def verify_signature(data, key, signature)
+          ec_key = coerce_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          n_bytes = coordinate_bytes_for(ec_key)
+          der_signature = raw_to_der(signature, n_bytes)
+          ec_key.verify(digest_name, der_signature, data)
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def coerce_key(key)
+          case key
+          when OpenSSL::PKey::EC then key
+          when OpenSSL::PKey::EC::Point
+            raise SignatureKeyError,
+                  "ECDSA requires an EC key, not a bare Point"
+          else
+            raise SignatureKeyError,
+                  "ECDSA signature method requires OpenSSL::PKey::EC, " \
+                  "got #{key.class}"
+          end
+        end
+
+        def coordinate_bytes_for(ec_key)
+          curve_name = ec_key.group.curve_name
+          self.class::CURVE_ORDER_BYTES.fetch(curve_name) do
+            raise SignatureError,
+                  "ECDSA curve #{curve_name.inspect} not supported; " \
+                  "add it to EcdsaSha::CURVE_ORDER_BYTES"
+          end
+        end
+
+        # Convert ASN.1 DER sequence of two INTEGERs to raw r‖s octets.
+        def der_to_raw(der, n_bytes)
+          seq = OpenSSL::ASN1.decode(der)
+          r = seq.value[0].value
+          s = seq.value[1].value
+          i2osp(r, n_bytes) + i2osp(s, n_bytes)
+        end
+
+        # Convert raw r‖s octets back to ASN.1 DER.
+        def raw_to_der(raw, n_bytes)
+          raise ArgumentError, "raw signature has wrong size" if raw.bytesize != (2 * n_bytes)
+
+          r = raw.byteslice(0, n_bytes)
+          s = raw.byteslice(n_bytes, n_bytes)
+          seq = OpenSSL::ASN1::Sequence.new([
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(r)),
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(s)),
+                                            ])
+          seq.to_der
+        end
+
+        # Integer to octet stream (I2OSP), minimal length parameter.
+        def i2osp(value, length)
+          n = value.to_i
+          raise ArgumentError, "I2OSP: integer too large" if n >= (1 << (8 * length))
+
+          bytes = Array.new(length, 0)
+          (length - 1).downto(0) do |i|
+            bytes[i] = n & 0xff
+            n >>= 8
+          end
+          bytes.pack("C*")
+        end
+
+        # Interpret an octet string as a positive integer (OS2IP).
+        def asn1_integer_value(octets)
+          octets.bytes.reduce(0) { |acc, byte| (acc << 8) | byte }
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/enveloped_signature_transform.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Enveloped Signature Transform (W3C §6.6.4).
+      #
+      # Removes the containing ds:Signature element from the node-set so the
+      # signature does not include itself in its own digest calculation.
+      #
+      # Semantics during signing: `signature_element` is nil (the Signature
+      # has not been attached to the document yet), so the transform is a
+      # no-op — the document contains no Signature to exclude.
+      #
+      # Semantics during verification: `signature_element` is the Signature
+      # element being verified. The transform detaches it (and its
+      # descendants) from a deep copy of the input so the canonicalizer
+      # walks a tree without the Signature.
+      class EnvelopedSignatureTransform < TransformBase
+        identifier "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+
+        def self.input_type; :nodeset; end
+        def self.output_type; :nodeset; end
+
+        def transform(input)
+          return input if @signature_element.nil?
+
+          # If the signature is not within the input subtree, no-op.
+          return input unless signature_within?(input)
+
+          working_copy = deep_copy(input)
+          remove_signature_within(working_copy)
+          working_copy
+        end
+
+        private
+
+        def signature_within?(input)
+          !find_signature_element(input).nil?
+        end
+
+        def remove_signature_within(node)
+          sig = find_signature_element(node)
+          sig&.remove
+        end
+
+        def find_signature_element(node)
+          return nil unless node
+          return node if signature_element?(node)
+
+          children = node.children if node.is_a?(::Moxml::Node)
+          children&.each do |child|
+            found = find_signature_element(child)
+            return found if found
+          end
+          nil
+        end
+
+        def signature_element?(node)
+          node.is_a?(::Moxml::Element) &&
+            node.name == "Signature" &&
+            node.namespace_uri == DSIG_NS
+        end
+
+        def deep_copy(input)
+          case input
+          when ::Moxml::Document
+            @context.parse(input.root.to_xml(indent: 0))
+          when ::Moxml::Element
+            wrapper = @context.parse("<__wrap__>#{input.to_xml(indent: 0)}</__wrap__>")
+            wrapper.root.children.first
+          else
+            input
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/exc_c14n_10.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Exclusive XML Canonicalization 1.0 (https://www.w3.org/TR/xml-exc-c14n/)
+      #
+      # Two registered URIs: one omits comments, one includes comments.
+      # The with_comments variant is detected from the URI suffix at
+      # instantiation time (see CanonicalizationBase#uri_has_comments?).
+      class ExcC14n10 < CanonicalizationBase
+        identifier "http://www.w3.org/2001/10/xml-exc-c14n#"
+        identifier "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"
+
+        private
+
+        def engine
+          ::Moxml::C14n::Exclusive.new
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/hmac_sha.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # HMAC per RFC 2104, bound to a digest.
+      #
+      # Per W3C XML Signature §4.4.2 and §6.3.1, if `HMACOutputLength` is
+      # specified, the output is truncated to that many bits and the
+      # truncation length MUST be at least max(hash_bits / 2, 80) bits.
+      class HmacSha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2000/09/xmldsig#hmac-sha1" => "SHA1",
+          "http://www.w3.org/2001/04/xmldsig-more#hmac-sha224" => "SHA224",
+          "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256" => "SHA256",
+          "http://www.w3.org/2001/04/xmldsig-more#hmac-sha384" => "SHA384",
+          "http://www.w3.org/2001/04/xmldsig-more#hmac-sha512" => "SHA512",
+        }.freeze
+
+        HASH_BITS = {
+          "SHA1" => 160,
+          "SHA224" => 224,
+          "SHA256" => 256,
+          "SHA384" => 384,
+          "SHA512" => 512,
+        }.freeze
+
+        MIN_TRUNCATION_BITS = 80
+
+        PAIRINGS.each_key { |uri| identifier uri }
+
+        # parameters: optional { hmac_output_length: Integer } (bits, multiple of 8)
+        def initialize(identifier_uri:, parameters: nil)
+          super(parameters)
+          @identifier_uri = identifier_uri
+          @truncation_bits = parameters&.dig(:hmac_output_length)
+          validate_truncation! if @truncation_bits
+        end
+
+        def compute_signature(data, key)
+          secret = coerce_key(key)
+          full = OpenSSL::HMAC.digest(digest_name, secret, data)
+          truncate(full)
+        end
+
+        def verify_signature(data, key, signature)
+          expected = compute_signature(data, key)
+          fixed_comparison(expected, signature)
+        end
+
+        private
+
+        def digest_name
+          PAIRINGS.fetch(@identifier_uri)
+        end
+
+        def hash_bits
+          HASH_BITS.fetch(digest_name)
+        end
+
+        def truncate(full_mac)
+          return full_mac unless @truncation_bits
+
+          unless (@truncation_bits % 8).zero?
+            raise SignatureError,
+                  "HMACOutputLength (#{@truncation_bits}) must be a " \
+                  "multiple of 8"
+          end
+
+          min = [hash_bits / 2, MIN_TRUNCATION_BITS].max
+          if @truncation_bits < min
+            raise SignatureError,
+                  "HMACOutputLength (#{@truncation_bits}) below minimum " \
+                  "of #{min} for #{digest_name}"
+          end
+
+          full_mac.byteslice(0, @truncation_bits / 8)
+        end
+
+        def validate_truncation!
+          unless (@truncation_bits % 8).zero?
+            raise SignatureError,
+                  "HMACOutputLength (#{@truncation_bits}) must be a " \
+                  "multiple of 8"
+          end
+
+          min = [hash_bits / 2, MIN_TRUNCATION_BITS].max
+          return if @truncation_bits >= min
+
+          raise SignatureError,
+                "HMACOutputLength (#{@truncation_bits}) below minimum " \
+                "of #{min} for #{digest_name}"
+        end
+
+        def coerce_key(key)
+          case key
+          when String then key
+          else
+            raise SignatureKeyError,
+                  "HMAC signature method requires a String secret, " \
+                  "got #{key.class}"
+          end
+        end
+
+        def fixed_comparison(expected, actual)
+          return false unless expected.bytesize == actual.bytesize
+
+          OpenSSL.fixed_length_secure_compare(expected, actual)
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/inclusive_c14n_10.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Canonical XML 1.0 (https://www.w3.org/TR/xml-c14n/)
+      #
+      # Implemented via the canon-derived C14n::Inclusive10 engine.
+      class InclusiveC14n10 < CanonicalizationBase
+        identifier "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
+        identifier "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"
+
+        private
+
+        def engine
+          ::Moxml::C14n::Inclusive10.new
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/inclusive_c14n_11.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Canonical XML 1.1 (https://www.w3.org/TR/xml-c14n11/)
+      #
+      # Currently delegates to Inclusive 1.0. Full 1.1 differences
+      # (XML 1.1 line-ending handling, notations, DTD entity refs)
+      # are documented in TODO.complete/05-c14n-engine.md.
+      class InclusiveC14n11 < CanonicalizationBase
+        identifier "http://www.w3.org/2006/12/xml-c14n11"
+        identifier "http://www.w3.org/2006/12/xml-c14n11#WithComments"
+
+        private
+
+        def engine
+          ::Moxml::C14n::Inclusive10.new
+        end
+      end
+    end
+  end
+end