A tool used to encrypt environment and decrypt environment variables using KMS to support passing of encrypted environment variables to docker containers.
If you are looking for a way to pass environment variables to a docker container in a secure manner, this tool aims to help.
- NodeJS v7.x
- A AWS Customer Master Key in KMS
How it works
- Create a CMK in AWS. IAM > Encryption Keys
- Give a user or role access to this key via the key's policy
By default, the tool will use the default credential chain for AWS.
You can specify Access Keys and Secret Access keys via Environment variables, or cli arguments. If you are running the tool on an EC2 instance, the instance profile will be used.
Usage: kms-env [options] [command]Commands:init [keyId] [file] Initialize an environment variable file with provided CMK Idadd [file] [entries...] Adds environment variable to file after encrypting the valuedecrypt Decrypts secure environment variables and generates a bash export
Exporting AWS Region
An AWS Region must be specified when running
kms-env. It can be provided via the
--region parameter or with the following export:
The above command will set your region to
Initializing an env file
To get started, you must run the
init command and specify
your KMS CMK ID or alias. You can find this in the AWS console: IAM > Encryption Keys
$ kms-env init [keyid] [filename]
Let's initialize a file called
test.env using a CMK with alias
$ kms-env init alias/mykey test.env
After running the
init command, a
test.env file will be created in your
It will contain the following:
KMS_DATA_KEY = [encrypted value]
You can now start adding secure environment variables to this file
Adding secure variables
To add secure environment variables to your file you can use:
$ kms-env add [filename] [entries...]
Let's add the following environment variables:
- DATABASE_PASS = test123
- DATABASE_USER = alice
$ kms-env add test.env DATABASE_PASS=test123 DATABASE_USER=alice
The new environment variables should be added to your
KMS_DATA_KEY = [encrypted value]DATABASE_PASS = secure:[encrypted value]DATABASE_USER = secure:[encrypted value]
Decrypting secure variables
Once you have exported the above environment variables in your an environment, you can easily have them decrypted
$ export KMS_DATA_KEY = ...$ export DATABASE_PASS = secure:...$ export DATABASE_USER = secure:...$ eval $(kms-env decrypt)$ echo $DATABASE_PASS$ test123$ echo $DATABASE_USER$ alice
decrypt command will output export statements which you can run through
to have the secure environment variables replaced in place.
Example: Secure environment variables to Docker container
The motivation behind creating kms-env was to securely pass sensitive environment variables to an application running in a docker container in AWS
env file created by
kms-env can be used with the
docker run command using the
--env-file [file] argument.
Step 1: Create a docker image with kms-env installed
kms-env to securely pass env vars to a docker container, the container needs kms-env installed.
Example Dockerfile with node + kms-env
An example docker file which has kms-env installed is provided at Dockerfile
You can use this docker file as your base image for your application image if you are building a NodeJs application. If you are using a different platform (eg JVM) then you will also need to install the necessary dependencies for that platform.
How it works
The docker file uses an
env-decrypt bash entrypoint script, so it will first run
kms-env decrypt and then run whatever is supplied as a command to
So, for example:
docker run [image] npm start
Assuming your image has the working directory set to a node project, the
npm start command will run after the
Step 2: Permissions to the CMK
In order for your container to decrypt environment variables, it will need read access to the CMK used to encrypt the env vars.
To set up permissions, you will need to attach a policy to the role which is assumed by your AWS EC2 instance or the task role (if you are using AWS ECS)
Example IAM Policy Granting Access to a CMK
The above policy, when attached to a role will give decrypt access for the CMK. You must supply the ARN for your specific key.
ECS Task Role If you are running docker containers using AWS ECS, you would attach the above policy to the Task Role associated with your ECS Task Definition
Step 3: Supplying an env file to your container
Once you have a container image that has
kms-env installed and the container is running on an EC2 instance or ECS Task with
the correct permissions, you can supply your
env files to your container.
Supplying env via docker run
If you are running docker on EC2 directly, you can use supply your
env file via:
docker run --env-file [filepath] [image] [command]
The above command will run your container with the supplied env file as environment variables. If the container is using the example base image, it will automatically decrypt the secure env vars in place for your application to read.
Supplying env via ECS Task Definition
To supply environment variables to a container running on ECS you will need to supply them via the task definition JSON
The following is an example task def (with some fields left blank) where we supply the environment variables which would be present in
.env file generated by
Example Task Def
When the above task runs, it would supply the env vars to the docker container similar to the
-e argument for the
docker run command.
To supply credentials manually you can use the following parameters:
- --access-key-id - To specify your access key ID
- --secret-access-key - To specify your secret
- --region - To specify the AWS Region
Alternatively you can supply an AWS credential profile to use via:
- --profile - To use a credential profile instead of supplying access key and secret