This repository has been archived by the owner. It is now read-only.
Simple, strong encryption.
CoffeeScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib Started writing API documentation. Sep 11, 2013
src
test
.gitattributes Improved git config. [ci skip] Aug 25, 2013
.gitignore Started writing API documentation. Sep 11, 2013
.travis.after-success
.travis.before-install Attempting automated API publishing. Sep 12, 2013
.travis.key Attempting automated API publishing. Sep 12, 2013
.travis.yml Attempting automated API publishing. Sep 12, 2013
CHANGELOG.md
CONTRIBUTING.md Started implementing encryption cipher. Aug 23, 2013
LICENSE Started implementing encryption cipher. Aug 23, 2013
README.md Added link to API docs. [ci skip] Sep 12, 2013
makefile
npm-shrinkwrap.json Switch to istanbul for coverage. Sep 10, 2013
package.json Started writing API documentation. Sep 11, 2013
yuidoc.json Started writing API documentation. Sep 11, 2013

README.md

Lockbox for Node.js

Simple, strong encryption.

Build status Test coverage Uses semantic versioning

Installation and documentation

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
    }
}