cryptian

MCrypt compatible crypto wrapper for Node.js

Provides the ciphers, block cipher modes and paddings that libmcrypt had, including the ones OpenSSL never exposed, so data written by PHP mcrypt can still be read after its removal in PHP 7.2.

Migrating from PHP? See docs/migrating-from-php-mcrypt.md. It maps every mcrypt constant onto this library and covers the three things that most often go wrong: MCRYPT_RIJNDAEL_256 is a 256 bit block and is not AES-256, mcrypt_encrypt() padded with null bytes rather than PKCS#7, and the mcrypt mode names do not line up with the OpenSSL ones (cfb is 8 bit, ncfb is the full block variant).

Intended use

These algorithms exist to read existing data. Most of them are obsolete and several are broken. None of the modes here authenticate, so ciphertext can be altered without detection. For new work use an AEAD construction such as AES-GCM from node's built-in crypto, and treat this library as a migration tool: decrypt once, re-encrypt with something modern.

Modes hold their algorithm

A mode refers to the algorithm you give it rather than copying it, and keeps it alive for as long as the mode exists, so this is safe:

const cipher = new mode.cbc.Cipher(new algorithm.Rijndael128(), iv);

Two consequences follow. Several modes can share one algorithm instance. And calling setKey on an algorithm changes the behaviour of every mode already using it, since the mode holds the algorithm and not a snapshot of its key schedule. Rekey deliberately, or build a separate algorithm per mode.

Known limitations

encrypt and decrypt on an algorithm object take exactly one block and throw otherwise. Empty input is a no operation and returns an empty buffer. They are a single block primitive. For anything longer, or anything not a whole number of blocks, use a mode: the mode slices the input, calls the algorithm once per block, and a padding class handles the remainder.

// one block, fine
rijndael.encrypt(Buffer.alloc(16));

// longer or unaligned data goes through a mode
const cipher = new mode.cbc.Cipher(rijndael, iv);
const padder = new padding.Pkcs7(cipher.getBlockSize());

cipher.transform(padder.pad(plaintext));

The addon registers with NODE_MODULE, which is not context aware, so it can be initialized only once per process. If the main thread has loaded cryptian, a worker_threads worker that requires it fails with Module did not self-register. A worker can load it only when the main thread has not.

This matters for bulk work, which is the common case here: re-encrypting a large table is the obvious thing to parallelize across workers. Until the binding moves to Node-API, split that work across processes rather than threads.

Making the module context aware means moving the per class Nan::Persistent function templates out of static storage first. Marking it context aware without that would replace a clear error with shared state across contexts, which is worse.

See CHANGELOG.md for recent changes, including fixes that affect existing data.

Install

Using NPM

npm install --save cryptian

Using Yarn

yarn add cryptian

Basic Usage With Transform Stream Support

Check out the test folder to find out the different ways to use it.

Block Algorithm Encryption

const fs = require('fs');
const {default: {algorithm, mode}, padding, createEncryptStream} = require('cryptian');

const key = Buffer.from('0a0c0e1012141618', 'hex');
const iv = Buffer.from('ca40f5af0b1aeea2', 'hex');

const des = new algorithm.Des();
des.setKey(key);

const cipher = new mode.cbc.Cipher(des, iv);

fs.createReadStream('test.png')
    .pipe(createEncryptStream(cipher, padding.Pkcs5))
    .pipe(fs.createWriteStream('test.png.encrypted'));

Block Algorithm Decryption

const fs = require('fs');
const {default: {algorithm, mode}, padding, createDecryptStream} = require('cryptian');

const key = Buffer.from('0a0c0e1012141618', 'hex');
const iv = Buffer.from('ca40f5af0b1aeea2', 'hex');

const des = new algorithm.Des();
des.setKey(key);

const cipher = new mode.cbc.Decipher(des, iv);

fs.createReadStream('test.png.encrypted')
    .pipe(createDecryptStream(cipher, padding.Pkcs5))
    .pipe(fs.createWriteStream('test-decrypted.png'));

Available Crypto Algorithms

All the following crypto algorithms ported from libmcrypt

Block Cipher

