moxml 0.1.24 → 0.1.26

data/docs/signature/quick-reference.md

@@ -0,0 +1,115 @@
+# Quick reference
+
+## Public API
+
+```ruby
+# Sign a document
+signature = Moxml::Signature.sign(
+  context:,                   # Moxml::Context (from Moxml.new(:nokogiri))
+  document:,                  # Moxml::Document to sign
+  key:,                       # OpenSSL::PKey::* or HMAC secret String
+  signature_method:,          # algorithm URI
+  canonicalization_method:,   # algorithm URI
+  digest_method:,             # algorithm URI
+  reference_uri:,             # "" for whole document
+  transforms:,                # array of algorithm URIs
+  key_info: nil,              # optional Model::KeyInfo
+  signature_id: nil,          # optional Id attribute
+)
+
+# Verify a document
+result = Moxml::Signature.verify(
+  context:,
+  document:,
+  key: nil,        # optional; auto-extracted from KeyInfo if absent
+  key_map: {},     # for KeyName-based resolution
+)
+```
+
+## Algorithm URIs
+
+### Digests
+- `http://www.w3.org/2000/09/xmldsig#sha1` (verification only)
+- `http://www.w3.org/2001/04/xmlenc#sha256` (REQUIRED)
+- `http://www.w3.org/2001/04/xmlenc#sha512`
+- `http://www.w3.org/2001/04/xmldsig-more#sha224`
+- `http://www.w3.org/2001/04/xmldsig-more#sha384`
+
+### Signature methods
+- RSA-PKCS1v1.5: `http://www.w3.org/2001/04/xmldsig-more#rsa-sha{1,224,256,384,512}`
+- HMAC: `http://www.w3.org/2001/04/xmldsig-more#hmac-sha{1,224,256,384,512}`
+- ECDSA: `http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha{1,224,256,384,512}`
+- DSA: `http://www.w3.org/2000/09/xmldsig#dsa-sha1`, `http://www.w3.org/2009/xmldsig11#dsa-sha256`
+
+### Canonicalization
+- Exclusive: `http://www.w3.org/2001/10/xml-exc-c14n#` (add `#WithComments`)
+- Inclusive 1.0: `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`
+- Inclusive 1.1: `http://www.w3.org/2006/12/xml-c14n11`
+
+### Transforms
+- `http://www.w3.org/2000/09/xmldsig#enveloped-signature`
+- `http://www.w3.org/2000/09/xmldsig#base64`
+
+## Common algorithm combinations
+
+### Enveloped RSA-SHA256 (most common)
+```ruby
+signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+```
+
+### HMAC-SHA256
+```ruby
+signature_method: "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256",
+canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+```
+
+### ECDSA-SHA256 (P-256)
+```ruby
+signature_method: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256",
+canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+```
+
+## Result inspection
+
+```ruby
+result.valid?                       # → bool (all signatures)
+result.signature_count              # → Integer
+result.failing                      # → [SingleVerificationResult]
+
+result.results.first.signature_valid?   # → bool (crypto verify)
+result.results.first.references         # → [ReferenceResult]
+result.results.first.failing_references # → [ReferenceResult]
+result.results.first.error             # → Exception or nil (debugging)
+```
+
+## C14N top-level API
+
+```ruby
+Moxml::C14n.canonicalize(node_or_xml, with_comments: false)
+Moxml::C14n.canonicalize_exclusive(node_or_xml, with_comments: false,
+                                   inclusive_namespaces: [])
+```
+
+## Errors
+
+```ruby
+Moxml::Signature::Error                       # base
+Moxml::Signature::SignatureError              # generic
+Moxml::Signature::UnknownAlgorithm            # URI not in registry
+Moxml::Signature::DuplicateAlgorithm          # URI registered twice
+Moxml::Signature::SigningError                # signing failed
+Moxml::Signature::VerificationError           # verification failed
+Moxml::Signature::ReferenceDigestMismatch     # digest mismatch
+Moxml::Signature::SignatureValueMismatch      # crypto verify failed
+Moxml::Signature::TransformError              # transform pipeline
+Moxml::Signature::CanonicalizationError       # C14N failure
+Moxml::Signature::MalformedSignatureError     # XML schema violation
+Moxml::Signature::SignatureKeyError           # wrong key type
+```

