{"id":15942,"library":"xml-encryption","title":"Node.js XML Encryption","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/auth0/node-xml-encryption","tags":["javascript","xml","encryption","xmlenc"],"install":[{"cmd":"npm install xml-encryption","lang":"bash","label":"npm"},{"cmd":"yarn add xml-encryption","lang":"bash","label":"yarn"},{"cmd":"pnpm add xml-encryption","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for XML parsing and manipulation within the encryption/decryption process.","package":"xmldom","optional":false}],"imports":[{"note":"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.","wrong":"import xmlenc from 'xml-encryption';","symbol":"xmlenc","correct":"const xmlenc = require('xml-encryption');"},{"note":"`encrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.","wrong":"import { encrypt } from 'xml-encryption';","symbol":"encrypt","correct":"xmlenc.encrypt(content, options, callback);"},{"note":"`decrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.","wrong":"import { decrypt } from 'xml-encryption';","symbol":"decrypt","correct":"xmlenc.decrypt(xml, options, callback);"}],"quickstart":{"code":"import { readFileSync } from 'node:fs';\nimport xmlenc from 'xml-encryption'; // Using import for modern TS/Node compatibility, despite CJS origin\n\nconst options = {\n  rsa_pub: readFileSync('./your_rsa.pub', 'utf8'),\n  pem: readFileSync('./your_public_cert.pem', 'utf8'),\n  encryptionAlgorithm: 'http://www.w3.org/2009/xmlenc11#aes256-gcm', // Recommended secure algorithm\n  keyEncryptionAlgorithm: 'http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p',\n  keyEncryptionDigest: 'sha256', // Stronger digest for OAEP\n  disallowEncryptionWithInsecureAlgorithm: true, // Recommended security posture\n  warnInsecureAlgorithm: true\n};\n\nconst contentToEncrypt = '<data>Secret information</data>';\n\nxmlenc.encrypt(contentToEncrypt, options, function(err: Error | null, result?: string) {\n  if (err) {\n    console.error('Encryption failed:', err);\n    return;\n  }\n  console.log('Encrypted XML:\\n', result);\n\n  const decryptOptions = {\n    key: readFileSync('./your_private_key.key', 'utf8'),\n    disallowDecryptionWithInsecureAlgorithm: true,\n    warnInsecureAlgorithm: true\n  };\n\n  if (result) {\n    xmlenc.decrypt(result, decryptOptions, function(err: Error | null, decryptedContent?: string) {\n      if (err) {\n        console.error('Decryption failed:', err);\n        return;\n      }\n      console.log('Decrypted content:\\n', decryptedContent);\n    });\n  }\n});\n\n// Placeholder for key files for demonstration purposes\n// In a real application, these would be securely generated and managed.\n// Example: create a self-signed cert for testing:\n// openssl genrsa -out your_private_key.key 2048\n// openssl rsa -in your_private_key.key -pubout -out your_rsa.pub\n// openssl req -new -x509 -key your_private_key.key -out your_public_cert.pem -days 365 -nodes -subj \"/CN=test\"\n","lang":"typescript","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your code to use the correct option name `keyEncryptionAlgorithm`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Avoid using Triple DES; migrate to modern and secure algorithms like AES-256-GCM for all encryption operations.","message":"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.","severity":"gotcha","affected_versions":"Any version of `xml-encryption` on Node.js >=18"},{"fix":"Migrate to recommended algorithms, specifically AES-GCM (e.g., `http://www.w3.org/2009/xmlenc11#aes256-gcm`).","message":"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.","severity":"gotcha","affected_versions":"All versions for RSA 1.5/3DES, >=4.0.0 for AES-CBC"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","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.","error":"Error: Unsupported algorithm: http://www.w3.org/2001/04/xmlenc#aes256-cbc. Consider setting disallowEncryptionWithInsecureAlgorithm to false."},{"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.","cause":"Attempting to use Triple DES (3DES) encryption or decryption on Node.js version 18 or higher, which no longer supports it.","error":"Error: error:00000000:lib(0):func(0):reason(0) when using Triple DES."},{"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(...)`.","cause":"Incorrect import or `require` of the `xml-encryption` library, or attempting to destructure `encrypt` directly from a CommonJS module.","error":"TypeError: xmlenc.encrypt is not a function"},{"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).","cause":"Using the insecure RSA 1.5 algorithm without explicitly allowing it via options.","error":"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."}],"ecosystem":"npm"}