moxml 0.1.25 → 0.1.26

data/docs/signature/flows.md

@@ -0,0 +1,132 @@
+# Signing and verification flows
+
+## Signer (spec §3.1)
+
+```
+Moxml::Signature.sign(context:, document:, key:, **options)
+        │
+        ▼
+build a Model::Signature with the requested algorithms
+        │
+        ▼
+Signer#sign
+        │
+        ├── for each Reference in SignedInfo:
+        │     ├── ReferenceResolver.resolve(uri)        → node or octets
+        │     ├── TransformPipeline.apply(input, transforms)
+        │     ├── TransformPipeline.to_octets(transformed, reference)
+        │     └── DigestMethod#digest_base64(canonical) → Reference#digest_value
+        │
+        ├── Serializer.serialize_signed_info(signed_info)  → Moxml::Document
+        ├── CanonicalizationMethod#canonicalize(signed_info_root) → octets
+        └── SignatureMethod#sign(canonical_octets, key)   → SignatureValue
+```
+
+The Signer never touches algorithms directly — every step delegates to
+the algorithm registry. This is OCP: new algorithms are added without
+touching the Signer.
+
+## Verifier (spec §3.2 + Best Practice 1)
+
+```
+Moxml::Signature.verify(context:, document:, key: nil, key_map: {})
+        │
+        ▼
+find all ds:Signature elements in the document
+        │
+        ▼ for each Signature
+verify_one(signature_element)
+        │
+        ├── Parser.parse(signature_element)   → Model::Signature
+        │
+        ├── verify_signature_value FIRST   (Best Practice 1)
+        │     ├── find original SignedInfo element (do NOT re-serialize)
+        │     ├── CanonicalizationMethod#canonicalize(signed_info_elem)
+        │     ├── resolve_key(signature)   (KeyExtractor if no key:)
+        │     └── SignatureMethod#verify(canonical, key, sig_value)
+        │
+        └── if signature value verifies:
+              for each Reference:
+                ├── ReferenceResolver.resolve(uri)
+                ├── TransformPipeline.apply(...)
+                ├── TransformPipeline.to_octets(...)
+                └── DigestMethod#digest_base64 vs Reference#digest_value
+```
+
+### Best Practice 1: authenticate before transforms
+
+The verifier deliberately runs `SignatureValue` validation BEFORE
+applying any transforms. Reason: a malicious signature could include
+XSLT or expensive XPath transforms. Best Practice 1 says only run
+those after authenticating the signer.
+
+If `SignatureValue` doesn't verify, we skip reference transforms
+entirely. The result object reports `signature_valid?: false` and
+`references: []`.
+
+### Why we canonicalize the original element
+
+The verifier canonicalizes the SignedInfo **as it appears in the
+document**, not a re-serialized model. Reason: re-serialization could
+change namespace prefixes (e.g., default-namespace SignedInfo might
+become `ds:SignedInfo`), breaking the byte-exact match the signature
+was computed against.
+
+The Signer serializes (it has to — it's building new XML). The Verifier
+has the original element from the document and uses it directly. This
+asymmetry is intentional and necessary for cross-verification with
+libxmlsec1-produced signatures.
+
+### Errors are captured, not raised
+
+`SingleVerificationResult#error` carries any `VerificationError` or
+`UnknownAlgorithm` that caused failure. The verifier returns a result
+object rather than raising, so a hostile signature cannot panic the
+application. Use `result.results.first.error` for debugging.
+
+## Key resolution
+
+```ruby
+Moxml::Signature.verify(context:, document:)  # no key:
+```
+
+When no `key:` is passed, the Verifier uses `KeyExtractor` to derive
+one from the signature's `KeyInfo`:
+
+1. **X509Certificate** (preferred) — decode base64 DER →
+   `OpenSSL::X509::Certificate` → `.public_key`
+2. **RSAKeyValue** — reconstruct via ASN.1 (OpenSSL 3.x dropped
+   `RSA.new(n, e)`)
+3. **DSAKeyValue** — reconstruct via ASN.1
+4. **ECKeyValue** — build SubjectPublicKeyInfo DER for the named curve
+   (OpenSSL 3.x made PKey immutable)
+6. **KeyName** — look up in the application-supplied `key_map:`
+
+OpenSSL 3.x compatibility notes are inline in `key_extractor.rb`.
+
+## Transform pipeline
+
+`TransformPipeline` is shared by Signer and Verifier. Each Transform
+in the chain declares `input_type` (`:octets` or `:nodeset`) and
+`output_type`; the pipeline coerces types between transforms per
+spec §4.4.3.2:
+
+- `octets → nodeset`: parse as XML via the caller's `context:`
+- `nodeset → octets`: apply inclusive C14N 1.0
+
+Final conversion to octets (for digesting) uses the last canonicalization
+transform in the chain if any, else inclusive C14N 1.0 as the spec default.
+
+## Result objects
+
+```ruby
+result = Moxml::Signature.verify(context:, document:, key:)
+result.valid?              # → bool (all signatures valid)
+result.signature_count     # → Integer
+result.results             # → [SingleVerificationResult, ...]
+result.results.first.signature_valid?
+result.results.first.references       # → [ReferenceResult, ...]
+result.results.first.references.first.valid?
+result.results.first.error            # → Exception or nil
+result.failing            # → [SingleVerificationResult, ...]
+```

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/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