Crate xml_canonical 

XML Canonicalization (C14N) library for Rust.

This library provides implementations of the W3C XML Canonicalization standards:

• Canonical XML 1.0 (C14N) - Standard canonicalization that preserves all namespace declarations in scope.
• Exclusive Canonical XML 1.0 (Exc-C14N) - Canonicalization that only outputs “visibly utilized” namespaces, commonly used for XML Digital Signatures.

Quick Start

use xml_canonical::{canonicalize, Algorithm};

let xml = r#"<root xmlns="http://example.com" id="1"><child/></root>"#;

// Using the simple API
let canonical = canonicalize(xml, Algorithm::C14n).unwrap();

// Using Exclusive C14N
let exclusive = canonicalize(xml, Algorithm::ExcC14n).unwrap();

Algorithms

Canonical XML 1.0

Standard canonicalization that:

• Outputs all namespace declarations that are in scope
• Sorts namespace declarations (default first, then by prefix)
• Sorts attributes (by namespace URI, then local name)
• Normalizes attribute values
• Converts empty elements to start-end tag pairs

Exclusive Canonical XML 1.0

Exclusive canonicalization that:

• Only outputs namespaces that are “visibly utilized”
• A namespace is visibly utilized if the element or an attribute uses that prefix
• Supports InclusiveNamespacesPrefixList for forcing certain namespaces

Advanced Usage

For more control, use the processor types directly:

use xml_canonical::{Document, C14nProcessor, C14nOptions};

let xml = "<root><!-- comment --></root>";
let doc = Document::parse(xml).unwrap();

// Canonicalize with comments included
let processor = C14nProcessor::new(C14nOptions::with_comments());
let result = processor.process(&doc).unwrap();
assert!(result.contains("<!-- comment -->"));

Subset Canonicalization

You can canonicalize a subset of nodes using node IDs:

use xml_canonical::{Document, C14nProcessor, C14nOptions};
use std::collections::HashSet;

let xml = "<root><a/><b/><c/></root>";
let doc = Document::parse(xml).unwrap();

// Create a node set (you would typically use XPath to select nodes)
let mut node_set = HashSet::new();
node_set.insert(0); // Document node
// Add other nodes as needed...

let options = C14nOptions::new().with_node_set(node_set);
let processor = C14nProcessor::new(options);
let result = processor.process(&doc).unwrap();

Structs

C14nOptions

Options for Canonical XML 1.0 processing.

C14nProcessor

Canonicalizes an XML document according to C14N 1.0.

Document

An XML document represented as a tree of nodes.

ExcC14nOptions

Options for Exclusive Canonical XML processing.

ExcC14nProcessor

Canonicalizes an XML document according to Exclusive C14N 1.0.

Enums

Algorithm

Canonicalization algorithm variants.

Error

Error type for XML canonicalization operations.

Node

Represents an XML node in the document tree.

Functions

c14n_canonicalize

Convenience function to canonicalize XML without comments.

canonicalize

Canonicalizes an XML string using the specified algorithm.

canonicalize_exclusive

Convenience function to canonicalize XML using Exclusive C14N without comments.

canonicalize_exclusive_with_comments

Convenience function to canonicalize XML using Exclusive C14N with comments.

canonicalize_exclusive_with_options

Canonicalizes an XML string with exclusive C14N and inclusive namespace prefixes.

canonicalize_exclusive_with_prefixes

Convenience function to canonicalize with inclusive prefixes.

canonicalize_to

Canonicalizes an XML string to a writer using the specified algorithm.

canonicalize_with_comments

Convenience function to canonicalize XML with comments.

Type Aliases

NodeId

Unique identifier for nodes in the document.

Result

Result type alias for canonicalization operations.