data/docs/signature/security.md

@@ -0,0 +1,143 @@
+# Security considerations
+
+XML signature is a complex spec with a long history of attacks. This
+document explains what `Moxml::Signature` does to mitigate them and
+what the application is responsible for.
+
+## Built-in mitigations
+
+### Best Practice 1 — authenticate before transforms (DONE)
+
+The Verifier validates `SignatureValue` before running any reference
+transforms. A hostile signature with expensive XSLT or XPath transforms
+cannot consume server resources unless its `SignatureValue` verifies
+against a key the application trusts.
+
+### Best Practice 26 — HMAC truncation floor (DONE)
+
+`HMACOutputLength` values below `max(hash_bits/2, 80)` are rejected
+during algorithm instantiation (spec §4.4.2). Signatures with
+sub-minimum truncation are deemed invalid.
+
+### Best Practice 11 — opaque certificate handling (DONE)
+
+`X509Certificate` payloads are decoded as raw DER and passed to
+`OpenSSL::X509::Certificate.new`. We never re-encode certificates, so
+the signature on the certificate itself is preserved.
+
+## What the application must do
+
+The library cannot make trust decisions; the application must.
+
+### Best Practice 2 — establish trust in the key
+
+Just because `SignatureValue` verifies against a public key in
+`KeyInfo` does NOT mean the signature should be trusted. The key must
+come from a trusted source:
+
+```ruby
+# Application-side: pin the expected key, ignore KeyInfo entirely
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key: trusted_public_key,   # do NOT rely on KeyInfo extraction
+)
+
+# Or, with certificate validation:
+cert = OpenSSL::X509::Certificate.new(cert_der)
+store = OpenSSL::X509::Store.new
+store.add_trust_file("cacert.pem")
+unless store.verify(cert)
+  raise "certificate chain invalid"
+end
+
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key: cert.public_key,
+)
+```
+
+### Best Practice 12 — see what was signed
+
+Use `SingleVerificationResult#references` to inspect what the signature
+actually covers:
+
+```ruby
+result.results.first.references.each do |ref|
+  puts "#{ref.uri}: #{ref.valid?}"
+  # Confirm ref.uri matches what the application expects to be signed.
+  # Wrapping attacks work by getting the verifier to confirm a different
+  # node than the application acts on.
+end
+```
+
+### Best Practice 14 — check name AND position
+
+When checking a reference URI, don't just verify the element name. A
+wrapping attack moves the signed element into an `<Object>` and points
+the reference at it; the application then acts on a different (unsigned)
+element with the same name.
+
+### Best Practice 8 — control external references
+
+External URI dereferencing is **not enabled by default**. If you need
+it, wrap the resolver in a policy that:
+
+- Allows only same-document URIs (`#id`, `""`)
+- Allows only specific schemes (`https://`, never `file://`)
+- Caps size and timeout
+- Disallows query parameters that mutate server state
+
+## What this library does NOT do
+
+### Not a chain validator
+
+`Moxml::Signature` does not validate X.509 certificate chains, check
+revocation, or evaluate certificate policies. The application is
+responsible for these (see Best Practice 2 above).
+
+### Not a timestamp authority
+
+Long-lived signatures need RFC 3161 timestamps from a TSA. This library
+does not implement timestamp verification.
+
+### Not a wrapping-attack detector
+
+Wrapping attacks succeed when the application acts on a different node
+than the one the signature actually covers. The library returns the
+list of references; the application must verify they cover the right
+nodes.
+
+## SHA-1 warning
+
+The W3C spec marks SHA-1 as REQUIRED for backwards compatibility but
+DISCOURAGED for new signatures. Cryptanalytic advances (SHAttered,
+2017) demonstrated practical collisions. Use SHA-256 or stronger for
+new signatures.
+
+## HMAC security
+
+HMAC signatures require a shared secret. Any verifier with the secret
+can forge signatures. Use distinct keys for signing vs. encryption
+(Best Practice 27).
+
+## Limited XPath support
+
+The library implements the Enveloped Signature transform directly
+(no XPath). XPath Filter and XSLT transforms are not implemented;
+Best Practices 3, 5, 6, 22 say avoid them.
+
+## Performance and DoS
+
+Canonicalization is O(N) for tree size. XSLT and complex XPath are
+not supported, eliminating the most common DoS vectors (Best Practices
+3, 5, 6). Wrap calls in a timeout if processing untrusted input:
+
+```ruby
+require "timeout"
+
+Timeout.timeout(5) do
+  Moxml::Signature.verify(context: ctx, document: untrusted_doc, key:)
+end
+```

