How to encrypt files using AWS KMS?

3 min readMar 24, 2023

Background

Most of the company still migrating their applications to the cloud environment. It is very common that we have to facilitate the communication between on-premise and cloud. File transfer is common strategy especially for legacy system. Envelop encryption probably is the most easy and secure way to encrypt our file on-premise with the help of AWS KMS.

Prerequisite

1. AWS account with permission to create/access AWS KMS

2. AWS CLI

3. AWS Encryption CLI

What is envelop encryption?

Encrypt API of AWS KMS has a limit of 4KB. Therefore, if we want to encrypt file larger than 4JB, we need to use envelop encryption

AWS KMS solution uses an envelope encryption strategy with AWS KMS keys. Envelope encryption is the practice of encrypting plaintext data with a data key, and then encrypting the data key under another key. Use KMS keys to generate, encrypt, and decrypt the data keys that you use outside of AWS KMS to encrypt your data. KMS keys are created in AWS KMS and never leave AWS KMS unencrypted.

Encryption Algorithm

By default, it uses AES-GCM with an HKDF, an ECDSA signature, and a 256-bit encryption key.

Other supported algorithm suites (not recommend by AWS)

AES-GCM without key commitment, AES-GCM without signing, AES-GCM without key derivation

Steps

1. Generate a new encryption key

By default, create-key creates a symmetric encryption KMS key with key material that KMS generates. This is the basic and most widely used type of KMS key, and provides the best performance.

If succeed, it will return the key metadata like the following

{
    "KeyMetadata": {
        "AWSAccountId": "1234567890",
        "KeyId": "a1234567-4db7-4f81-a603-b0232326518",
        "Arn": "arn:aws:kms:ap-east-1:98765432102165:key/ a1234567-4db7-4f81-a603-b0232326518",
        "CreationDate": "2023-03-21T17:49:32.317000+08:00",
        "Enabled": true,
        "Description": "envelope encryption using encryption cli",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegion": false
    }
}

2. Verify the key is available in AWS console

Verify the key is available in AWS console by verify the key id shown in previous step is displaying in AWS KMS console

3. Encrypt the file

aws-encryption-cli --encrypt --input hello.txt --wrapping-keys key="arn:aws:kms:ap-east-1:974109842181:key/a220d1ee-4db7-4f81-a603-b02e3e273103" --metadata-output metadata/ --output output/

This command will encrypt file ‘hello.txt’ with key ‘arn:aws:kms:ap-east-1:974109842181:key/a220d1ee-4db7–4f81-a603-b02e3e273103’ and output the metadata file ‘metadata’ and encrypted file to folder ‘output’

If succeed, it will generate the encrypted file ‘output/hello.txt.encrypted’, and metadata file which including the file encryption information

4. Decrypt the file

aws-encryption-cli --decrypt --input output/hello.txt.encrypted --wrapping-keys key="arn:aws:kms:ap-east-1:974109842181:key/a220d1ee-4db7-4f81-a603-b02e3e273103" --metadata-output metadata --output hello.txt.decrypted

This command will decrypt the file ‘output/hello.txt.encrypted’ with key ‘arn:aws:kms:ap-east-1:974109842181:key/a220d1ee-4db7–4f81-a603-b02e3e273103’ to hello.txt.decrypted