aws-kms-thingy

A wrapper/helper utility for encrypting/decrypting with AWS KMS

Usage no npm install needed!

<script type="module">
  import awsKmsThingy from 'https://cdn.skypack.dev/aws-kms-thingy';
</script>

README

aws-kms-thingy

Convenience wrapper around the AWS Node.js SDK to simplify encrypting/decrypting secrets with the AWS KMS service. Suitable for use with AWS Lambda.

CircleCI Coveralls David David GitHub release

Contents

  1. Features
  2. Usage
    1. With the CLI
    2. With AWS Lambda
    3. With Multiple Secrets
    4. Locally In Development
  3. API
  4. Related Thingies
  5. License

Features

  • Unencrypted strings simply returned, useful for testing/local development
  • Encrypt/decrypt multiple values in one go
  • Results are cached, so multiple decrypt/encrypt calls incur only a single call to the AWS SDK
  • CLI to encrypt/decrypt secrets
  • Well tested

Usage

The module assumes that the Amazon SDK has access to AWS credentials that are able to access the KMS key used for encryption and decryption.

npm install aws-kms-thingy aws-sdk@^2

With the CLI

Encrypt with:

aws-kms-thingy encrypt

You'll be prompted for the string to encrypt.

Decrypt with:

aws-kms-thingy decrypt

You'll be prompted for the encrypted string to decrypt.

With AWS Lambda

Safe to use within a Lambda handler. After cold-start, decrypted values are cached so subsequent invocations won't incur an AWS KMS API call:

const { decrypt } = require('aws-kms-thingy')

module.exports.myLambdaHandler = (event, context, callback) => {
  decrypt(process.env.SOME_API_TOKEN) // Only incurs network call on cold-start
    .then(doStuffWithDecryptedApiToken)
    .then(resultOrWhatever => callback(null, resultOrWhatever))
    .catch(callback)
}

With Multiple Secrets

Decrypt multiple values in parallel

import { decrypt } from 'aws-kms-thingy'

const [
  decryptedApiToken1,
  decryptedApiToken2,
  decryptedDatabasePassword,
  somethingElseSecret,
] = await decrypt([
  process.env.API_TOKEN_1,
  process.env.API_TOKEN_2,
  process.env.DATABASE_PASSWORD,
  process.env.SOMETHING_ELSE_SECRET,
])

Locally In Development

Providing a non-base64 encoded value will skip en/decrypting with AWS KMS and just return the same value. This is useful in local development where you may not be necessary to have your secrets encrypted. This helps to avoid the need to write development environment exception code:

import { decrypt } from 'aws-kms-thingy'

process.env.DATABASE_PASSWORD = 'foobar'

const dbPassword = await decrypt(process.env.DATABASE_PASSWORD)

console.log(dbPassword) // "foobar"

An undefined value is also OK. This does nothing and returns undefined. Useful when environment variables are unset in local development.

process.env.DATABASE_PASSWORD = undefined // e.g. not set in development

const dbPassword = await decrypt(process.env.DATABASE_PASSWORD)

console.log(dbPassword) // undefined

Alternatively, one can also disable en/decryption entirely with DISABLE_AWS_KMS_THINGY environment variable:

import { decrypt } from 'aws-kms-thingy'

process.env.DISABLE_AWS_KMS_THINGY = 'true'

const token = await decrypt('aHR0cDovL2JpdC5seS8xVHFjd243')

console.log(token) // "aHR0cDovL2JpdC5seS8xVHFjd243"

API

Methods

encrypt(parameters)

interface InterfaceEncryptParameters {
  readonly plaintext: string
  readonly keyId: string
}

async function encrypt(
  parameters:
    | InterfaceEncryptParameters
    | ReadonlyArray<InterfaceEncryptParameters>,
): Promise<string | ReadonlyArray<string>>

Encrypt a plaintext string. Requires a AWS KMS key ID (or key Arn).

const ciphertext = await encrypt({
  plaintext: 'secret text',
  keyId:
    'arn:aws:kms:eu-west-1:000000000000:key/55kkmm11-aann-99ff-mmaa-3322115566hh',
})

decrypt(ciphertext)

AWS KMS encrypted ciphertext contains metadata so it is not necessary to provide context or key ID.

async function decrypt(
  ciphertext: undefined | string | ReadonlyArray<string>,
): Promise<undefined | string | ReadonlyArray<string>>

Decrypt KMS-encrypted ciphertext.

const plaintext = await decrypt('aHR0cDovL2JpdC5seS8xVHFjd243')

Related Thingies

License

aws-kms-thingy © Marco Lüthy. Released under the MIT license.
Authored and maintained by Marco Lüthy with help from contributors.

github.com/adieuadieu · GitHub @adieuadieu · Twitter @adieuadieu · Medium @marco.luethy