data/examples/signature/auto_key_extraction.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Example: auto-extract the verification key from a KeyInfo that
+# contains an embedded X509Certificate. The Verifier derives the
+# OpenSSL key without application help.
+#
+# Run with: bundle exec ruby examples/signature/auto_key_extraction.rb
+
+require "moxml"
+require "moxml/signature"
+
+ctx = Moxml.new(:nokogiri)
+
+fixture = File.expand_path(
+  "../../spec/fixtures/xmldsig/sign3-result.xml",
+  __dir__,
+)
+xml = File.read(fixture)
+doc = ctx.parse(xml)
+
+# No explicit key — Verifier auto-extracts from X509Certificate.
+result = Moxml::Signature.verify(context: ctx, document: doc)
+puts "Auto-extracted from X509Certificate: #{result.valid?}"
+puts "Signature count: #{result.signature_count}"

data/examples/signature/enveloped_rsa.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Example: enveloped RSA-SHA256 signature with verification.
+#
+# Run with: bundle exec ruby examples/signature/enveloped_rsa.rb
+
+require "moxml"
+require "moxml/signature"
+require "openssl"
+
+ctx = Moxml.new(:nokogiri)
+key = OpenSSL::PKey::RSA.generate(2048)
+
+doc = ctx.parse("<doc><greeting>Hello, World!</greeting></doc>")
+puts "=== Before signing ==="
+puts doc.to_xml
+
+signature = Moxml::Signature.sign(
+  context: ctx,
+  document: doc,
+  key: key,
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+puts ""
+puts "=== After signing ==="
+puts doc.to_xml
+
+result = Moxml::Signature.verify(context: ctx, document: doc, key: key)
+puts ""
+puts "=== Verification ==="
+puts "Valid: #{result.valid?}"
+
+# Tamper test
+doc2 = ctx.parse(doc.to_xml(indent: 0))
+doc2.at_xpath("//greeting").text = "Goodbye!"
+tampered = Moxml::Signature.verify(context: ctx, document: doc2, key: key)
+puts "Tampered: #{tampered.valid?} (expected false)"

data/examples/signature/hmac.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Example: HMAC-SHA256 signature with a shared secret.
+#
+# Run with: bundle exec ruby examples/signature/hmac.rb
+
+require "moxml"
+require "moxml/signature"
+
+ctx = Moxml.new(:nokogiri)
+secret = "super-secret-shared-key"
+
+doc = ctx.parse("<message><body>hello</body></message>")
+
+signature = Moxml::Signature.sign(
+  context: ctx,
+  document: doc,
+  key: secret,
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+result = Moxml::Signature.verify(context: ctx, document: doc, key: secret)
+puts "Valid: #{result.valid?}"
+
+wrong = Moxml::Signature.verify(context: ctx, document: doc, key: "wrong")
+puts "Wrong secret: #{wrong.valid?} (expected false)"

data/lib/compat/opal/moxml_boot.rb

@@ -35,6 +35,10 @@ require "moxml/sax/element_handler"
 require "moxml/sax/block_handler"
 require "moxml/sax/namespace_splitter"
 require "moxml/adapter/rexml"
+require "moxml/adapter/customized_oga"
+require "moxml/adapter/customized_oga/xml_declaration"
+require "moxml/adapter/customized_oga/xml_generator"
+require "moxml/adapter/oga"
 require "moxml/document_builder"
 require "moxml/builder"
 require "moxml/context"

data/lib/moxml/adapter.rb

@@ -11,9 +11,11 @@ module Moxml
     AVAILABLE_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
 
     # Adapters that work under the Opal (JavaScript) runtime.
-    # REXML is pure Ruby and Opal reimplements strscan/stringio in its stdlib,
-    # enabling REXML to compile cleanly to JavaScript.
-    OPAL_AVAILABLE_ADAPTERS = %i[rexml].freeze
+    # Oga is pure Ruby and designed with Opal compatibility in mind — it is the
+    # canonical XML parser for the JavaScript runtime. REXML is also pure Ruby
+    # but requires extensive runtime compat shims (regex features like /n,
+    # \u{...}, (?-mix:...) don't transpile cleanly), so it is opt-in only.
+    OPAL_AVAILABLE_ADAPTERS = %i[oga rexml].freeze
 
     # Registry mapping adapter names to their class name suffixes.
     # Special cases (like :headed_ox → "HeadedOx") live here instead of

data/lib/moxml/c14n/attribute_handler.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Moxml
+  module C14n
+    # Attribute axis handler for inclusive C14N.
+    # Implements W3C C14N 1.0 §2.4 / 1.1 §2.4 attribute rendering,
+    # including resolution of simple inheritable attributes (xml:lang,
+    # xml:space) for document subsets.
+    class AttributeHandler
+      attr_reader :encoder
+
+      def initialize(encoder)
+        @encoder = encoder
+      end
+
+      def process_attributes(element, output, omitted_ancestors = [])
+        return unless element.in_node_set?
+
+        attributes = collect_attributes(element, omitted_ancestors)
+        attributes.each do |attr|
+          output << " "
+          output << attr.qname
+          output << '="'
+          output << encoder.encode_attribute(attr.value)
+          output << '"'
+        end
+      end
+
+      private
+
+      def collect_attributes(element, omitted_ancestors)
+        attributes = element.sorted_attribute_nodes.select(&:in_node_set?)
+
+        return attributes if omitted_ancestors.empty?
+
+        inherited = collect_inherited_attributes(element, omitted_ancestors)
+        merge_attributes(attributes, inherited)
+      end
+
+      # Walk omitted ancestors to collect simple inheritable attributes
+      # not already declared on the element. Per C14N 1.1 §2.4, these
+      # are inherited from the nearest ancestor in which they are declared.
+      def collect_inherited_attributes(element, omitted_ancestors)
+        inherited = []
+        seen = Set.new
+
+        element.attribute_nodes.each do |attr|
+          seen.add(attr.name) if attr.simple_inheritable?
+        end
+
+        omitted_ancestors.reverse_each do |ancestor|
+          ancestor.attribute_nodes.each do |attr|
+            next unless attr.simple_inheritable?
+            next if seen.include?(attr.name)
+
+            inherited << attr
+            seen.add(attr.name)
+          end
+        end
+
+        inherited
+      end
+
+      def merge_attributes(element_attrs, inherited_attrs)
+        (element_attrs + inherited_attrs).sort_by do |attr|
+          [attr.namespace_uri.to_s, attr.local_name]
+        end
+      end
+    end
+  end
+end

data/lib/moxml/c14n/character_encoder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Moxml
+  module C14n
+    # Character encoder for C14N output. Handles the entity escaping
+    # mandated by W3C C14N 1.0 §2.4 / 1.1 §2.4 for text and attribute values.
+    class CharacterEncoder
+      TEXT_ESCAPES = {
+        "&" => "&",
+        "<" => "&lt;",
+        ">" => "&gt;",
+        "\r" => "&#xD;",
+      }.freeze
+      ATTRIBUTE_ESCAPES = TEXT_ESCAPES.merge(
+        '"' => "&quot;",
+        "\t" => "&#x9;",
+        "\n" => "&#xA;",
+      ).freeze
+
+      def encode_text(text)
+        text.to_s.gsub(/[&<>\r]/, TEXT_ESCAPES)
+      end
+
+      def encode_attribute(value)
+        value.to_s.gsub(/[&<"\t\n\r]/, ATTRIBUTE_ESCAPES)
+      end
+    end
+  end
+end

data/lib/moxml/c14n/data_model.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Moxml
+  module C14n
+    # Builds a C14N data model from a Moxml::Node tree (or XML string).
+    #
+    # The data model exists because canonicalization needs:
+    #   - sorted namespace and attribute axes (spec §2.3, §2.4)
+    #   - in_node_set flags for subset canonicalization (spec §3)
+    #   - xml:* inheritable attribute resolution
+    #
+    # Ported from canon (lutaml/canon) — adapted to build directly from
+    # Moxml::Node rather than via a separate Nokogiri pass. Matches
+    # canon's document-level node iteration (PIs and comments outside
+    # the document root element).
+    class DataModel
+      def self.from_xml(xml_string)
+        from_node(::Moxml.parse(xml_string))
+      end
+
+      def self.from_node(moxml_node)
+        return build_from_document(moxml_node) if moxml_node.is_a?(::Moxml::Document)
+
+        root = Nodes::RootNode.new
+        root.add_child(build_node(moxml_node))
+        root
+      end
+
+      # Build from a Moxml::Document. Matches canon's Nokogiri path:
+      # the root element is added first, then all other document-level
+      # children (PIs, comments) in document order.
+      def self.build_from_document(document)
+        root = Nodes::RootNode.new
+
+        if document.root
+          root.add_child(build_element_node(document.root))
+          # Iterate ALL document children — not just the root element.
+          # This captures PIs and comments that appear outside the
+          # document element, which are part of the canonical form.
+          document.children.each do |child|
+            next if child.equal?(document.root)
+            next if child.is_a?(::Moxml::Element)
+
+            built = build_node(child)
+            root.add_child(built) if built
+          end
+        end
+
+        root
+      end
+
+      def self.build_node(moxml_node)
+        case moxml_node
+        when ::Moxml::Element then build_element_node(moxml_node)
+        when ::Moxml::Text then build_text_node(moxml_node)
+        when ::Moxml::Comment then build_comment_node(moxml_node)
+        when ::Moxml::ProcessingInstruction then build_pi_node(moxml_node)
+        end
+      end
+
+      def self.build_element_node(moxml_element)
+        ns = moxml_element.namespace
+        element = Nodes::ElementNode.new(
+          name: moxml_element.name,
+          namespace_uri: ns&.uri,
+          prefix: ns&.prefix,
+        )
+
+        build_namespace_nodes(moxml_element, element)
+        build_attribute_nodes(moxml_element, element)
+
+        moxml_element.children.each do |child|
+          built = build_node(child)
+          element.add_child(built) if built
+        end
+
+        element
+      end
+
+      def self.build_namespace_nodes(moxml_element, element)
+        moxml_element.in_scope_namespaces.each do |ns|
+          element.add_namespace(
+            Nodes::NamespaceNode.new(prefix: ns.prefix || "", uri: ns.uri),
+          )
+        end
+
+        return if element.namespace_nodes.any? { |n| n.prefix == "xml" }
+
+        element.add_namespace(
+          Nodes::NamespaceNode.new(prefix: "xml", uri: XML_URI),
+        )
+      end
+
+      def self.build_attribute_nodes(moxml_element, element)
+        moxml_element.attributes.each do |attr|
+          ns = attr.namespace
+          element.add_attribute(
+            Nodes::AttributeNode.new(
+              name: attr.name,
+              value: attr.value,
+              namespace_uri: ns&.uri,
+              prefix: ns&.prefix,
+            ),
+          )
+        end
+      end
+
+      def self.build_text_node(moxml_text)
+        Nodes::TextNode.new(value: moxml_text.content)
+      end
+
+      def self.build_comment_node(moxml_comment)
+        Nodes::CommentNode.new(value: moxml_comment.content)
+      end
+
+      def self.build_pi_node(moxml_pi)
+        Nodes::ProcessingInstructionNode.new(
+          target: moxml_pi.target || moxml_pi.name,
+          data: moxml_pi.content || "",
+        )
+      end
+
+      def self.mark_all(node, value)
+        node.in_node_set = value
+        node.children.each { |child| mark_all(child, value) }
+      end
+
+      def self.mark_subset(root_node, matched)
+        matched.each { |node| mark_node_and_descendants(node) }
+        root_node.in_node_set = true
+      end
+
+      def self.mark_node_and_descendants(node)
+        node.in_node_set = true
+        node.children.each { |child| mark_node_and_descendants(child) }
+      end
+
+      private_class_method :build_from_document, :build_node,
+                           :build_element_node, :build_namespace_nodes,
+                           :build_attribute_nodes, :build_text_node,
+                           :build_comment_node, :build_pi_node,
+                           :mark_node_and_descendants
+    end
+  end
+end