XMLDSIGjs

XML Digital Signature implementation in TypeScript/JavaScript using Web Crypto API.

Installation

npm install xmldsigjs

Features

• Complete XMLDSIG implementation
• Support for RSA, ECDSA, and HMAC algorithms
• Multiple canonicalization methods
• Cross-platform: browsers and Node.js
• TypeScript support

Algorithm Support

Cryptographic Algorithms

| | SHA1 | SHA2-256 | SHA2-384 | SHA2-512 | | ----------------- | ---- | -------- | -------- | -------- | | RSASSA-PKCS1-v1_5 | ✓ | ✓ | ✓ | ✓ | | RSA-PSS | ✓ | ✓ | ✓ | ✓ | | ECDSA | ✓ | ✓ | ✓ | ✓ | | HMAC | ✓ | ✓ | ✓ | ✓ |

Canonicalization

• C14N (Canonical XML)
• C14N with Comments
• Exclusive C14N
• Exclusive C14N with Comments
• Enveloped Signature Transform
• Base64 Transform

Quick Start

Node.js Setup

Note: Use ESM modules (.mjs extension or "type": "module" in package.json).

import * as xmldsigjs from 'xmldsigjs';
import { Crypto } from '@peculiar/webcrypto';

xmldsigjs.Application.setEngine('NodeJS', new Crypto());

Browser Setup

<script type="module">
import * as xmldsigjs from "https://unpkg.com/xmldsigjs@latest/dist/esm/index.js";
</script>

Signing XML

import * as xmldsigjs from 'xmldsigjs';
import { Crypto } from '@peculiar/webcrypto';

xmldsigjs.Application.setEngine('NodeJS', new Crypto());

async function signXML() {
  // Generate key pair
  const keys = await crypto.subtle.generateKey(
    {
      name: "RSASSA-PKCS1-v1_5",
      modulusLength: 2048,
      publicExponent: new Uint8Array([1, 0, 1]),
      hash: "SHA-256"
    },
    false,
    ["sign", "verify"]
  );

  // Parse XML document
  const xml = xmldsigjs.Parse('<root><data>Hello World</data></root>');

  // Create signature
  const signedXml = new xmldsigjs.SignedXml();
  await signedXml.Sign(
    { name: "RSASSA-PKCS1-v1_5" },
    keys.privateKey,
    xml,
    {
      keyValue: keys.publicKey,
      references: [{ hash: "SHA-256", transforms: ["enveloped", "c14n"] }]
    }
  );

  console.log(signedXml.toString());
}

Verifying XML

import * as xmldsigjs from 'xmldsigjs';

async function verifyXML(signedXmlString) {
  const doc = xmldsigjs.Parse(signedXmlString);
  const signatures = doc.getElementsByTagNameNS(
    'http://www.w3.org/2000/09/xmldsig#',
    'Signature'
  );

  const signedXml = new xmldsigjs.SignedXml(doc);
  signedXml.LoadXml(signatures[0]);

  const isValid = await signedXml.Verify();
  console.log('Signature valid:', isValid);
}

API Reference

SignedXml.Sign()

Sign(
  algorithm: Algorithm,
  key: CryptoKey,
  data: Document,
  options?: OptionsSign
): Promise<Signature>

Options:

interface OptionsSign {
  id?: string;                          // Signature ID
  keyValue?: CryptoKey;                 // Public key for KeyInfo
  x509?: string[];                      // X.509 certificates
  references?: OptionsSignReference[];  // Reference elements
}

SignedXml.Verify()

Verify(key?: CryptoKey): Promise<boolean>

Node.js: Registering XML Dependencies

To work with XML in Node.js, you need to register DOM and XPath dependencies:

import * as xmldom from '@xmldom/xmldom';
import { setNodeDependencies } from 'xmldsigjs';
import xpath from 'xpath';

setNodeDependencies({
  XMLSerializer: xmldom.XMLSerializer,
  DOMParser: xmldom.DOMParser,
  DOMImplementation: xmldom.DOMImplementation,
  xpath,
});

WebCrypto Environment

Node.js >=19 ships a built‑in WebCrypto. For Node.js 16/18 or to ensure consistent behavior across environments, you can use:

import { Crypto } from '@peculiar/webcrypto';
import { Application } from 'xmldsigjs';
Application.setEngine('NodeJS', new Crypto());

License

MIT