mrcrypt is a command-line tool which encrypts secrets that conform to the AWS Encryption SDK's message format for envelope encryption. Envelope encryption is used to encrypt a file using a KMS data key. That data key is then encrypted with regional KMS Customer Master Keys. Each regionally encrypted data key is then stored in the encrypted message. When decrypting, the appropriate regional CMK is used to decrypt the data key, and the data key is then used to decrypt the file. In other words, encrypt once - decrypt from anywhere.
Because mrcrypt follows the AWS Encryption SDK's message format, files encrypted by mrcrypt can also be decrypted using the AWS Encryption SDK for Java. For details, see the section titled Compatibility with the AWS Encryption SDK.
You can install the latest release of mrcrypt with pip:
pip install mrcrypt
Note: mrcrypt uses the Python package
Cryptography which depends on
libffi. You may need to install it on your system if
pip install . fails. For more specific instructions for your OS:
https://cryptography.io/en/latest/installation/
Encrypt a file for use in 3 regions (NOTE: Key alias must exist in specified regions):
mrcrypt encrypt -r us-east-1 us-west-2 eu-west-1 -- alias/master-key secrets.txt
Decrypt the file:
mrcrypt decrypt secrets.txt.encrypted
usage: mrcrypt [-h] [-p PROFILE] [-e ENCRYPTION_CONTEXT] [-d] [-o OUTFILE]
{encrypt,decrypt} ...
Multi Region Encryption. A tool for managing secrets across multiple AWS
regions.
positional arguments:
{encrypt,decrypt}
optional arguments:
-h, --help show this help message and exit
-p PROFILE, --profile PROFILE
The profile to use
-e ENCRYPTION_CONTEXT, --encryption_context ENCRYPTION_CONTEXT
An encryption context to use. (Cannot have whitespace)
-d, --debug Enable more output for debugging
-o OUTFILE, --outfile OUTFILE
The file to write the results to
Both the encrypt, and decrypt commands can encrypt and decrypt files in directories recursively.
If you have multiple named profiles in your ~/.aws/credentials file,
you can specify one using the -p argument.
mrcrypt -p my_profile encrypt alias/master-key secrets.txt
You can specify an encryption
context
using the -e argument. This flag takes a JSON object with no spaces:
# encrypt
mrcrypt -e '{"key":"value","key2":"value2"}' encrypt alias/master-key secrets.txt
# decrypt
mrcrypt -e '{"key":"value","key2":"value2"}' decrypt secrets.txt.encrypted
If you want to specify the output filename, you can use the -o
argument.
# Encrypt 'file.txt' writing the output into 'encrypted-file.txt' mrcrypt -o encrypted-file.txt encrypt alias/master-key file.txt
By default, when encrypting, mrcrypt will create a file with the same
file name as the input file with .encrypted appended to the end.
When decrypting, if the file ends with .encrypted it will write the
plaintext output to a file of the same name but without the
.encrypted.
usage: mrcrypt encrypt [-h] [-r REGIONS [REGIONS ...]] [-e ENCRYPTION_CONTEXT]
key_id filename
Encrypts a file or directory recursively
positional arguments:
key_id An identifier for a customer master key.
filename The file or directory to encrypt. Use a - to read from
stdin
optional arguments:
-h, --help show this help message and exit
-r REGIONS [REGIONS ...], --regions REGIONS [REGIONS ...]
A list of regions to encrypt with KMS. End the list
with --
-e ENCRYPTION_CONTEXT, --encryption_context ENCRYPTION_CONTEXT
An encryption context to use
Example: Encrypt secrets.txt with the key alias
alias/master-key in the regions us-east-1 and us-west-2:
mrcrypt encrypt -r us-east-1 us-west-2 -- alias/master-key secrets.txt
Note: In this example, the key alias alias/master-key exists in both the us-east-1, and us-west-2 regions.
usage: mrcrypt decrypt [-h] filename Decrypts a file positional arguments: filename The file or directory to decrypt. Use a - to read from stdin optional arguments: -h, --help show this help message and exit
Example: To decrypt secrets.txt.encrypted:
mrcrypt decrypt secrets.txt.encrypted
Note: Be careful when decrypting a directory. If the directory contains files that are not encrypted, it will fail.
Running tests for mrcrypt is easy if you have tox installed. Simply
run tox at the project's root.
All files encrypted with mrcrypt can be decrypted with the AWS Encryption SDK for Java. But not all files encrypted with the AWS Encryption SDK for Java can be decrypted by mrcrypt.
Currently, mrcrypt only supports the AWS Encryption SDK's default (and most secure) cryptographic algorithm:
- Content Type: Framed
- Frame size: 4096
- Algorithm: ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384
Support for the remaining algorithms are planned, but files encrypted using one of the other algorithms are currently not supported by mrcrypt.
Also, the AWS Encryption SDK specifies that files use elliptic curve point compression. Files created with mrcrypt do not use point compression because they are not currently supported in Cryptography, a Python package mrcrypt uses. The uncompressed points are just as secure as the compressed points, but files are a few bytes larger. The AWS Encryption SDK for Java can decrypt files that use uncompressed points, meaning all files created with mrcrypt are compatible with the AWS Encryption SDK for Java. The AWS Encryption SDK for Python cannot decrypt files created by mrcrypt, because it does not support uncompressed points. Work is planned in the future to have mrcrypt use compressed points.