Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
xmlenc
✓ const xmlenc = require('xml-encryption');
✗ import xmlenc from '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
✓ xmlenc.encrypt(content, options, callback);
✗ import { encrypt } from 'xml-encryption';
`encrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.
decrypt
✓ xmlenc.decrypt(xml, options, callback);
✗ import { decrypt } from 'xml-encryption';
`decrypt` is a method on the default export object (`xmlenc`), not a named export. Direct named imports are not supported.
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"
Debug
Known issues
breakingVersion 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.fixUpdate 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).
affects: >=4.0.0
breakingVersion 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.fixEnsure 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.
affects: >=2.0.0
breakingVersion 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.fixUpdate your code to use the correct option name `keyEncryptionAlgorithm`.
affects: >=1.0.0
gotchaNode.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.fixAvoid using Triple DES; migrate to modern and secure algorithms like AES-256-GCM for all encryption operations.
affects: Any version of `xml-encryption` on Node.js >=18
gotchaThe 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.fixMigrate to recommended algorithms, specifically AES-GCM (e.g., `http://www.w3.org/2009/xmlenc11#aes256-gcm`).
affects: All versions for RSA 1.5/3DES, >=4.0.0 for AES-CBC
Errors
Common errors & fixes
Error: Unsupported algorithm: http://www.w3.org/2001/04/xmlenc#aes256-cbc. Consider setting disallowEncryptionWithInsecureAlgorithm to false.
Attempting to use AES-CBC with xml-encryption v4.0.0 or later without explicitly allowing insecure algorithms, which are now disallowed by default.
fixUpdate 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.
Attempting to use Triple DES (3DES) encryption or decryption on Node.js version 18 or higher, which no longer supports it.
fixMigrate 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
Incorrect import or `require` of the `xml-encryption` library, or attempting to destructure `encrypt` directly from a CommonJS module.
fixEnsure `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.
Using the insecure RSA 1.5 algorithm without explicitly allowing it via options.
fixMigrate 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).
Audit
Dependencies
xmldomrequiredCore dependency for XML parsing and manipulation within the encryption/decryption process.