SecretKMS

Overview

This is a Javascript/Node.js library that leverages Amazon KMS and Amazon S3 to provide a secure way to encrypt and decrypt secrets (Strings) such that your data encryption keys are stored separately and themselves encrypted by a KMS customer master key.

This is a common requirement for PCI DSS compliance - this approach has been used to pass PCI Audits by payments companies hosting on AWS.

Terminology and Concepts

http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html

How it Works

Encryption:

1. A request is made to S3 to retrieve an encrypted data key.

2. If the key DOES exist, it is retrieved and decrypted using KMS.

3. If the key DOES NOT exist, a new encrypted key is requested from KMS and stored in S3.

4. The data key is used to encrypt the secret locally. The decrypted key is only ever kept in memory for the duration of the operation.

5. The encrypted data is returned along with the data key name, data key version, and master key name.

Decryption:

1. A request is made to S3 to retrieve an encrypted data key.

2. The data key is decrypted using KMS.

3. The data key is used to decrypt the data locally. The decrypted key is only ever kept in memory for the duration of the operation.

4. The decrypted secret is returned.

Why It's Safe

• Keys are stored in a highly reliable location (s3)
• Keys are stored separately from the encrypted data (s3)
• Keys are encrypted using a master key (KMS)
• Keys can be encrypted and decrypted only by KMS

Even if an attacker downloads your data AND your keys they cannot decrypt your data without KMS access

Initialization

Create an instance providing your AWS credentials and config:

const secretkms = require('secretkms')({
    accessKey: 'AKIAIMGERGY46EXAMPLE',
    secretKey: 'aX45RdV0FRSPEKh44FpvCksQV8eT2aj6REXAMPLE',
    masterKey: '9b64aaa7-ce47-4dac-8830-e0da1EXAMPLE',
 
    region: 'us-east-1',
    bucket: 'application-secretkms',
});

Encrypt

const encryptedData = await secretkms.encrypt('foo is my secret', keyName);

This returns an object:

{
  "data":"uSQfQ1z0RbFbUXL/hOgRTIBlCPuotLvgByzw4BtFnQo=",
  "key":{
    "masterKey":"9b64aaa7-ce47-4dac-8830-e0da1EXAMPLE",
    "name":"MY_DATA_KEY_NAME_EG_USER_UUID",
    "version":"EZcPuxOQ9wyrSn0ROxWOIrOsToBSJ2Zw"
  }
}

Note: You should store this entire object in your database as the "encrypted secret"!!!

Decrypt

const decryptedSecret = await secretkms.decrypt(encryptedData, keyName);

This returns an object:

{
  "secret": "foo is my secret"
}

Building

This client is written with ES 2017 features like async await.

To make it compatible to a wider audience, I have transpiled to a ES 2015 profile with Babel.

If you need to rebuild this, just run yarn install then yarn build.

The transpiled file and source map end up in /dist.

Infrastructure

As an example, a terraform file has been provided that will create the necessary IAM User, S3 bucket(s) and KMS key. To install terraform on a mac, use brew install terraform.

Note: You will need to edit setup.tf and include an Adminsitrator AWS ACCESS KEY and AWS SECRET KEY to allow terraform to construct resources.

To preview the infrastructure:

$ terraform plan

To create some infrastructure

$ terraform apply

The output of terraform will give you three configuration values you will need to use this client:

Outputs:
 
accessKey = AKIAIAU4UPRNXEXAMPLE
secretKey = 2iSBp4vfZ5Simu5yeOAbeW9X/g5wvGQc-EXAMPLE
kmsCustomerMasterKey = 300054ea-f7ad-46f9-9162-3fd83EXAMPLE