Node.js crypto-extra

Adds convenience methods to the native Node.js crypto module. It is a drop in replacement, meaning it extends the original functionality with additional methods.

• Getting Started
• API
  • encrypt
  • decrypt
  • hash
  • bcrypt
  • random
  • all other native crypto methods
• Testing and Contributing

Why?

The native crypto module requires a lot of boilerplate to do things such as hashing and encryption. This takes care of the boilerplate allowing much cleaner code.

Getting Started

npm install crypto-extra -g

To use in your project, simply require into your project as you would the crypto module, and go crazy!

/* with ES5 */
var crypto = require('crypto-extra')
/* with ES6 */
import crypto from 'crypto-extra'
/* with ES6 destructuring */
import { hash, random } from 'crypto-extra'

API

.encrypt(value, [secretKey])

Encrypts a value using AES256-CTR.

• value The value you want to encrypt. Supports strings, numbers, and objects.
• secretKey Optional. The secret key used to encrypt your value. Will fallback to the environment variable ENCRYPTION_KEY, and will throw an error if a secret key isn't provided or is not an environment variable.

/* encrypt a string */
var encrypted = crypto.encrypt('my-message', 'secret-key')

/* encrypt an object */
var encrypted = crypto.encrypt({foo: 'bar'}, 'secret-key')

.decrypt(value, [secretKey])

Decrypts a value that was encrypted using AES256-CTR.

• value The encrypted string you want to decrypt.
• secretKey Optional. The secret key used to encrypt your value. Will fallback to the environment variable ENCRYPTION_KEY.

var decrypted = crypto.decrypt('af1ed6d214', 'secret-key')

.hash(value, [options])

Hashes a string with the provided algorithm.

• value The value you want to hash.
• options
  • salt Will be appended to the string before it is hashed.
  • algorithm [default: SHA256] The hashing algorithm to use.

var hashed = crypto.hash('my-message') // SHA256
var hashed = crypto.hash('my-message', { salt: 'this-is-a-salt' }) // SHA256 with salt
var hashed = crypto.hash('my-message', { algorithm: 'MD5' }) // MD5

.bcrypt(value, [hashToCompare])

Returns a promise with the hash. If comparing a string to a hash, it will return a boolean.

• value The value you want to hash with bcrypt
• hashToCompare Optional value. If provided, it will attempt to validate the hash. (ex. comparing a password to a hashed value in the database).

/* to hash */
crypto.bcrypt('my-password')
  .then(function(hash) {
    /* do what you will with the hash */
  })

/* to validate a hash */
var hash = '$2a$10$4aIbKI4tBwDxoHeLMsuPseVsLyIL/PgDgVz2K5MwyM9jWbjYDbAZW'
crypto.bcrypt('my-password', hash)
  .then(function(isValid) {
    /* isValid will be true or false */
  })

.random(length)

Returns a random string of any defined length.

• length [default: 10] The length of the string you want. Must be an integer above 0.

/* random string with default length (10) */
var randomString = crypto.random()

/* with length of 20 */
var randomString = crypto.random(20)

Testing and Contributing

git clone https://github.com/jsonmaur/node-crypto-extra.git
cd node-crypto-extra
npm install
npm test

crypto-extra is built with ES2015 features, so Babel compilation is necessary. Run npm run build to transpile.

If you want to contribute or come across an issue that you know how to fix, just do it.