moxml 0.1.25 → 0.2.0

data/docs/signature/architecture.md

@@ -0,0 +1,148 @@
+# Moxml::Signature — Architecture
+
+## Where it lives
+
+`Moxml::Signature` is a sub-module of moxml that implements W3C XML
+Signature (xmldsig-core-1.1). It is **XML implementation agnostic** —
+every XML operation flows through `Moxml::Document` / `Moxml::Element`,
+so the same signature code works whether you parse with Nokogiri, Oga,
+REXML, Ox, or LibXML.
+
+C14N itself is a top-level `Moxml::C14n` feature, sibling to
+`Moxml::XPath`, `Moxml::Builder`, and `Moxml::SAX`. Signature uses it;
+so can any other consumer (e.g., the sibling `canon` gem).
+
+## Module layout
+
+```
+lib/moxml.rb                              # top-level, autoloads Signature and C14n
+lib/moxml/signature.rb                    # Signature namespace + .sign/.verify entry points
+
+lib/moxml/signature/errors.rb             # error hierarchy
+lib/moxml/signature/algorithms.rb         # OCP registry hub
+lib/moxml/signature/algorithms/           # concrete algorithms (digests, sig methods, transforms)
+lib/moxml/signature/model/                # PORO models
+lib/moxml/signature/serializer.rb         # model → XML (uses moxml primitives)
+lib/moxml/signature/parser.rb             # XML → model
+lib/moxml/signature/reference_resolver.rb # Reference URI → node-set / octets
+lib/moxml/signature/transform_pipeline.rb # shared transform chain (DRY)
+lib/moxml/signature/signer.rb             # spec §3.1 signing flow
+lib/moxml/signature/verifier.rb           # spec §3.2 verification flow
+lib/moxml/signature/key_extractor.rb      # X509 / RSA / DSA / EC / KeyName → OpenSSL key
+lib/moxml/signature/verification_result.rb
+lib/moxml/signature/single_verification_result.rb
+lib/moxml/signature/reference_result.rb
+
+lib/moxml/c14n.rb                         # top-level C14n namespace
+lib/moxml/c14n/                           # canon-ported engine + moxml-native Exclusive
+```
+
+## Layering
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ Application code                                                 │
+│   Moxml::Signature.sign / .verify                                │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Orchestration:  Signer, Verifier, TransformPipeline, KeyExtractor│
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────┐   ┌──────────────────────────────────────┐
+│ Algorithms (OCP hub) │   │ Models: Signature, SignedInfo, etc.  │
+└──────────────────────┘   └──────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Moxml::C14n (canon-ported Inclusive + moxml-native Exclusive)    │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Moxml::Document / Element / Text / Namespace / Attribute          │
+│   (adapter-agnostic — Nokogiri, Oga, REXML, Ox, LibXML)           │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+                          OpenSSL (crypto)
+```
+
+## Core design decisions
+
+### 1. Algorithm registry as the OCP hub
+
+Every W3C algorithm (digest, signature method, canonicalization,
+transform) is identified by URI. The `Moxml::Signature::Algorithms`
+module is the registry; adding a new algorithm means:
+
+1. Subclass the relevant base (`DigestBase`, `SignatureMethodBase`,
+   `CanonicalizationBase`, `TransformBase`).
+2. Declare `identifier "http://..."` on the subclass.
+3. Add an autoload entry in `algorithms.rb` and a reference in
+   `load_builtins!`.
+
+No edits to existing code. The registry has four categories:
+`:digest`, `:signature_method`, `:canonicalization`, `:transform`.
+
+### 2. Models are POROs; serialization is a service
+
+Models (`Model::Signature`, `Model::SignedInfo`, `Model::Reference`,
+etc.) are plain Ruby objects with `attr_accessor`. They do **not** own
+their wire shape. A dedicated `Serializer` translates model → XML using
+moxml primitives; `Parser` translates XML → model. This keeps the data
+shape and the wire shape independent, and matches the user's global
+rule ("no hand-rolled serialization on model classes").
+
+### 3. Signer / Verifier orchestrate, don't compute
+
+`Signer` walks the references, delegates to the transform pipeline,
+computes digests via `DigestMethod` instances, and signs the
+canonicalized SignedInfo. It contains no algorithm-specific logic.
+
+`Verifier` follows Best Practice 1: authenticate SignatureValue first,
+then run reference transforms. Errors are captured into the result
+object (`SingleVerificationResult#error`), not raised, so a malicious
+signature cannot panic the application.
+
+### 4. TransformPipeline is shared by Signer and Verifier
+
+The transform-chain logic (lookup algorithm, coerce input type, apply,
+repeat) is the same for signing and verifying. It lives in
+`TransformPipeline` — DRY.
+
+### 5. C14N is shared infrastructure
+
+Inclusive C14N is ported from `~/src/lutaml/canon` (mature, ~1,200
+lines, full node-set subset support, xml:base fixup, xml:* inheritable
+attribute resolution). Exclusive C14N is moxml-native (canon doesn't
+implement it). Both expose the same `#canonicalize(node, with_comments:,
+inclusive_namespaces:)` interface.
+
+## Adapter-agnostic invariant
+
+Every XML operation — parse, walk, serialize, canonicalize — goes
+through `Moxml::Node`. The signature module never imports Nokogiri,
+Oga, REXML, Ox, or LibXML directly. Switching adapters does not change
+signature behavior.
+
+The one exception is the `context:` parameter threaded through every
+constructor. When a transform receives octet-stream input, it parses
+with the same adapter the caller used (`context.parse(...)`), preserving
+byte-exact canonicalization across adapters.
+
+## Cross-verification
+
+`spec/fixtures/xmldsig/sign2-result.xml` and `sign3-result.xml` are
+real libxmlsec1-produced signatures (from the Ruby
+`nokogiri-xmlsec-instructure` reference). Both verify byte-exact against
+`Moxml::Signature.verify`, proving the C14N and signing logic matches a
+battle-tested C implementation.
+
+## What this module deliberately doesn't do
+
+- **XPath Filter transform** — Best Practice 5 says avoid. The Enveloped
+  Signature transform walks ancestors directly, no XPath needed.
+- **XSLT transform** — Best Practice 3 says avoid. Disabled.
+- **External URI dereferencing** — Best Practice 8 says constrain.
+  Applications must provide their own resolver.
+- **X.509 chain validation** — application responsibility (trust policy).
+- **XML Encryption** — separate spec (xmlenc-core-1.1).
+- **XAdES** — separate spec (ETSI TS 101 903).

