KmsTools

A simplified toolset for encrypting and decrypting data using Amazon Key Management Service. Since credentials are managed by the AWS SDK, you can use a local credentials file for the CLI and rely on IAM roles to provide access for applications running on AWS instances. This completely removes the need to manage plaintext secret keys even for locally encrypted and decrypted data.

Local Encryption

Per the KMS spec, data up to 4KB may be encryptyed with a simple encrypt call. Larger blobs of data must be locally encrypted using data keys. KmsTools facilitates this by generating two data keys for each blob encrypted. One is used as the symmetric secret key and the other used as the initialization vector. These two keys are encrypted and then stored along side the encrypted data for later use.

Standard lib OpenSSL is used for local encryption. While any block cipher compiled in to OpenSSL can be used for local encryption, it is important to note that the same cipher must be available on any machine attempting to decrypt the same data. So it is recommended to use commonly available ciphers. aes-256-cbc is the default.

.kms Filetype

To make storage and recall of encryption metadata easier, the .kms filetype was developed. This filetype is used when storing encrypted files with the CLI and by default when using KmsTools::EncryptedFile. .kms files are a digital envelope made up of 3 specific parts:

1. A zero-padded 7 byte integer noting total length of metadata stored
2. YAML encoded metadata
3. Encrypted binary data meta-length metadata encrypted binary data INT YAML BIN |-----------|----------------------|---------------------------------------------------------|

While an arbitrary number of metadata elements can be stored as needed, there are a few standard elements

• OpenSSL cipher used for encryption required
• Encrypted encryption key (decypted with KMS prior to using) required
• Encrypted initialization vector (decypted with KMS prior to using) required
• Original file extension required
• Original data checksum required
• KMS Master Key ARN (Optional but there by default for troubleshooting)

CLI

The CLI exposes most of the functionality of the gem in a simple interface.

Keep in mind that the gem uses standard AWS credential management. So if you are using the CLI on a server without a credentials file in place, all activity will be logged in CloudTrail as the role instead of the user taking action. For this reason it is highly recommended that you run some sort of IDS on instances using roles that have access to KMS to ensure that all KMS activity is properly logged.

NAME
    kms-tools - CLI for encrypting and decrypting information with Amazon KMS

SYNOPSIS
    kms-tools [global options] command [command options] [arguments...]

VERSION
    0.0.1

GLOBAL OPTIONS
    --[no-]color         - Colorize output (default: enabled)
    -d, --debug          - Debug output (Includes verbose)
    --help               - Show this message
    -k, --master_key=arg - Encrypt using the specified key alias or key id as the customer master key (default: none)
    -p, --profile=arg    - AWS credentials profile to use (default: default)
    -r, --region=arg     - AWS Region (default: us-east-1)
    -v, --verbose        - Verbose output
    --version            - Display the program version

COMMANDS
    decrypt      - Decrypt a text string or a file
    encrypt      - Encrypt a text string or a file
    help         - Shows a list of commands or help for one command
    list-aliases - List KMS key aliases available to current credentials

Example string encryption/decryption:

[~/sportngin/kms-tools] (master)$ bundle exec bin/kms-tools encrypt "something secret"
Choose which key alias to use as the base Customer Master Key:
1. alias/staging/kms-tools1
2. alias/staging/kms-tools2
3. alias/staging/vpn
? 1
Encrypted ciphertext (copy all text without surrounding whitespace):

CiAA6CYSKxFRMav+m01ps0d8V5PrVvbPebe2L7LNbrV7NBKXAQEBAgB4AOgmEisRUTGr/ptNabNHfFeT61b2z3m3ti+yzW61ezQAAABuMGwGCSqGSIb3DQEHBqBfMF0CAQAwWAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwFjvAk2NeDhOGxlUUCARCAK1hO8B+M6RWjiQckqI4RlGnP8mI/gePSfERHcD0KgwvJwhiPP8z+p0m2TkY=


[~/sportngin/kms-tools] (master)$ bundle exec bin/kms-tools decrypt CiAA6CYSKxFRMav+m01ps0d8V5PrVvbPebe2L7LNbrV7NBKXAQEBAgB4AOgmEisRUTGr/ptNabNHfFeT61b2z3m3ti+yzW61ezQAAABuMGwGCSqGSIb3DQEHBqBfMF0CAQAwWAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwFjvAk2NeDhOGxlUUCARCAK1hO8B+M6RWjiQckqI4RlGnP8mI/gePSfERHcD0KgwvJwhiPP8z+p0m2TkY=
Decrypted string:

something secret


[~/sportngin/kms-tools] (master)$