Serverless KMS Secrets (DEPRECATED)

A Serverless Plugin for the Serverless Framework which helps with encrypting service secrets using the AWS Key Management Service (KMS)

THIS MODULE IS NO LONGER MAINTAINED. The best practice for managing secrets, also supported out-of-the-box by Serverless Framework, is to use the AWS SSM parameter store. See https://serverless.com/framework/docs/providers/aws/guide/variables/#reference-variables-using-the-ssm-parameter-store

Introduction

This plugins does the following:

It provides commands to encrypt and decrypt secrets with KMS

Installation and configuration

In your service root, run:

npm install --save-dev serverless-kms-secrets

Add the plugin to serverless.yml:

plugins:
  - serverless-kms-secrets

Configure the plugin into the custom block in serverless.yml. For example:

custom:
  serverless-kms-secrets:
    secretsFile: kms-secrets.${opt:stage, self:provider.stage}.${opt:region, self:provider.region}.yml (optional)
  kmsSecrets: ${file(kms-secrets.${opt:stage, self:provider.stage}.${opt:region, self:provider.region}.yml)}

By default, the plugin creates secrets to the file kms-secrets.[stage].[region].yml. This can be overriden with the secretsFile parameter in the serverless-kms-secrets configuration.

Add Decrypt permissions to your lambda function with e.g. this block in IamRoleStatements:

    - Effect: Allow
      Action:
      - KMS:Decrypt
      Resource: ${self:custom.kmsSecrets.keyArn}

Usage

Creating KMS Key

Create a KMS key in AWS IAM service, under Encryption keys. Collect the key id, which is the remaining part of the key ARN.

Encrypting Variables

To encrypt a variable using the key defined in the configuration, enter

sls encrypt -n VARIABLE_NAME -v myvalue [-k keyId]

e.g.

sls encrypt -n SLACK_API_TOKEN -v xoxp-1234567890-1234567890-123467890-a12346 -k 999999-9999-99999-999

The keyid (-k) parameter is mandatory for the first encrypted variable, but optional for the later ones (will be read from the secrets file). The encrypted variable is written to your secrets file (kms-secrets.[stage].[region].yml by default)

You may also pack multiple secrets into one KMS encrypted string. This simplifies consuming the secrets in the Lambda function since all secrets can be decrypted with one single KMS.Decrypt call. To encrypt multiple secrets into one single string, use the following notation:

sls encrypt -n VARIABLE_NAME:SECRET_NAME -v myvalue [-k keyId]

e.g.

sls encrypt -n SECRETS:SLACK_API_TOKEN -v xoxp-1234567890-1234567890-123467890-a12346 -k 999999-9999-99999-999

Would encrypt and add the SLACK_API_TOKEN into the (JSON) secret SECRETS.

NOTE: you may get warnings about the missing kms-secrets file when encrypting your first variables for a specific stage / region. The warning will go away once the file has been created by the plugin.

Decrypting Variables

The variables in the secrets file can be decrypted using

sls decrypt [-n VARIABLE_NAME]

The -n option is optional. Without that, all variables are decrypted and displayed in clear text on the console.

Using variables

Pass the variables stored in the secrets file e.g. as environment variables using

  environment:
    MY_VARIABLE: ${self:custom.kmsSecrets.secrets.MY_VARIABLE}

The variable must be decrypted in the Lambda function using the KMS decrypt method. E.g.

kms.decrypt({
  CiphertextBlob: Buffer(process.env.MY_VARIABLE, 'base64')
}).promise()
.then(data => {
  const decrypted = String(data.Plaintext)
})

If MY_VARIABLE consists of multiple variables, decode it using

  const secrets = JSON.parse(decrypted);