data/docs/signature/c14n.md

@@ -0,0 +1,110 @@
+# Canonicalization (C14N)
+
+Canonicalization is the load-bearing primitive for XML signature.
+Two documents that differ only in surface representation (whitespace,
+attribute order, namespace prefix choice) must produce identical
+canonical bytes — otherwise signatures won't verify.
+
+`Moxml::C14n` is a top-level moxml feature, sibling to `Moxml::XPath`,
+`Moxml::Builder`, and `Moxml::SAX`.
+
+## Algorithms
+
+### Inclusive C14N 1.0 / 1.1
+
+- W3C: <https://www.w3.org/TR/xml-c14n/>, <https://www.w3.org/TR/xml-c14n11/>
+- Implementation: **ported from `~/src/lutaml/canon`** (~1,200 lines)
+- Files: `lib/moxml/c14n/inclusive_10.rb`, `inclusive_11.rb`,
+  `data_model.rb`, `processor.rb`, `namespace_handler.rb`,
+  `attribute_handler.rb`, `xml_base_handler.rb`, `character_encoder.rb`,
+  `node.rb`, `nodes/*.rb`
+- "Attracts" ancestor context: at the apex, every in-scope namespace is
+  rendered, including those inherited from outside the canonicalization
+  subset.
+
+### Exclusive C14N 1.0
+
+- W3C: <https://www.w3.org/TR/xml-exc-c14n/>
+- Implementation: **moxml-native** (canon does not implement exclusive)
+- Files: `lib/moxml/c14n/exclusive.rb`, `writer.rb`, `namespace_context.rb`
+- "Repels" ancestor context: only namespaces visibly used by the apex
+  element's qualified name or attributes are rendered. Keeps signatures
+  valid when subdocuments are moved between XML contexts (e.g., into a
+  SOAP envelope).
+
+## Public API
+
+```ruby
+# Convenience: inclusive C14N 1.0
+Moxml::C14n.canonicalize(node_or_xml, with_comments: false)
+# → canonical UTF-8 octet String
+
+# Convenience: exclusive C14N 1.0
+Moxml::C14n.canonicalize_exclusive(
+  node_or_xml,
+  with_comments: false,
+  inclusive_namespaces: [],  # InclusiveNamespacesPrefixList parameter
+)
+# → canonical UTF-8 octet String
+
+# Direct engine access (used by signature algorithms)
+Moxml::C14n::Inclusive10.new.canonicalize(node, with_comments:, inclusive_namespaces:)
+Moxml::C14n::Inclusive11.new.canonicalize(node, with_comments:, inclusive_namespaces:)
+Moxml::C14n::Exclusive.new.canonicalize(node, with_comments:, inclusive_namespaces:)
+```
+
+`node_or_xml` accepts a `Moxml::Node`, `Moxml::Document`, or XML `String`.
+
+## Data model
+
+The canon-derived inclusive C14N walks an intermediate data model
+(`Moxml::C14n::Nodes::*`) rather than the live `Moxml::Node` tree. This
+is because canonicalization needs:
+
+- **Node-set membership flags** for subset canonicalization (spec §3).
+  Same-document references select a node-set; only selected nodes are
+  rendered.
+- **Sorted namespace and attribute axes** per spec §2.3 / §2.4.
+- **xml:base fixup** per RFC 3986 with C14N 1.1 modifications.
+- **xml:* inheritable attribute resolution** (xml:lang, xml:space) from
+  omitted ancestors.
+
+The data model is built from `Moxml::Node` via `Moxml::C14n::DataModel`.
+
+## Output invariants
+
+All algorithms produce canonical octets with these properties:
+
+- UTF-8 encoded, no BOM
+- NFC characters preserved
+- Document-order traversal
+- Entity references: `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`
+- Attribute values: also escape `"`, tab, LF, CR
+- Empty elements expanded: `<foo/>` → `<foo></foo>`
+- Line endings normalized to LF (XML parser already does this)
+
+## Why not delegate to Nokogiri's native C14N?
+
+Nokogiri (via libxml2) has both inclusive and exclusive C14N built-in,
+and it's much faster than pure Ruby. But:
+
+1. **XML-agnosticity.** Moxml's whole point is that switching adapters
+   doesn't change behavior. If C14N were Nokogiri-only, Oga/REXML/Ox
+   users would get no canonicalization.
+2. **Adapter-coupled canonicalization breaks cross-adapter signature
+   verification.** A signature produced with Nokogiri must verify with
+   Oga — same canonical bytes.
+3. **Canon already had the mature pure-Ruby implementation.** Porting it
+   was less work than building a hybrid adapter-delegated system.
+
+**Future work:** add an optional adapter-level C14N delegation. The
+Nokogiri adapter could expose `canonicalize(node, ...)` and the
+`Moxml::C14n` top-level method would delegate when available. This is
+documented in TODO.complete/19.
+
+## Cross-verification
+
+The libxmlsec1-produced fixtures in `spec/fixtures/xmldsig/` verify
+byte-exact against our C14N output. This proves the implementation
+matches libxml2's C-based canonicalization for the cases the Ruby
+reference exercises.

