keasy v0.4.0

Disclaimer

This library is meant to handle sensitive information. It's up to you to determine if you trust it or not. The functionality is limited and will remain so in an attempt to make it auditable and understandable.

Description

The goal is to get secrets out of source. A CLI is provided to encrypt and decrypt secrets using AWS's Key Management Service (KMS) as the key management infrastructure. Secrets can be any UTF-8 encoded text from passwords to server keys. For those using node it also exposes an API. The initial use case was to generate secrets via the CLI, pass them to AWS Lambda functions via env variables, and decrypt at runtime in the AWS Lambda function using the node API.

The library is not meant as a general wrapper for interacting with the AWS KMS service. It's purely meant to be used to secure secrets.

I recommend you reference the document AWS Key Management Service Concepts for definition of terms and concepts. I'll try to explain but the document does a better job than I could do.

Installation

% npm install -g keasy

AWS Account Definition

The AWS account is looked up with the following hierarchy:

• Within EC2 or Lambda via the IAM role if one exists.
• AWS profile defined via AWS_PROFILE env variable mapping to a credential in ~/.aws/credentials. If AWS_PROFILE is undefined the 'default' profile is used.

For details of how the SDK looks up credentials see Credentials in Nodejs.

Ways to execute:

• Using a defined profile

AWS_PROFILE=myprofile keasy ..
# or
export AWS_PROFILE=myprofile
keasy ...

• Using the default profile or profile defined with AWS role:

keasy ..

CLI Operations

Encrypt

% keasy encrypt xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx yoursecret
Encrypted Data Key (hex): 01010300786e71defa65e30f1e7bbe5775613ca61e62c1a26bd6c8d29dac3f1767d62311070000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040ca8770d7fb829f48adc30a858020110803b13c766f6581b3b26538769c5ee9fa3979e5efa1956a92ada1910e1f5865ae9778e0e5e63038c0c48c0379c8a1b07b319b5a390223c0122def8e457
Ciphertext (hex): 2759364818c5646933cb

The key is an identifier for the customer master key to use. The output of the command is an encrypted data key and the ciphertext (encrypted version of your secret) written to the console as hex in order to not run into shell expansion issues when passing to decrypt. With every call to encrypt a new data key will be created. AWS does not store or manage data keys. The assumption by the library is the data key is specific to the secret and should be stored along side the secret. I'm not against adding the ability to reuse data keys but at this point in time they're assumed to be cheap to create and store.

Decrypt

% keasy decrypt 01010300786e71defa65e30f1e7bbe5775613ca61e62c1a26bd6c8d29dac3f1767d62311070000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040ca8770d7fb829f48adc30a858020110803b13c766f6581b3b26538769c5ee9fa3979e5efa1956a92ada1910e1f5865ae9778e0e5e63038c0c48c0379c8a1b07b319b5a390223c0122def8e457 2759364818c5646933cb
yoursecret

The output of the command above is 'yoursecret' which was the original text in the encrypt operation. See the CLI help (--help) for more.

FAQ

Why is it named keasy?

"Keys" then "easy"... naming things is hard. Leave me alone.

What are the crypto details?

First and foremost I'm not a crypto engineer. Please read the source if curious. The following is not configurable at the time being but could be in the future.

• when requesting a data key from KMS the key spec used is AES_256.
• when encrypting the secret with the KMS generated data key it uses the aes-256-ctr algorithm.

Are you going to steal my secrets?

I don't intend to but it's up to you to audit the source and answer the question yourself. I don't plan to expand the library to provide any other functionality with the goal to keep it simple to audit.

What AWS permissions are needed to encrypt?

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

What AWS permissions are needed to decrypt?

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

How do you use it with serverless?

1. Encrypt a secret using the CLI.
2. Store the encrypted data key and ciphertext returned by the CLI in serverless env variables (in serverless.yml).
3. Decrypt using the node API:

import { decrypt } from 'keasy'

...

function decryptEnvVariable(name) {
  return new Promise(function (resolve, reject) {
    const variable = process.env[name]
    const key = process.env[name + "_key"]

    decrypt(new Buffer(key, 'hex'), new Buffer(variable, 'hex'), {region: 'us-east-1'}).then((decrypted) => {
      resolve(decrypted);
    }).catch(reject);
  });
}