aes-kit v1.0.0

AES-KIT

An es6 version of Richard Moore's pure JavaScript implementation of the AES block cipher algorithm and all common modes of operation (CBC, CFB, CTR, ECB and OFB).

Features

• Pure JavaScript (with no dependencies)
• Supports all key sizes (128-bit, 192-bit and 256-bit)
• Supports all common modes of operation (CBC, CFB, CTR, ECB and OFB)
• Works in node.js

API

Node.js

To install aes-kit in your node.js project:

npm install aes-kit

And to access it from within node, simply add:

const aesKit = require('aes-kit');

Keys

All keys must be 128 bits (16 bytes), 192 bits (24 bytes) or 256 bits (32 bytes) long. To generate keys from simple-to-remember passwords, consider using a password-based key-derivation function such as scrypt or bcrypt.

Common Modes of Operation

There are several modes of operations, each with various pros and cons. In general though, the CBC and CTR modes are recommended. The ECB is NOT recommended., and is included primarily for completeness.

CTR - Counter (recommended)

const
	{Ctr, Counter} = require('aes-kit'),
	key = 'Example128BitKey',

	// "Text may be any length you wish, no padding is required."
	text = 'Text may be any length you wish, no padding is required.',

	// The counter is optional, and if omitted will begin at 0
	encrypted = (new Ctr(key, new Counter(5))).encrypt(text),

	// The counter mode of operation maintains internal state, so to
	// decrypt a new instance must be instantiated.
	decrypted = (new Ctr(key)).decrypted(encrypted);

console.log(decrypted);

CBC - Cipher-Block Chaining (recommended)

const
	{Cbc, pkcs7} = require('aes-kit'),
	key = 'Example128BitKey',
	text = pkcs7.pad('The text must be padded'),
	iv = 'IVMustBe16Bytes',
	encrypted = (new Cbc(key, iv)).encrypt(text),

	// The cipher-block chaining mode of operation maintains internal
	// state, so to decrypt a new instance must be instantiated.
	decrypted = pkcs7.strip((new Cbc(key, iv)).decrypt(encrypted));

console.log(decrypted);

CFB - Cipher Feedback

const
	{Cfb, pkcs7} = require('aes-kit'),
	key = 'Example128BitKey',
	text = pkcs7.pad('The text must be padded to a multiple of segment size'),

	// The initialization vector, which must be 16 bytes
	iv = 'IVMustBe16Bytes',

	// The segment size is optional, and defaults to 1
	encrypted = (new Cfb(key, iv, 8)).encrypt(text),

	// The cipher feedback mode of operation maintains internal state,
	// so to decrypt a new instance must be instantiated.
	decrypted = pkcs7.strip((new Cfb(key, iv, 8)).decrypt(encrypted));

console.log(decrypted);

OFB - Output Feedback

const
	{Ofb} = require('aes-kit'),
	key = 'Example128BitKey',
	text = 'Text may be any length you wish, no padding is required.',

	// The initialization vector, which must be 16 bytes
	iv = 'IVMustBe16Bytes',

	encrypted = (new Ofb(key, iv)).encrypt(text),

	// The output feedback mode of operation maintains internal state,
	// so to decrypt a new instance must be instantiated.
	decrypted = (new Ofb(key, iv)).decrypt(encrypted);

console.log(decrypted);

ECB - Electronic Codebook (NOT recommended)

This mode is not recommended. Since, for a given key, the same plaintext block in produces the same ciphertext block out, this mode of operation can leak data, such as patterns. For more details and examples, see the Wikipedia article, Electronic Codebook.

const
	{Ecb, pkcs7} = require('aes-kit'),
	key = 'Example128BitKey',
	text = pkcs7.pad('Text must be padded'),
	// Since electronic codebook does not store state, we can
	// reuse the same instance.
	ecb = new Ecb(key),

	encrypted = ecb.encrypt(text),
	decrypted = pkcs7.strip(ecb.decrypt(encrypted));

console.log(decrypted);

Notes

What is a Key

This seems to be a point of confusion for many people new to using encryption. You can think of the key as the "password". However, these algorithms require the "password" to be a specific length.

With AES, there are three possible key lengths, 128-bit (16 bytes), 192-bit (24 bytes) or 256-bit (32 bytes). When you create an AES object, the key size is automatically detected, so it is important to pass in a key of the correct length.

Often, you wish to provide a password of arbitrary length, for example, something easy to remember or write down. In these cases, you must come up with a way to transform the password into a key of a specific length. A Password-Based Key Derivation Function (PBKDF) is an algorithm designed for this exact purpose.

Here is an example, using the popular (possibly obsolete?) pbkdf2:

var pbkdf2 = require('pbkdf2');

var key_128 = pbkdf2.pbkdf2Sync('password', 'salt', 1, 128 / 8, 'sha512');
var key_192 = pbkdf2.pbkdf2Sync('password', 'salt', 1, 192 / 8, 'sha512');
var key_256 = pbkdf2.pbkdf2Sync('password', 'salt', 1, 256 / 8, 'sha512');

Another possibility, is to use a hashing function, such as SHA256 to hash the password, but this method is vulnerable to Rainbow Attacks, unless you use a salt.

TODO

Tests!