This library provides methods to encrypt and decrypt values using envelope encryption for node.js.
- Simple API Methods for encrypting and decrypting all types of data
- Using a Key Management Service (KMS) of your choice. (See Implementation Status)
- Bring your own key or use a key provided by Cryptari
API Documentation can be found here
To explain envelope encryption the following terms need to be defined and scoped:
- Master Key: Also known as Customer Master Key. This is the encryption key used to encrypt and decrypt DataKeys
- Data Key: An encryption key used to encrypt your data.
- KMS: Short for Key Manamagement Service, is a (internet) service which provides service methods for creating keys and encrypting and decrypting data.
The flow for envelope encryption is the following:
- Ask the KMS to generate a new DataKey. It will return two values. An unecrypted data key and an encrypted data key.
- Encrypt your data with the unencrypted DataKey
- Store your encrypted data alongside with the encrypted data key.
- Forget the unecrypted data key
The flow for envelope decryption is the reverse:
- Take your encrypted data key and ask the KMS to decrypt it for you
- Use the unecrypted data key to decrypt you encrypted data
The advantages of this approach are:
- Your master key is never exposed and is protected by the KMS
- You store only encrypted values
- Only users/services with access to the master key can decrypt data
Envelope encryption does not protect you from someone who has gained access to your servers
But it does protect you from somebody who gained access of your stored data.
- AWS
- Local Encryption (not intended for production use)
- Microsoft
- Telekom
- Alibaba
npm install cryptari --save
If you plan to use only one cryptari instance, all you need to do is set default enviroments variables, as describe in the following sections
If no options are given and no environment variables are found, cryptari-node will use a hardcoded and totally insecure local master key. This is fine for local development.
const Cryptari = require('cryptari');
const cryptari = new Cryptari({local:{masterKey:'A16ByteHexString'}});
By either setting the CRYPTARI_LOCAL_MASTERKEY
environment varaiable or passing the a 16 Byte Hex String key, a cryptari instance will use this key to encrypt and decrypt values.
const Cryptari = require('cryptari');
const cryptari = new Cryptari({local:{masterKey:'A16ByteHexString'}});
DO NOT ADD ANY OF THE IDS/SECRETS TO YOUR SOURCE CODE!
Cryptari will auto-decect the following environments variables for AWS KMS
CRYPTARI_AWS_ACCESS_KEY_ID
The IAM User Id with acccess to the below keyCRYPTARI_AWS_SECRET_ACCESS_KEY
The matching secret of the IAM UserCRYPTARI_AWS_CMK_ID
The Id of the AWS master keyCRYPTARI_AWS_REGION
The region where the above master key is stored
Alternatively you can pass an options object as follows:
const Cryptari = require('cryptari');
const cryptari = new Cryptari({
aws:{
accessKeyId:'...',
secretAccessKey:'...',
cmkKeyId:'...',
region:'...',
}
});
cryptari.encryptValue('Encrypt Me').then((encrypted)=>{
console.log(encrypted);
/// --> _cryptari.7f94f53730b61fd97823d8a8c804d25fc8847505daa8e925b34891bf908d6dad.dc2ec5bcd41a410adbe0.string.4213342259
cryptari.decryptValue(encrypted).then((decrypted){
console.log(decrypted);
// --> 'Encrypt Me'
});
});
const testObject = {
foo:'Original',
bar:'Secret'
}
cryptari.encryptObject(testObject,['bar']).then(()=>{
console.log(JSON.stringify(testObject,2,2));
// property bar will be encrypted, property foo will be untouched
// -->
// {
// "foo": "Original",
// "bar": "_cryptari.7c6400980252c620a45e110b7d11213ab7fb74143603cac7adf834b161521531.a166af24c9c8.string.3137411440"
// }
cryptari.decryptObject(testObject,['bar']).then(()=>{
console.log(JSON.stringify(testObject,2,2));
// property bar will be decrypted, property foo will be untouched
// -->
// {
// "foo": "Original",
// "bar": "Secret"
// }
});
});
const Promise = require('bluebird');
function testGenerator () {
return Promise.coroutine(function*() {
let encrypted = yield cryptari.encryptValue('test');
console.log(encrypted);
})();
}
const Promise = require('bluebird');
function testGenerator () {
return Promise.coroutine(function*() {
let encrypted = yield cryptari.encryptValue('test');
console.log(encrypted);
})();
}
By default cryptari-node will always return the value given to the encrypt/decrypt method if encryption/decryption fails Alternatively you can also configure to cryptari to throw errors in the case of a failure. Set the following enviroment variables for this:
CRYPTARI_ENCRYPTION_ONERROR=throw
CRYPTARI_DECRYPTION_ONERROR=throw
You can also set these options on a per use case