xml-crypto

xml-crypto is a Node.js library that implements the W3C XML Signature (XMLDSig) and XML Encryption specifications, letting applications cryptographically sign, verify, and encrypt XML documents. It underpins SAML-based single sign-on flows, WS-Federation metadata exchange, and any protocol that needs tamper-evident XML, exposing a single SignedXml class that handles canonicalization, digest computation, and signature generation/verification against configurable algorithm registries.

Maintained under the node-saml GitHub organization (the same group behind node-saml/passport-saml and node-saml/node-saml), the library is a foundational dependency for the Node.js SAML ecosystem, where XML signature wrapping attacks make correct, spec-faithful signature verification a security-critical concern rather than a convenience feature.

What You Get

• A SignedXml class covering the full sign/verify lifecycle: addReference, computeSignature, loadSignature, checkSignature, getSignedXml, and getSignedReferences
• Built-in support for exclusive and non-exclusive XML canonicalization (C14N), with and without comments
• RSA-SHA1/SHA256/SHA256-MGF1/SHA512 signature algorithms plus optional HMAC-SHA1 for symmetric signing
• A getSignedReferences() API that returns only the canonicalized XML that was cryptographically verified, guarding against XML signature wrapping attacks
• An extensible algorithm registry (CanonicalizationAlgorithms, HashAlgorithms, SignatureAlgorithms) for registering custom transforms without forking the library
• X.509 / KeyInfo helpers for embedding and extracting public certificates from a signature

Common Use Cases

• Verifying signed SAML assertions and responses in an identity-provider or service-provider integration
• Signing outgoing XML payloads (invoices, WS-Federation metadata, SOAP messages) for tamper-evidence
• Implementing custom XMLDSig-based protocols that need pluggable canonicalization or signature algorithms
• Auditing or debugging XML signature validation failures in existing SAML/WS-Fed integrations

Under The Hood

Architecture The library centers on a single SignedXml class (src/signed-xml.ts) that orchestrates the full sign/verify lifecycle, delegating to focused single-responsibility modules — c14n-canonicalization.ts, exclusive-canonicalization.ts, enveloped-signature.ts, hash-algorithms.ts, and signature-algorithms.ts — each implementing one interchangeable piece of the XMLDSig pipeline. Extensibility is expressed through public registry maps (CanonicalizationAlgorithms, HashAlgorithms, SignatureAlgorithms) keyed by W3C namespace URI, so new algorithms are registered rather than requiring changes to core logic; this registry pattern is the load-bearing abstraction — if it changed shape, the documented “customizing algorithms” extension point would break. DOM parsing is deliberately not owned by the library: callers supply their own parsed document (typically via @xmldom/xmldom) and the xpath package for node selection, keeping the core stateless with respect to XML parsing.

Tech Stack Written in TypeScript, compiled with tsc and targeting Node.js 16+, the runtime dependency surface is intentionally minimal: xpath for XPath evaluation, @xmldom/xmldom for DOM parsing/serialization, and @xmldom/is-dom-node for type-narrowing DOM nodes, with all cryptographic operations (RSA, HMAC) delegated to Node’s built-in crypto module rather than a third-party crypto dependency. Tooling is conventional Node library tooling: ESLint with typescript-eslint, Prettier (extended with @prettier/plugin-xml), Mocha/Chai for tests, and nyc/Istanbul for coverage; GitHub Actions runs a lint job plus a test matrix across Node 16/18/20/latest and reports coverage to Codecov.

Code Quality Testing is extensive and specific — over a dozen spec files cover canonicalization variants (with/without comments, exclusive/non-exclusive), HMAC signing, KeyInfo handling, SAML response fixtures, WS-Federation metadata, and both unit- and integration-level signature tests, backed by fixture certificates under test/static/. Error handling favors explicit exceptions over silent failure (e.g. checkSignature throws rather than swallowing invalid-signature cases), and the codebase uses TypeScript’s deprecate() utility to actively warn callers off the unsafe .getReferences()/.references APIs in favor of the verified .getSignedReferences(), a security-conscious pattern rare outside signature-verification libraries. Lint and formatting are enforced as a separate CI job rather than left to convention.

What Makes It Unique xml-crypto is not attempting novel cryptography — it is a faithful, actively-maintained implementation of the W3C XMLDSig/XMLEnc specifications. Its distinguishing trait is defensive API design aimed squarely at a known, real-world attack class: the README explicitly documents XML signature wrapping attacks and steers integrators toward getSignedReferences() so only cryptographically-verified content is ever parsed for claims, rather than leaving that judgment call to the caller. Combined with enableHMAC()’s explicit disabling of asymmetric algorithms to prevent key-confusion attacks, the library encodes hard-won security lessons from the SAML ecosystem directly into its API surface rather than leaving them to documentation alone.