• Blowfish
• CAST-128
• CAST-256
• DES
• GOST
• LOKI97
• RC2
• Rijndael-128 (AES-128)
• Rijndael-192
• Rijndael-256
• SAFER
• SAFER+
• 3-Way
• 3DES
• XTEA

Basic Usage

const assert = require('assert');
const {default: {algorithm}} = require('cryptian');
const des = new algorithm.Des();

des.setKey(Buffer.from('0a0c0e1012141618', 'hex'));

const ciphertext = Buffer.from('a1502d70ba1320c8', 'hex');
const plaintext  = Buffer.from('0001020304050607', 'hex');

assert(ciphertext.equals(des.encrypt(plaintext)), 'encrypted plaintext should equal to ciphertext');
assert(plaintext.equals(des.decrypt(ciphertext)), 'decrypted ciphertext should equal to plaintext');

Stream Cipher

• RC4 (Arcfour)
• Enigma
• WAKE

Basic Usage

const assert = require('assert');
const {default: {algorithm}} = require('cryptian');

const enigma = new algorithm.Enigma();

enigma.setKey(Buffer.from('enadyotr', 'ascii'));

const ciphertext = Buffer.from('f3edda7da20f8975884600f014d32c7a08e59d7b', 'hex');
const plaintext  = Buffer.from('000102030405060708090a0b0c0d0e0f10111213', 'hex');

assert(ciphertext.equals(enigma.encrypt(plaintext)), 'encrypted plaintext should equal to ciphertext');
assert(plaintext.equals(enigma.decrypt(ciphertext)), 'decrypted ciphertext should equal to plaintext');

Available Block Cipher Mode Algorithms

All the following block cipher mode algorithms ported from libmcrypt

| cryptian | width | PHP mcrypt | OpenSSL | | --- | --- | --- | --- | | cbc | block | MCRYPT_MODE_CBC | aes-128-cbc | | pcbc | block | none | none | | cfb | 8 bit | MCRYPT_MODE_CFB | aes-128-cfb8 | | ncfb | block | 'ncfb' | aes-128-cfb | | ctr | block | 'ctr' | aes-128-ctr | | ecb | block | MCRYPT_MODE_ECB | aes-128-ecb | | ofb | 8 bit | MCRYPT_MODE_OFB | none | | nofb | block | MCRYPT_MODE_NOFB | aes-128-ofb |

Note that OpenSSL's aes-128-cfb is the full block variant and corresponds to ncfb, not cfb, and that aes-128-ofb corresponds to nofb, not ofb. These pairings are verified in test/openssl.

Basic Usage

const assert = require('assert');
const {default: {algorithm, mode}} = require('cryptian');

const plaintext  = Buffer.from('88cc3d134aee5660f7623cf475fe9df20f773180bd70b0ef2aae00910ba087a1', 'hex');
const ciphertext = Buffer.from('ace98b99e6803c445b8bb76d937ea1b654fc86ed2e0e11597e52867c25ae96f8', 'hex');

const iv = Buffer.from('2425b68aac6e6a24', 'hex');

// don't use Dummy algorithm in real production environment 
// because this is not an encryption algorithm
const dummy = new algorithm.Dummy(); 

const cipher = new mode.cbc.Cipher(dummy, iv);
assert(ciphertext.equals(cipher.transform(plaintext)), 'transformed plaintext should be equal to ciphertext');

const decipher = new mode.cbc.Decipher(dummy, iv);
assert(plaintext.equals(decipher.transform(ciphertext)), 'transformed ciphertext should be equal to plaintext');

Available Block Cipher Padding Algorithms

• ANSI-x923
• ISO-10126
• ISO-7816
• NULL bytes
• PKCS5
• PKCS7
• Space character bytes

Basic Usage

const assert = require('assert');
const {padding} = require('cryptian');

const padder = new padding.Pkcs5(8);
const padded = Buffer.from('0575ba559d030303', 'hex');
const unpadded = Buffer.from('0575ba559d', 'hex');

assert(padded.equals(padder.pad(unpadded)));
assert(unpadded.equals(padder.unpad(padded)));

License