AWS KMS and envsec

KMS is a relatively new AWS service that provides an API for managing symmetric encryption keys, encryption operations on top of them as well as providing a source of random bytes.
10.05.2016
Tags

KMS is relatively new AWS service that provides an API for managing symmetric encryption keys, encryption operations on top of them as well as providing a source of random bytes. It’s used internally by AWS to provide encryption for several AWS services such as EBS, Redshift, S3 and others while letting the end-user keep control over the lifecycle of the keys (which is a useful property e.g. for managing compliance to the German data-privacy laws).

Another useful property of KMS is the possibility to split access between encryption and decryption operations. This makes it a convenient candidate for encrypting configuration secrets (such as database passwords or API keys), where encryption should be available to all operator-type users while decryption should be reserved to EC2 instance profiles or Lambda execution roles.

To make this easy to use we wrote a tool named envsec (es) which is similiar in spirit to envplate and either encrypts environment variables or transparently decrypts them, making them available as regular environment variables to another process which is being exec()-uted after the decryption takes place.

Using es users or roles with appropriate access through a KMS key’s key policy (in KMS access rights are configured on the key, not in IAM and pointing to the key) can encrypt exisiting environment variables like this:

export HELLO=world                                                                                                                                  es enc --arn=arn:aws:kms:eu-west-1:1234:key/5dabcb5e-b6fd-4af2-a7f4-0b2ad5528b53 HELLO
$ ENVSEC_HELLO=CiB9o66svYk4uWid3Fgl1NFXHvavIw3DymOpPNUPqLCdLhKMAQEBAgB4faOurL2JOLlondxYJdTRVx72ryMNw8pjqTzVD6iwnS4AAABjMGEGCSqGSIb3DQEHBqBUMFICAQAwTQYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwZ5yAlrGOZ14TP6ogCARCAIIBmHRkRxafXYI4xXrjcyz7RbfpbprLcEPyp4PlYujlJ

The resulting environment variable ENVSEC_HELLO can now be safely committed to version control, e.g. as part of a Dockerfile, CloudFormation or Terraform template.

To decrypt it, es be used as follows - given an executable shell script out.sh containing the lines

# !/bin/bash
echo $HELLO

we can decrypt and output our encrypted environment variable as follows:

es dec -- $PWD/out.sh

When using the decrypted variable values for templating, es can also easily be combined with envplate like this:

es dec -- /path/to/ep path/to/config/*.conf

Interested in getting started with KMS and es? Check out the example section of es, which also contains a CloudFormation / Tacks stack to get you started with custom KMS keys and matching encryption / decryption IAM roles for easy testing.

Image credits for the cover image go to Marcus Povey.