Bring Your Own Key Generation and Import Process for AWS Flexible Cloud Architecture

[Tom_Garrett]

This topic shows how to create and import encrypted key material for AWS Key Management Service using Bring Your Own Keys (BYOK).

Pre-Requisites

Bluescape recommends using RSAES_OAEP_SHA_256 for the wrapping encryption material, which requires OpenSSL. You cannot perform these functions with LibreSSL (an alternative tool to OpenSSL).

Bluescape must provide the following information to begin:

• AWS Account Number to grant access to the Key Management Service (KMS) you will generate with this document
• The AWS region to create the KMS key in

Finding the KMS Console

1. Switch to the correct AWS region (See Pre-Requisites).

2. Access the KMS console by logging into the AWS Management Console.

3. From the main page, expand All services.

   

4. Click on Key Management Service.

   

Creating a new Customer Managed Key

1. From the Key Management Service (KMS) console, select Customer managed keys.

   

2. To create a new Customer Managed Key (CMK), select Create key.

   

3. In the next screen, give your key an Alias. Then expand the Advanced options and check External for the Key material origin. Also, check the box at the bottom confirming that you understand the circumstances of using an imported key. Click on the links provided in the console for additional details.

   

4. Optionally, you may add tags to your key. These are used for tracking and reporting purposes and are not required.

   

5. In the next screen, you are asked to define key administrative permissions. For now, check the box for your AWS username and the usernames of others you feel need this permission.

   

6. You must also define key usage permissions. Again, check the box for your AWS username and the usernames of others you feel need this permission.

   

7. The final step asks you to review and edit your key policy. The policy text is generated based on your previous responses; you do not need to change any information. Click Finish to continue.

   

Importing your key

After you create the CMK (customer-managed key), AWS immediately takes you to a dialog to download the wrapping key and import token.

1. To achieve the highest level of security, Bluescape and AWS recommend using RSAWS_OAEP_SHA_256 as the wrapping algorithm. Once selected, click Download wrapping key and import token to continue, then click Next.

   

2. Your browser then asks you to save a file called ImportParameters.zip. Save this file for use later in the process.

Encrypting the downloaded key material (ImportParameters.zip)

IMPORTANT: Ensure you use a recent version of the openssl command. LibreSSL (sometimes used as an alternative to OpenSSL) does not work for this process as it cannot support the SHA256 algorithm we’re using. The commands in the example below were used on a Linux operating system. However, OpenSSL does work with other Operating Systems.

Note: The commands below are examples using OpenSSL on a Linux Operating system.

1. Ensure that your OpenSSL command is OpenSSL and not LibreSSL.

2. In your terminal, type openssl version as seen below.

   $ openssl version
   OpenSSL 1.0.2o 27 Mar 2018
   

3. If the command outputs a LibreSSL version, you are using LibreSSL. If this is the case, remove
   your installation of LibreSSL and download/install a recent version of OpenSSL.

   $ openssl version
   LibreSSL 2.6.5
   

4. Next, extract and encrypt the key material.

   Note: These are slightly modified steps taken from AWS’s developer guide to support the SHA256 algorithm: Importing key material step 3: Encrypt the key material - AWS Key Management Service

5. In an empty directory, unzip the ImportParameters.zip file

   $ unzip ImportParameters.zip
   

6. You should see three files (a README, an importToken, and a wrappingKey):

   $ ls -l
   total 40
   -rw-r--r--@ 1 reed staff 296 Mar 15 2019 README_a857ecad-4f75-4ae9-b7e5- 
   5392f8854cd1_03151209.txt
   -rw-r--r--@ 1 reed staff 1757 Mar 15 2019 importToken_a857ecad-4f75-4ae9-b7e5- 
   5392f8854cd1_03151209
   -rw-r--r--@ 1 reed staff 294 Mar 15 2019 wrappingKey_a857ecad-4f75-4ae9-b7e5- 
   5392f8854cd1_03151209
   

7. With your OpenSSL command, generate some key material:

   $ openssl rand -out PlaintextKeyMaterial.bin 32
   

8. Next, with your OpenSSL command, generate an EncryptedKeyMaterial.bin file using your generated PlaintextKeyMaterial.bin and the wrappingKey file from the ImportParameters.zip file:

   $ openssl pkeyutl -in PlaintextKeyMaterial.bin -out EncryptedKeyMaterial.bin -inkey wrappingKey_a857ecad-4f75-4ae9-b7e5-5392f8854cd1_03151209 -keyform DER -pubin -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
   

Import your Encrypted Key Material

1. Return to the AWS console in your browser, where it asks you to import your wrapped key material.

2. In the Wrapped key material section, click Choose file and choose the EncryptedKeyMaterial.bin file you generated with OpenSSL.

   

3. In the Import token section, click Choose file and choose the importToken file from the ImportParameters.zip file.

   

4. Click Upload key material to finish the import process.

   

5. If the process was successful, you should see a banner that indicates you can now use this CMK. Your imported key is now ready to be used for encryption.

   

Enable “External” AWS Bluescape Account

These steps allow Bluescape to create and manage secure data stores using the KMS key created in the previous section.

1. In the Key Management Service console, click on the alias of your imported key.

   

2. At the bottom of the details page of the imported key is a section called Other AWS Accounts. Click Add other AWS accounts.

   

3. In the Other AWS accounts dialog box, type in the 12-digit AWS account ID (provided by Bluescape) in the box, then click Save changes.

   

Finding the ARN of the imported key

1. In the Key Management Service console, click on the alias of your imported key.

   

2. At the top of the key’s details is an ARN id (circled in the image below). Copy this ARN id; it must be given to Bluescape, which is required to encrypt data stores.

   

Summary of what Bluescape requires after keys are setup

The following information must be given to Bluescape to build an instance of Bluescape using the key generated:

• The ARN of the KMS key generated (See section: Finding the ARN of the imported key for details)

---

Now, go try it in your workspace!