AWS KMS decrypt / encrypt cli

A helper tool to decrypt encrypt data through AWS KMS service. Decryption and Encryption can be done through a cli or in the codebase with the KMS class.

Installation

npm install

Usage

General use

The idea is to use the so called Envelope Encryption proposed by AWS KMS. In short the steps are.

1. Create masterkey in AWS KMS
2. Generate datakey with masterkey id and store it ENCRYPTED! locally
3. Decrypt the datakey through KMS and encrypt files locally with decrypted datakey as key
4. Decrypt the datakey through KMS and decrypt files locally with decrypted datakey as key

Do not store the decrypted datakey but keep it in memory only as long as you need it

Use KMS in code

const { KMS } = require('./lib');
const KeyId = '123-456-789';

const kms = new KMS(KeyId);
// uses global aws credentials
kms.encryptData('foo')
    .then(({ CiphertextBlob }) => {
        // returns a buffer
        console.log(CiphertextBlob.toString('base64'));
    }, err => console.error(err));

kms.decryptData('encryptedBase64Foo')
    .then(({ Plaintext }) => {
        // returns a buffer
        console.log(Plaintext.toString());
    }, err => console.error(err));

// you could always wrap the functions into an async functions to have an synchronous workflow
decryptAsync();

async function decryptAsync() {
  const { CiphertextBlob } = await kms.encryptData('foo');
  const { Plaintext } = await kms.decryptData(CiphertextBlob);
  console.log({ decryptedSecret: Plaintext.toString() });
}

Use CRYPT in code

const { Crypt } = require('./lib');

// you should use a decrypted KMS masterkey as key
const crypt = new Crypt('decryptedMasterKeyValue');

const encryptedFoo = crypt.encrypt('foo');
const decryptedFoo = crypt.decrypt(encryptedFoo);

Use crypt command globally

npm install -g && npm link

Use locally

./cli/crypt.js [options]

Access Help Menus

# global
crypt -h
crypt [encrypt|decrypt|get-datakey|encrypt-local|decrypt-local] -h

# local
./cli/crypt.js -h
./cli/crypt.js [encrypt|decrypt|get-datakey|encrypt-local|decrypt-local] -h

Following args are used to create the AWS.KMS instance in encrypt and decrypt:

{
    -r: 'region',
    -a: 'accessKeyId',
    -s: 'secretAccessKey',
    -t: 'sessionToken'
}

if the accessKeyId, secretAccessKey or sessionToken is omitted the globally stored aws credentials are used

encrypt

crypt encrypt -k 123-456-789 dataToEncrypt ~/fileToEncrypt

crypt -k 123-456-789 -p ~/Desktop dataToEncrypt ~/fileToEncrypt

Additional valid args.

{
    -k: 'KeyId', // required!!
    -p: 'Path' // if results should be stored in binary file - specify path
}

files have to begin with "./", "/" or "~/" the results are displayed as base64 string in console

decrypt

crypt decrypt dataToEncrypt ~/fileToEncrypt

files have to begin with "./", "/" or "~/" data strings have to be base64 encrypted

get-datakey

Generate datakey with given aws masterkey and store it in binary - encrypted file.

crypt get-datakey -k 123-456-789

crypt -k 123-456-789 -p ~/Desktop

Additional valid args.

{
    -k: 'KeyId', // required!!
    -p: 'Path' // if results should be stored in binary file - specify path
}

the results are displayed as strings in console

encrypt-local

Encrypt datakey locally with given aws datakey. It makes a call to kms, decrypts the datakey and encrypts with it the data. (AWS credentials have to be setup and masterkey active)

crypt encrypt-local dataToEncrypt ~/fileToEncrypt -d dataKey

crypt encrypt-local dataToEncrypt ~/fileToEncrypt -d dataKey -p ~/Desktop

Additional valid args.

{
    -d: 'DataKey', // path to encrypted datakey - required!!
    -p: 'Path' // if results should be stored in file - specify path
}

files have to begin with "./", "/" or "~/" the results are displayed as base64 string in console

decrypt-local

Decrypt datakey locally with given aws datakey. It makes a call to kms, decrypts the datakey and encrypts with it the data. (AWS credentials have to be setup and masterkey active)

crypt decrypt-local dataToEncrypt ~/fileToEncrypt -d dataKey

crypt decrypt-local dataToEncrypt ~/fileToEncrypt -d dataKey -p ~/Desktop

Additional valid args.

{
    -d: 'DataKey', // path to encrypted datakey - required!!
    -p: 'Path' // if results should be stored in file - specify path
}

files have to begin with "./", "/" or "~/" the results are displayed as base64 string in console

Requirements

• This project needs node > 6.
• Valid aws credentials have to be set up globally or passed as arguments
• For the tests to work you need to create a kms keyId you have access and use rights to and enter it in ./config.js

License

MIT

© mycs 2015

Maintainer

jroehl

TODO

• write tests for crypt
• documentation

Whenever editing the repository

Should you update the readme, use npm script semantic-release to check if a new version has to be set and to publish it to npm.