data/docs/signature/examples.md

@@ -0,0 +1,109 @@
+# Examples
+
+Runnable examples live in `examples/signature/`. Run with:
+
+```bash
+bundle exec ruby examples/signature/enveloped_rsa.rb
+bundle exec ruby examples/signature/hmac.rb
+bundle exec ruby examples/signature/auto_key_extraction.rb
+```
+
+## Minimal enveloped RSA-SHA256 signature
+
+```ruby
+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>")
+
+# Sign — produces a Model::Signature
+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"],
+)
+
+# Serialize the signature into XML and attach to the document
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+puts doc.to_xml
+```
+
+## Verify with the public key
+
+```ruby
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key: key,   # private key works; public key alone is enough
+)
+
+puts "Valid: #{result.valid?}"
+puts "Signature count: #{result.signature_count}"
+result.results.each do |r|
+  puts "  signature_valid=#{r.signature_valid?}"
+  r.references.each { |ref| puts "    ref #{ref.uri.inspect}: #{ref.valid?}" }
+end
+```
+
+## Auto-extract key from X509Certificate
+
+```ruby
+# sign3-result.xml embeds the signing certificate in KeyInfo.
+# No explicit key is needed — the Verifier extracts it automatically.
+doc = ctx.parse(File.read("spec/fixtures/xmldsig/sign3-result.xml"))
+result = Moxml::Signature.verify(context: ctx, document: doc)
+puts "Auto-extracted: #{result.valid?}"
+```
+
+## KeyName-based key resolution
+
+```ruby
+# Signer used <KeyName>my-key</KeyName>; verifier resolves via key_map:
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key_map: { "my-key" => trusted_public_key },
+)
+```
+
+## HMAC with truncation
+
+```ruby
+signature = Moxml::Signature.sign(
+  context: ctx,
+  document: doc,
+  key: "shared-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"],
+)
+```
+
+HMAC `OutputLength` truncation below `max(hash_bits/2, 80)` is rejected.
+
+## Adding a custom algorithm
+
+```ruby
+class MyDigest < Moxml::Signature::Algorithms::DigestBase
+  identifier "http://example.com/my-digest"
+
+  def compute_digest(data)
+    OpenSSL::Digest.digest("SHA3-256", data)
+  end
+end
+
+# Now usable in any Reference#digest_method
+```

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
+```