Bring Your Own Keys with AWS Key Management Service

In this lab, you will use the AWS Key Management Service (KMS) which makes it easy for you to create and manage cryptographic keys and control their use across a wide range of AWS services and in your applications. AWS KMS is a secure and resilient service that uses AWS managed hardware security modules that have been validated under FIPS 140-2 to protect your keys. AWS KMS is integrated with AWS CloudTrail to provide you with logs of all key usage to help meet your regulatory and compliance needs.

Bring your Own Keys

AWS Key Management Service (AWS KMS) has the ability to bring your own keys (BYOK) for use with KMS-integrated AWS services and custom applications. This feature allows you more control over the creation, lifecycle, and durability of your keys. You decide the hardware or software used to generate the customer-managed customer master keys (CMKs), you determine when or if the keys will expire, and you get to upload your keys only when you need them and delete them when you’re done.

You will be using OpenSSL to create the customer managed key (BYOK) for this lab. OpenSSL is a valid method of creating the key material associated with a KMS CMK, but the best practice is to perform key creation using a hardware security module (HSM). While beyond the scope of this lab, AWS offers AWS CloudHSM which is a cloud-based hardware security module (HSM) that enables easy generation and use of HSM encryption keys on the AWS Cloud.


To complete this BYOK encryption lab, in addition to Amazon DocumentDB and AWS Cloud9 environments, you will need IAM privileges for the AWS Key Management Service. An AWS led event typically provides an Event Engine account that have sufficient privileges.

Creating the Master Key

(1) Navigate to the KMS console and choose Create key. (Note, Event Engine accounts have sufficient privileges for this lab. If using your own account, ensure you have Permissions for creating CMKs). AWS KMS 1

You must use a symmetric CMK to encrypt your cluster as Amazon DocumentDB supports only symmetric CMKs. Additionally, imported key material is supported only for symmetric CMKs in AWS KMS key stores. For more information, see Using Symmetric and Asymmetric Keys in the AWS Key Management Service Developer Guide.

Choose the Symmetric key option for the Key type, select Advanced options and choose External as the Key material origin. Finally, check the box acknowledging you understand the security, availability, and durability implications of using an imported key, and click Next. AWS KMS 2

Provide an Alias like DocumentDB-MasterKey and Description for the key and click on Next to continue.


Choose the IAM Users or roles who can administer the key. If you are running this lab using an AWS provided Event Engine account choose TeamRole, which may be on the 2nd page.

If you are running this using your account, choose a role with sufficient KMS privileges. (See “Learn more” link on console under “Key administrators”).

Select Next.


Similarly, choose the IAM users and roles that will use the CMK. Click Next


Review the policy and click Finish AWS KMS 6

With the CMK ID created, next Download the wrapping key and import token. Leave the wrapping algorithm at default, RSAES_OAEP_SHA_256. Wrapping is a method of encrypting the key so that it doesn’t pass in plaintext over the network. You need both the wrapping key and the import token in order to import the key you create into AWS KMS. AWS KMS 6 Unzip the files on your local machine.

Leave the above KMS console browser tab open–you will return to it to upload your key material after creating it.

(2) You will use AWS Cloud9 to create your key material. Open an AWS cloud9 management Console in a new browser tab and choose open IDE to launch the AWS Cloud9 environment. You can close the Welcome screen and adjust your terminal window to increase screen area.

Click on File and choose Upload Local files and upload the wrapping key file (starts with “wrappingKey”) downloaded from the previous step. AWS KMS 7

When finished uploading, close the Upload file window by selecting X in the upper right corner of the dialog box.

(3) You will use the openssl command twice, first to generate a secret key, and a second time to wrap the secret key with the wrapping key. The openssl program is a command line tool for using the various cryptography functions of OpenSSL’s crypto library from the shell.

Run the following command to generate a secret key:

openssl rand -out plain_text_aes_key.bin 32

The command will return silently, but will generate a file with your secret key named plain_text_aes_key.bin

You can list the files in the current directory to see it:

ls -ltr


Next, wrap the secret key with the wrapping key. You will need to manually cut and paste the command below being sure to use your wrapping key file name uploaded above.

openssl pkeyutl -in plain_text_aes_key.bin -inkey <your-wrappingKey...>  -pubin -keyform DER  -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -out enc.aes.key
ls -ltr


The command above will create a wrapped key named enc.aes.key.

Download this key to your local machine by clicking on enc.aes.key in the left panel, then right-click, and select Download. Note the download location on your local system. AWS KMS 8

(4) Return to the KMS console left open in a different browser tab in Step #1 and click Next.

Upload both the wrapped key material and the import token.

  • The wrapped key material is the enc.aes.key downloaded in the prior step.
  • The import token will be found on your local machine in the directory unzipped in step #1 above.

Choose Upload Key material:


You should receive a “Your key material was imported…” message and see the key Enabled on the KMS console.

You now have customer managed key (BYOK) stored in KMS. Please move on to the next section to create a new Amazon DocumentDB cluster using your key.