Serverless plugin for encrypting secrets using KMS
npm install serverless-kms-secretsA 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
This plugins does the following:
* It provides commands to encrypt and decrypt secrets with KMS
In your service root, run:
``bash`
npm install --save-dev serverless-kms-secrets
Add the plugin to serverless.yml:
`yml`
plugins:
- serverless-kms-secrets
Configure the plugin into the custom block in serverless.yml. For example:
`yml`
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:
`yml`
- Effect: Allow
Action:
- KMS:Decrypt
Resource: ${self:custom.kmsSecrets.keyArn}
Create a KMS key in AWS IAM service, under Encryption keys. Collect the key id, which is the remaining part of the key ARN.
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.
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.
Pass the variables stored in the secrets file e.g. as environment variables using
`yml`
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.
`js`
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
`js``
const secrets = JSON.parse(decrypted);
* Add support for sls deploy (deploy as KMS encrypted environment variables)
* Ease configuration (KeyIds / Arns in various places)
* 2019/02/24 - v1.0.4 - Fix issue with serverless 1.33
* 2017/09/09 - v1.0.0 - Add support for multisecret structures
* 2017/05/13 - v0.9.0 - Initial version
Copyright (c) 2017 Nordcloud, licensed for users and contributors under MIT license.
https://github.com/nordcloud/serverless-kms-secrets/blob/master/LICENSE