moxml 0.1.25 → 0.2.0

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

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # RSASSA-PKCS1-v1_5 per RFC 3447 §8.2, bound to a digest.
+      #
+      # One Ruby class registered under five URIs (sha1 / sha224 / sha256 /
+      # sha384 / sha512). When instantiated, the class is told which URI was
+      # resolved so it can pick the right digest.
+      class RsaPkcs1Sha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2000/09/xmldsig#rsa-sha1" => "SHA1",
+          "http://www.w3.org/2001/04/xmldsig-more#rsa-sha224" => "SHA224",
+          "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" => "SHA256",
+          "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384" => "SHA384",
+          "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512" => "SHA512",
+        }.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)
+          rsa_key = coerce_key(key)
+          rsa_key.sign(digest_name, data)
+        end
+
+        def verify_signature(data, key, signature)
+          rsa_key = coerce_key(key)
+          rsa_key.verify(digest_name, signature, data)
+        end
+
+        private
+
+        def digest_name
+          PAIRINGS.fetch(@identifier_uri)
+        end
+
+        def coerce_key(key)
+          return key if key.is_a?(OpenSSL::PKey::RSA)
+
+          raise SignatureKeyError,
+                "RSA signature method requires OpenSSL::PKey::RSA, " \
+                "got #{key.class}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      class SHA1 < DigestBase
+        identifier "http://www.w3.org/2000/09/xmldsig#sha1"
+        digest_bits 160
+        openssl_digest_name "SHA1"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      class SHA224 < DigestBase
+        identifier "http://www.w3.org/2001/04/xmldsig-more#sha224"
+        digest_bits 224
+        openssl_digest_name "SHA224"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      class SHA256 < DigestBase
+        identifier "http://www.w3.org/2001/04/xmlenc#sha256"
+        digest_bits 256
+        openssl_digest_name "SHA256"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      class SHA384 < DigestBase
+        identifier "http://www.w3.org/2001/04/xmldsig-more#sha384"
+        digest_bits 384
+        openssl_digest_name "SHA384"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      class SHA512 < DigestBase
+        identifier "http://www.w3.org/2001/04/xmlenc#sha512"
+        digest_bits 512
+        openssl_digest_name "SHA512"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for signature methods and MACs.
+      #
+      # Subclasses declare an identifier URI per W3C spec §6.4 / §6.3 and
+      # implement #compute_signature and #verify_signature.
+      #
+      # `key` is whatever OpenSSL expects (OpenSSL::PKey::RSA for RSA, a
+      # String secret for HMAC, etc.).
+      class SignatureMethodBase
+        class << self
+          attr_reader :identifier_uri, :digest_uri
+
+          def identifier(uri, digest_uri: nil)
+            @identifier_uri = uri
+            @digest_uri = digest_uri
+            Algorithms.register(:signature_method, uri, self)
+          end
+        end
+
+        # Optional constructor for parameterized methods (e.g. HMACOutputLength).
+        def initialize(parameters = nil)
+          @parameters = parameters
+        end
+
+        def sign(data, key)
+          compute_signature(data, key)
+        rescue OpenSSL::PKey::PKeyError => e
+          raise SigningError.new(
+            "signing failed: #{e.class}",
+            algorithm: self.class.identifier_uri,
+          )
+        end
+
+        def verify(data, key, signature)
+          verify_signature(data, key, signature)
+        rescue OpenSSL::PKey::PKeyError => e
+          raise VerificationError.new(
+            "verification raised: #{e.class}",
+          )
+        end
+
+        def compute_signature(_data, _key)
+          raise NotImplementedError,
+                "#{self.class} must implement #compute_signature"
+        end
+
+        def verify_signature(_data, _key, _signature)
+          raise NotImplementedError,
+                "#{self.class} must implement #verify_signature"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for XML Signature transforms.
+      #
+      # Each transform declares input and output types (:octets or :nodeset)
+      # plus an identifier URI. The reference resolver chains them with
+      # default type conversion when types mismatch (octets → nodeset via
+      # XML parse; nodeset → octets via inclusive C14N 1.0).
+      class TransformBase
+        class << self
+          attr_reader :identifier_uri
+
+          def identifier(uri)
+            @identifier_uri = uri
+            Algorithms.register(:transform, uri, self)
+          end
+
+          def input_type; :octets; end
+          def output_type; :octets; end
+        end
+
+        # `parameters`: optional hash parsed from the ds:Transform element
+        # (e.g. { xpaths: [...] } for the XPath Filter transform).
+        def initialize(parameters: nil, context: nil, signature_element: nil)
+          @parameters = parameters || {}
+          @context = context
+          @signature_element = signature_element
+        end
+
+        def transform(_input)
+          raise NotImplementedError,
+                "#{self.class} must implement #transform"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Open-closed registry of W3C XML Signature algorithms keyed by URI.
+    #
+    # Adding a new algorithm:
+    #   1. Subclass the relevant base (DigestBase, SignatureMethodBase, etc.)
+    #   2. Declare `identifier "http://..."` on the subclass.
+    #   3. Add an autoload entry below and a reference in `load_builtins!`.
+    #
+    # No edits to existing classes are required to add a new algorithm.
+    module Algorithms
+      CATEGORIES = %i[digest signature_method canonicalization transform].freeze
+
+      class << self
+        def registry
+          @registry ||= CATEGORIES.to_h { |c| [c, {}] }
+        end
+
+        def register(category, uri, klass)
+          validate_category!(category)
+          registry[category][uri] = klass
+          klass
+        end
+
+        def lookup(category, uri)
+          load_builtins! unless @builtins_loaded
+          registry[category][uri] ||
+            raise(UnknownAlgorithm.new(category, uri))
+        end
+
+        def registered?(category, uri)
+          load_builtins! unless @builtins_loaded
+          registry[category].key?(uri)
+        end
+
+        def [](category)
+          validate_category!(category)
+          registry[category]
+        end
+
+        # Forces autoload of every built-in algorithm class so that
+        # self-registration runs. Pure autoload — no `require` calls.
+        def load_builtins!
+          return if @builtins_loaded
+
+          # Digests
+          SHA1
+          SHA224
+          SHA256
+          SHA384
+          SHA512
+          # Signature methods
+          RsaPkcs1Sha
+          HmacSha
+          EcdsaSha
+          DsaSha
+          # Canonicalization
+          ExcC14n10
+          InclusiveC14n10
+          InclusiveC14n11
+          # Transforms
+          Base64Transform
+          EnvelopedSignatureTransform
+
+          @builtins_loaded = true
+        end
+
+        private
+
+        def validate_category!(category)
+          return if CATEGORIES.include?(category)
+
+          raise ArgumentError,
+                "unknown algorithm category #{category.inspect}; " \
+                "expected one of #{CATEGORIES.inspect}"
+        end
+      end
+
+      # Base classes — interfaces only.
+      autoload :DigestBase, "moxml/signature/algorithms/digest_base"
+      autoload :SignatureMethodBase,
+               "moxml/signature/algorithms/signature_method_base"
+      autoload :CanonicalizationBase,
+               "moxml/signature/algorithms/canonicalization_base"
+      autoload :TransformBase, "moxml/signature/algorithms/transform_base"
+
+      # Digests
+      autoload :SHA1, "moxml/signature/algorithms/sha1"
+      autoload :SHA224, "moxml/signature/algorithms/sha224"
+      autoload :SHA256, "moxml/signature/algorithms/sha256"
+      autoload :SHA384, "moxml/signature/algorithms/sha384"
+      autoload :SHA512, "moxml/signature/algorithms/sha512"
+
+      # Signature methods
+      autoload :RsaPkcs1Sha, "moxml/signature/algorithms/rsa_pkcs1_sha"
+      autoload :HmacSha, "moxml/signature/algorithms/hmac_sha"
+      autoload :EcdsaSha, "moxml/signature/algorithms/ecdsa_sha"
+      autoload :DsaSha, "moxml/signature/algorithms/dsa_sha"
+
+      # Canonicalization (delegates to Moxml::C14n engine)
+      autoload :ExcC14n10, "moxml/signature/algorithms/exc_c14n_10"
+      autoload :InclusiveC14n10, "moxml/signature/algorithms/inclusive_c14n_10"
+      autoload :InclusiveC14n11, "moxml/signature/algorithms/inclusive_c14n_11"
+
+      # Transforms
+      autoload :Base64Transform, "moxml/signature/algorithms/base64_transform"
+      autoload :EnvelopedSignatureTransform,
+               "moxml/signature/algorithms/enveloped_signature_transform"
+    end
+  end
+end