kmscrypter

Command wrapper for encryption and decryption using aws kms.

Description

kmscrypter decrypts environment variables with keys that end in _KMS and assigns them to a key of the same name with the KMS suffix removed. It also encrypts the value of an environment variable that has a key ending with _PLAINTEXT and assigns it to a key of the same name that replaced the suffix with _KMS.

For example, the following environment variable:

MY_SECRET_KMS="hZGLgZHLGcL2Tq1k5GJgYPjH2Pu/ifH/mV57PTXRyq3dd3Lmr3KqvLrlnoneZ...."

Will generate a MY_SECRET key in the ENV variable that contains the plaintext value of the original key.

Installation

Linux

For RHEL/CentOS:

sudo yum install https://github.com/masahide/kmscrypter/releases/download/v0.1.0/kmscrypter_amd64.rpm

For Ubuntu/Debian:

wget -qO /tmp/kmscrypter_amd64.deb https://github.com/masahide/kmscrypter/releases/download/v0.1.0/kmscrypter_amd64.deb && sudo dpkg -i /tmp/kmscrypter_amd64.deb

macOS

install via brew:

brew tap masahide/kmscrypter https://github.com/masahide/kmscrypter
brew install kmscrypter

Usage

requires IAM access to Amazon's KMS service. It is necessary to exploit the role of EC2 IAM or to set access credentials in environment settings. (or ~/.aws/credentials and ~/.aws/config File)

AWS_ACCESS_KEY_ID=<your_key_id>
AWS_SECRET_ACCESS_KEY=<your_secret_key>
AWS_REGION=<ap-northeast-1(etc..)>

As a decryption command wrapper

$  kmscrypter some_command [arg1 arg2...]

kmscrypter operates as follows.

1. Find the key name of the environment variable with _KMS suffix
2. Execute KMS Decrypt API using aws credentials to decrypt the value
3. Set the decrypted value to the key name from which the _KMS suffix was removed from the original key
4. Execute some_command with args.

As a decryption environment variable exporter

When kmscrypter is executed without arguments, kmscrypter outputs environment variable shell script exprot decrypted data

$ export PASSWD1_KMS = "hZGLgZvuacL2TiyoCQ1HLGq1k5GJgYP ......"
$ export PASSWD2_KMS = "2TiyoCQ15acLGJgYPHLGqhZGLgZvu1k ......"
$ kmscrypter
export PASSWD 1 = "XXXXXXXXXXXXXXXX"
export PASSWD 2 = "XXXXXXXXXXXXXXXX"

You can set decoded data environment variable by eval.

$ eval "$ (kmscrypter)"

Creating encrypted data

kmscrypter encrypts the value of the _PLAINTEXT suffix when the environment variable KMS_CMK is set. It operates as follows.

1. Use the value of the environment variable KMS_CMK as KMS Customer Master keyId (ARN)
2. Find the key name of the environment variable with _PLAINTEXT suffix
3. Encrypt using the KMS GenarateDataKey API using aws credentials and KMS_CMK
4. Set the encrypted data to the key name obtained by replacing the encrypted value with the original key and the _PLAINTEXT suffix by _KMS
5. Output the encrypted value to standard output as export <Key name> _KMS =" encrypted data ... "

example:

$ MYSQL_ROOT_PASSWD_PLAINTEXT="passwordxxx" \
KMS_CMK=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
kmscrypter

## Encrypted environment variable is output..
MYSQL_ROOT_PASSWD_KMS="5acLGJyoCQ1PHLGqhZGvgY2Tiu1kLgZ......"

Use case 1:

Handle secret variables with ansible.

secret.json:

{
  "user1": "pass1111",
  "user2": "pass12345"
}

encrypt json:

• Set the master key ARN to KMS_CMK
• Set the json string to the key with the `_PLAINTEXT 'suffix

$ SECRET_JSON_PLAINTEXT=$(cat secret.json) \
KMS_CMK=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
kmscrypter

output:

export SECRET_JSON_KMS="hZGLgZvuacL2TiyoCQ1HLGq1k5GJgYP......"

playbook example:

From ansible-playbook you can reference it using lookup filter etc.

- hosts: all
   vars:
     secret: "{{ lookup('env', 'SECRET_JSON') | from_json }}"
   tasks:
   - debug: msg = {{secret [%s | format (item)]}}
     with_items:
       - "user1"
       - "user2"

running ansible-playbook:

When wrapping and running ansible-playbook as follows, the value of SECRET_JSON_KMS is decrypted and set as SECRET_JSON and passed to ansible-playbook.

$ SECRET_JSON_KMS="hZGLgZvuacL2TiyoCQ1HLGq1k5GJgYP..." kmscrypter ansible-playbook site.yml

or

$ export SECRET_JSON_KMS="hZGLgZvuacL2TiyoCQ1HLGq1k5GJgYP..."
$ kmscrypter ansible-playbook site.yml

or Use encrypted data saved in s3.

$ SECRET_JSON_KMS="$(aws s3 cp s3://bucket/secret.kms -)" kmscrypter ansible-playbook site.yml