Node.js XML Encryption

4.0.0 · active · verified Tue Apr 21

xml-encryption is a Node.js library that provides a W3C XML Encryption implementation. The current stable version is 4.0.0, released recently on March 31, 2026, indicating active development and maintenance. This library facilitates the encryption and decryption of XML documents, supporting various algorithms like AES-GCM, AES-CBC (with caveats), and RSA-OAEP-MGF1P for key transport. A key differentiator is its explicit handling of insecure cryptographic algorithms, defaulting to disallow them and providing warnings when they are used. Since version 2.0.0, it has transitioned to using native Node.js crypto functions, reducing external dependencies like `node-forge`. It focuses specifically on the XML Encryption standard, offering a robust solution for securing XML data in Node.js environments.

Common errors

```
Error: Unsupported algorithm: http://www.w3.org/2001/04/xmlenc#aes256-cbc. Consider setting disallowEncryptionWithInsecureAlgorithm to false.
```
cause Attempting to use AES-CBC with xml-encryption v4.0.0 or later without explicitly allowing insecure algorithms, which are now disallowed by default.

fix Update to a secure algorithm like AES-256-GCM (`http://www.w3.org/2009/xmlenc11#aes256-gcm`), or explicitly set `disallowEncryptionWithInsecureAlgorithm: false` in options (not recommended for production use).
```
Error: error:00000000:lib(0):func(0):reason(0) when using Triple DES.
```
cause Attempting to use Triple DES (3DES) encryption or decryption on Node.js version 18 or higher, which no longer supports it.

fix Migrate to a modern, secure algorithm such as AES-256-GCM. Triple DES is considered insecure and has been removed from newer Node.js versions.
```
TypeError: xmlenc.encrypt is not a function
```
cause Incorrect import or `require` of the `xml-encryption` library, or attempting to destructure `encrypt` directly from a CommonJS module.

fix Ensure `const xmlenc = require('xml-encryption');` is used, and then call `xmlenc.encrypt(...)`. For ESM, use `import xmlenc from 'xml-encryption';` and then `xmlenc.encrypt(...)`.
```
Error: Key encryption algorithm is not supported or not allowed: http://www.w3.org/2001/04/xmlenc#rsa-1_5. Consider setting disallowEncryptionWithInsecureAlgorithm to false.
```
cause Using the insecure RSA 1.5 algorithm without explicitly allowing it via options.

fix Migrate to a secure key encryption algorithm like RSA-OAEP (`http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p`), or explicitly set `disallowEncryptionWithInsecureAlgorithm: false` in options (not recommended).

Warnings

