Have ideas to improve npm?Join in the discussion! »


    1.0.5 • Public • Published

    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


    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:

      - serverless-kms-secrets

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

        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
          - KMS:Decrypt
          Resource: ${self:custom.kmsSecrets.keyArn} 


    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]


    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]


    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

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

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

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

    If MY_VARIABLE consists of multiple variables, decode it using

      const secrets = JSON.parse(decrypted);


    • Add support for sls deploy (deploy as KMS encrypted environment variables)
    • Ease configuration (KeyIds / Arns in various places)

    Release History

    • 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


    npm i serverless-kms-secrets

    DownloadsWeekly Downloads






    Unpacked Size

    18.8 kB

    Total Files


    Last publish


    • avatar