Basic, high-level, opnionated crypto suite. 0
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.
- dependency-free -- except node's internal
crypto
module 1 - 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 2
- 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 3
- truly async methods -- leverage streaming crypto functions 4
$ npm install --save basic-crypto
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"
There are only two methods in each instance, the function signature is the same:
syncronous: accepts only one argument. 5
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
})
})
This module can operate, transparently, in two distinct ways:
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. 6
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. 6integrity:
[boolean, required]
To enable signing this property must betrue
.hmacKey:
[string, optional]
set a fixed signing key. 6hmacSize:
[integer, optional]
truncate signature to this length.
- Syncronous invocations will throw an error if something goes awry.
- Asyncronous invocations follows node style callback,
(err, result)
.
node:
v4.0.0
or later
$ npm install
$ npm test
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.
This project is licensed under the MIT license. See the LICENSE file for more info.
0
As usual, everything is provided "AS-IS", no liability, but I might be using this code in production. Shhhh. ↩
1
And some usual test module, as dev-dependency. ↩
2
Accepting pull requests of unit tests for the helper library. ↩
3
Accepting pull requests of a method implementing pbkdf2. ↩
4
Unfortunelly this leads to code duplication, as the sync methods can't support it. ↩
5
Syncronous code should be always wraped inside a try-catch block, as any erros are thrown. ↩
6
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. ↩