breaking Version 4.0.0 (March 2026) marks AES-128-CBC and AES-256-CBC as insecure algorithms due to their lack of integrity guarantees. The `disallowEncryptionWithInsecureAlgorithm` and `disallowDecryptionWithInsecureAlgorithm` options now default to `true`, preventing their use unless explicitly set to `false`. Users upgrading from v3.x and earlier will experience failures if these algorithms are in use without configuration.
Fix: Update encryption/decryption configurations to use recommended secure algorithms like `http://www.w3.org/2009/xmlenc11#aes256-gcm` or explicitly set `disallowEncryptionWithInsecureAlgorithm: false` and `disallowDecryptionWithInsecureAlgorithm: false` in options to re-enable (not recommended for production).
breaking Version 2.0.0 dropped support for Node.js 8 and replaced the `node-forge` dependency with native Node.js crypto functions. This change might introduce subtle behavioral differences or require Node.js version upgrades.
Fix: Ensure your Node.js environment is version 10 or newer (or Node 18+ for current usage). Review any custom logic or assumptions previously relying on `node-forge` specific behavior.
breaking Version 1.0.0 corrected a typo in the encryption options: `options.keyEncryptionAlgorighm` was changed to `options.keyEncryptionAlgorithm`. Using the old misspelled option will result in configuration errors.
Fix: Update your code to use the correct option name `keyEncryptionAlgorithm`.
gotcha Node.js 18 and newer versions do not support Triple DES (3DES) algorithms due to an upstream Node.js core issue (https://github.com/nodejs/node/issues/52017). Attempting to use `http://www.w3.org/2001/04/xmlenc#tripledes-cbc` on Node.js 18+ will cause runtime errors.
Fix: Avoid using Triple DES; migrate to modern and secure algorithms like AES-256-GCM for all encryption operations.
gotcha The library defaults to disallowing several insecure algorithms, including `http://www.w3.org/2001/04/xmlenc#rsa-1_5`, `http://www.w3.org/2001/04/xmlenc#tripledes-cbc`, and (since v4.0.0) `http://www.w3.org/2001/04/xmlenc#aes128-cbc` and `http://www.w3.org/2001/04/xmlenc#aes256-cbc`. While these can be re-enabled by setting `disallowEncryptionWithInsecureAlgorithm` or `disallowDecryptionWithInsecureAlgorithm` to `false`, it's strongly recommended to use secure alternatives like AES-GCM for strong security posture.
Fix: Migrate to recommended algorithms, specifically AES-GCM (e.g., `http://www.w3.org/2009/xmlenc11#aes256-gcm`).

Install

npm install xml-encryption npm
yarn add xml-encryption yarn
pnpm add xml-encryption pnpm

Imports

xmlenc
wrong:
```
import xmlenc from 'xml-encryption';
```
correct:
```
const xmlenc = require('xml-encryption');
```
This package primarily exposes a CommonJS module. While `import xmlenc from 'xml-encryption';` may work in some ESM contexts via transpilation or Node.js's CJS interoperability, `require()` is the canonical way to consume it.
encrypt
wrong:
```
import { encrypt } from 'xml-encryption';
```
correct:
```
xmlenc.encrypt(content, options, callback);
```
`encrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.
decrypt
wrong:
```
import { decrypt } from 'xml-encryption';
```
correct:
```
xmlenc.decrypt(xml, options, callback);
```
`decrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.

Quickstart

Demonstrates encrypting a simple XML string using recommended secure algorithms (AES-256-GCM and RSA-OAEP) and subsequently decrypting it. It highlights secure configuration practices and handles potential errors.

import { readFileSync } from 'node:fs';
import xmlenc from 'xml-encryption'; // Using import for modern TS/Node compatibility, despite CJS origin

const options = {
  rsa_pub: readFileSync('./your_rsa.pub', 'utf8'),
  pem: readFileSync('./your_public_cert.pem', 'utf8'),
  encryptionAlgorithm: 'http://www.w3.org/2009/xmlenc11#aes256-gcm', // Recommended secure algorithm
  keyEncryptionAlgorithm: 'http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p',
  keyEncryptionDigest: 'sha256', // Stronger digest for OAEP
  disallowEncryptionWithInsecureAlgorithm: true, // Recommended security posture
  warnInsecureAlgorithm: true
};

const contentToEncrypt = '<data>Secret information</data>';

xmlenc.encrypt(contentToEncrypt, options, function(err: Error | null, result?: string) {
  if (err) {
    console.error('Encryption failed:', err);
    return;
  }
  console.log('Encrypted XML:\n', result);

  const decryptOptions = {
    key: readFileSync('./your_private_key.key', 'utf8'),
    disallowDecryptionWithInsecureAlgorithm: true,
    warnInsecureAlgorithm: true
  };

  if (result) {
    xmlenc.decrypt(result, decryptOptions, function(err: Error | null, decryptedContent?: string) {
      if (err) {
        console.error('Decryption failed:', err);
        return;
      }
      console.log('Decrypted content:\n', decryptedContent);
    });
  }
});

// Placeholder for key files for demonstration purposes
// In a real application, these would be securely generated and managed.
// Example: create a self-signed cert for testing:
// openssl genrsa -out your_private_key.key 2048
// openssl rsa -in your_private_key.key -pubout -out your_rsa.pub
// openssl req -new -x509 -key your_private_key.key -out your_public_cert.pem -days 365 -nodes -subj "/CN=test"

view raw JSON →