basic-crypto

Basic, high-level, opnionated crypto suite. ⁰

This module lets you encrypt and decrypt strings in your Node.js application. It's goal is to be a simplified interface to the many, sometimes confusing, methods of the crypto module.

Features:

• dependency-free -- except node's internal crypto module ¹
• simple api -- encrypt(plaintext) & decrypt(cypherText)
• message authentication -- turn on by setting {integrity: true}
• encryption and hash keys pinning, or generating them on-the-fly
• tested -- my first atempt at a "decently tested" module ²
• secure -- protected against HMAC timing attack, uses PRNG IV, etc
• convenient useage -- methods provides both sync and async signatures
• very small codebase -- easy to examine
• proper key stretching -- safe to handle user provided criptographic keys ³
• truly async methods -- leverage streaming crypto functions ⁴

Install

$ npm install --save basic-crypto

Usage

Constructor

This module provides a regular js constructor, which is initializated with options. For conveinience it can be called with or without the new keyword.

var basicCrypto = require('basic-crypto')(options)

is the same as

var BasicCrypto = require('basic-crypto')
var basicCrypto = new BasicCrypto(options)

for options, see "Modes"

Methods

There are only two methods in each instance, the function signature is the same:

syncronous: accepts only one argument. ⁵

var plainText = 'any string, multibyte support, etc'
var encrypted = basicCrypto.encrypt(plainText)
var decrypted = basicCrypto.decrypt(encrypted)
console.log(decrypted === plainText) //true

asyncronous: accepts only an argument and a standard node callback.

var plainText = 'any string, multibyte support, etc'
basicCrypto.encrypt(plainText, function(err, encrypted){
    basicCrypto.decrypt(encrypted, function(err, decrypted){
        console.log(decrypted === plainText) //true
    })
})

Modes

This module can operate, transparently, in two distinct ways:

• "Encrypt only"
• "Encrypt then sign"

Encrypt only

This is the default behaviour, but it's advisable to only use it in already signed enviroments, as encryption alone doesn't guarantees the origin and/or the integrity of the data.

A possible use case is inside a JWT, to encrypt a property.

valid options:

• key: [string, optional] Set a fixed cryptographic key. ⁶

Encrypt then sign

The second method is enabled by passing {integrity: true} to the constructor. After encrypting, it will append an HMAC of the encrypted text to the end of the block. When decrypting this block, it will first check the HMAC signature, and then decrypt it. When any "weird thing" occurs in either phase, the process is halted with an error.

valid options:

• key: [string, optional] Set a fixed cryptographic key. ⁶
• integrity: [boolean, required] To enable signing this property must be true.
• hmacKey: [string, optional] set a fixed signing key. ⁶
• hmacSize: [integer, optional] truncate signature to this length.

Error handling

• Syncronous invocations will throw an error if something goes awry.
• Asyncronous invocations follows node style callback, (err, result).

Compatibility

• node: v4.0.0 or later

Tests

$ npm install
$ npm test

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. Contact-me personally instead.

Author

Leonardo Dino

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Footnotes

⁰ As usual, everything is provided "AS-IS", no liability, but I might be using this code in production. Shhhh. ↩
¹ And some usual test module, as dev-dependency. ↩
² Accepting pull requests of unit tests for the helper library. ↩
³ Accepting pull requests of a method implementing pbkdf2. ↩
⁴ Unfortunelly this leads to code duplication, as the sync methods can't support it. ↩
⁵ Syncronous code should be always wraped inside a try-catch block, as any erros are thrown. ↩
⁶ A fixed key is useful when talking to other processes, or storing the key for later. When not provided a key will be generated randomly on the fly, but it's not possible to access this value, and it's unique in each instantiation. ↩