Lockbox for Node.js

Simple, strong encryption.

Installation and documentation

Available as NPM package lockbox.
API documentation available.

What is Lockbox?

Lockbox is the simplest possible way to implement strong, two-way, public-key encryption for use in applications. Lockbox uses a combination of well-established technologies to ensure the safety of data. For more information, see the Lockbox website.

Usage

Generating keys via OpenSSL

Lockbox uses RSA keys in PEM format. This is a standard format understood by OpenSSL. Generating of keys is normally handled by the openssl command line tool (although Lockbox can also generate keys programmatically). Generating a 2048-bit private key can be achieved with this command:

openssl genrsa -out private.pem 2048

Private keys can have password protection. To create a key with a password, simply add the -des3 flag, which will prompt for password input before the key is created:

openssl genrsa -des3 -out private.pem 2048

This private key must be kept secret, and treated as sensitive data. Private keys are the only keys capable of decrypting data. Public keys, on the other hand, are not as sensitive, and can be given to any party that will be responsible for encrypting data.

Lockbox is capable of extracting public keys from private keys, there is no need to create matching public key files; but if for some reason a public key file is required, this command will create one:

openssl rsa -pubout -in private.pem -out public.pem

Generating keys programmatically

var lockbox = require('lockbox');

var key = lockbox.keyFactory.generatePrivateKey();

Encrypting data

var lockbox = require('lockbox');

var data = 'Super secret data.';

var key = lockbox.keyFactory.createPrivateKeyFromFileSync(
    '/path/to/key.pem',
    'password'
);
var encrypted = lockbox.encrypt(key, data);

Encrypting multiple data packets with the same key

Lockbox includes 'bound' ciphers that are locked to a particular key. These type of ciphers are convenient for encrypting multiple data packets.

var lockbox = require('lockbox');

var data = [
    'Super secret data.',
    'Extra secret data.',
    'Mega secret data.'
];

var key = lockbox.keyFactory.createPrivateKeyFromFileSync(
    '/path/to/key.pem',
    'password'
);
var cipher = new lockbox.BoundEncryptionCipher(key);

var encrypted = [];
for (var i = 0; i < data.length; ++i) {
    encrypted.push(cipher.encrypt(data[i]));
}

Decrypting data

var lockbox = require('lockbox');

var encrypted = '<some encrypted data>';

var key = lockbox.keyFactory.createPrivateKeyFromFileSync(
    '/path/to/key.pem',
    'password'
);

var data;
try {
    data = lockbox.decrypt(key, encrypted);
} catch (error) {
    // decryption failed
}

Decrypting multiple data packets with the same key

Lockbox includes 'bound' ciphers that are locked to a particular key. These type of ciphers are convenient for decrypting multiple data packets.

var lockbox = require('lockbox');

var encrypted = [
    '<some encrypted data>',
    '<more encrypted data>',
    '<other encrypted data>'
];

var key = lockbox.keyFactory.createPrivateKeyFromFileSync(
    '/path/to/key.pem',
    'password'
);
var cipher = new lockbox.BoundDecryptionCipher(key);

var decrypted = [];
for (var i = 0; i < encrypted.length; ++i) {
    try {
        decrypted.push(cipher.decrypt(encrypted[i]));
    } catch (error) {
        // decryption failed
    }
}

eloquent/lockbox-nodejs