AWS Key Management Service
Developer Guide

Importing Key Material Step 2: Download the Public Key and Import Token

After you create a customer master key (CMK) with no key material, you download a public key and an import token for that CMK. You need these items to import your key material. You can download both items in one step by using the AWS Management Console or the AWS KMS API.

You also download these items when you want to reimport key material into a CMK. You might do this to manually rotate the key material, to change the expiration time for the key material, or to restore a CMK after the key material has expired or been deleted.

Use of the Public Key

When you import key material, you don't upload the raw key material to AWS KMS. You must first encrypt the key material with the public key that you download in this step and then upload the encrypted key material to AWS KMS. When AWS KMS receives your encrypted key material, it uses the corresponding private key to decrypt it. The public key that you receive from AWS KMS is a 2048-bit RSA public key and is always unique to your AWS account.

Use of the Import Token

The import token contains metadata to ensure that your key material is imported correctly. When you upload your encrypted key material to AWS KMS, you must upload the same import token that you download in this step.

Select a Wrapping Algorithm

To protect your key material during import, you encrypt it using a wrapping key and wrapping algorithm. Typically, you choose an algorithm that is supported by the hardware security module (HSM) or key management system that protects your key material. You must use the RSA PKCS #1 encryption scheme with one of three padding options, represented by the following choices. These choices are listed in order of AWS preference. The technical details of the schemes represented by these choices are explained in section 7 of the PKCS #1 Version 2.1 standard.

  • RSAES_OAEP_SHA_256 – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-256 hash function.

  • RSAES_OAEP_SHA_1 – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-1 hash function.

  • RSAES_PKCS1_V1_5 – The RSA encryption algorithm with the padding format defined in PKCS #1 Version 1.5.

Note

If you plan to try the Encrypt Key Material with OpenSSL proof-of-concept example in Step 3, use RSAES_OAEP_SHA_1.

If your HSM or key management system supports it, we recommend using RSAES_OAEP_SHA_256 to encrypt your key material. If that option is not available, you should use RSAES_OAEP_SHA_1. If neither of the OAEP options are available, you must use RSAES_PKCS1_V1_5. For information about how to encrypt your key material, see the documentation for the hardware security module or key management system that protects your key material.

The public key and import token are valid for 24 hours. If you don't use them to import key material within 24 hours of downloading them, you must download new ones.

To download the public key and import token, you can use the AWS Management Console or the AWS KMS API. You can use the API directly by making HTTP requests, or through one of the AWS SDKs or command line tools.

Downloading the Public Key and Import Token (Console)

You can use the AWS Management Console to download the public key and import token.

Note

AWS KMS recently introduced a new console that makes it easier for you to organize and manage your KMS resources. It is available in all AWS Regions that AWS KMS supports except for AWS GovCloud (US). We encourage you to try the new AWS KMS console at https://console.aws.amazon.com/kms.

The original console will remain available for a brief period to give you time to familiarize yourself with the new one. To use the original console, choose Encryption Keys in the IAM console or go to https://console.aws.amazon.com/iam/home?#/encryptionKeys. Please share your feedback by choosing Feedback in either console or in the lower-right corner of this page.

To download the public key and import token (new console)
  1. If you just completed the steps to create a CMK with no key material and you are on the Download wrapping key and import token page, skip to Step 7.

  2. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

  3. To change the AWS Region, use the Region selector in the upper-right corner of the page.

  4. In the navigation pane, choose Customer managed keys.

    Tip

    You can import key material into a CMK only when its Origin is EXTERNAL. This indicates that the CMK was created with no key material. To add the Origin column to your table, in the upper-right corner of the page, choose the settings icon ( ). Turn on Origin, and then choose Confirm.

  5. Choose the alias or key ID of the CMK that is pending import.

  6. Under Key material, choose Download wrapping key and import token.

    The Key material section appears only when the CMK was created with no key material. These CMKs have an Origin value of EXTERNAL. You cannot import key material into a CMK with any other Origin value. For information about creating CMKs with imported key material, see Importing Key Material in AWS Key Management Service (AWS KMS).

  7. For Select wrapping algorithm, choose the option that you will use to encrypt your key material. For more information about the options, see Select a Wrapping Algorithm in the preceding section.

    If you plan to try the Encrypt Key Material with OpenSSL proof-of-concept example in Step 3, choose RSAES_OAEP_SHA_1.

  8. Choose Download wrapping key and import token, and then save the file.

    If you have a Next option, to continue the process now, choose Next; to continue later, choose Cancel. Otherwise, to close the window, choose Cancel or click the X.

  9. Decompress the .zip file that you saved in the previous step (ImportParameters.zip).

    The folder contains the following files:

    • The wrapping key (public key), in a file named wrappingKey_CMK_key_ID_timestamp (for example, wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909). This is a 2048-bit RSA public key.

    • The import token, in a file named importToken_CMK_key_ID_timestamp (for example, importToken_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909).

    • A text file named README_CMK_key_ID_timestamp.txt (for example, README_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909.txt). This file contains information about the wrapping key (public key), the wrapping algorithm to use to encrypt your key material, and the date and time when the wrapping key (public key) and import token expire.

  10. To continue the process, see encrypt your key material.

To download the public key and import token (original console)

You can use the AWS Management Console to download the public key and import token. If you just completed the steps to create a CMK with no key material, skip to Step 6.

  1. If you just completed the steps to create a CMK with no key material, skip to Step 6.

  2. Sign in to the AWS Management Console and go to https://console.aws.amazon.com/iam/home?#/encryptionKeys.

  3. For Region, choose the appropriate AWS Region. Do not use the region selector in the navigation bar (top right corner).

  4. Choose the alias of the CMK for which you are downloading the public key and import token.

    Tip

    You can import key material into a CMK only when its Origin is EXTERNAL. This indicates that the CMK was created with no key material. To add the Origin column to your table, in the upper-right corner of the page, choose the settings icon ( ).

  5. In the Key Material section of the page, choose Download wrapping key and import token.

    The Key material section appears only when the CMK was created with no key material. These CMKs have an Origin value of EXTERNAL. You cannot import key material into a CMK with any other Origin value. For information about creating CMKs with imported key material, see Importing Key Material in AWS Key Management Service (AWS KMS).

  6. For Select wrapping algorithm, choose the option that you will use to encrypt your key material. For more information about the options, see the preceding section.

    If you plan to try the Encrypt Key Material with OpenSSL proof-of-concept example in Step 3, choose RSAES_OAEP_SHA_1.

  7. Choose Download wrapping key and import token, and then save the file.

  8. Decompress the .zip file that you saved in the previous step (ImportParameters.zip).

    The folder contains the following files:

    • The wrapping key (public key), in a file named wrappingKey_CMK_key_ID_timestamp (for example, wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909). This is a 2048-bit RSA public key.

    • The import token, in a file named importToken_CMK_key_ID_timestamp (for example, importToken_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909).

    • A text file named README_CMK_key_ID_timestamp.txt (for example, README_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909.txt). This file contains information about the wrapping key (public key), the wrapping algorithm to use to encrypt your key material, and the date and time when the wrapping key (public key) and import token expire.

    To continue the process now, proceed to the next step. Otherwise, choose Skip and do this later and then proceed to Step 3: Encrypt the Key Material.

  9. (Optional) To continue the process now, encrypt your key material. Then do one of the following:

    • If you are in the Import key material wizard, select the check box for I am ready to upload my exported key material and choose Next.

    • If you are in the key details page, choose Upload key material.

After you complete this step, proceed to Step 3: Encrypt the Key Material.

Downloading the Public Key and Import Token (KMS API)

To use the AWS KMS API to download the public key and import token, send a GetParametersForImport request that specifies the CMK for which you are downloading these items. The following example shows how to do this with the AWS CLI.

This example specifies RSAES_OAEP_SHA_1 as the encryption option. To specify a different option, replace RSAES_OAEP_SHA_1 with RSAES_OAEP_SHA_256 or RSAES_PKCS1_V1_5. Replace 1234abcd-12ab-34cd-56ef-1234567890ab with the key ID of the CMK for which to download the public key and import token. You can use the CMK's key ID or Amazon Resource Name (ARN), but you cannot use an alias for this operation.

Note

If you plan to try the Encrypt Key Material with OpenSSL proof-of-concept example in Step 3, specify RSAES_OAEP_SHA_1.

$ aws kms get-parameters-for-import --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --wrapping-algorithm RSAES_OAEP_SHA_1 \ --wrapping-key-spec RSA_2048

When the command is successful, you see output similar to the following:

{ "ParametersValidTo": 1470933314.949, "PublicKey": "public key base64 encoded data", "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "ImportToken": "import token base64 encoded data" }

When you receive this output, save the base64 encoded public key and import token in separate files. Then base64 decode each file into binary data and save the binary data in new files. Doing so prepares these items for later steps. See the following example.

To prepare the public key and import token for later steps

  1. Copy the public key's base64 encoded data (represented by public key base64 encoded data in the example output), paste it into a new file, and then save the file. Give the file a descriptive name, for example PublicKey.b64.

  2. Use OpenSSL to base64 decode the file's contents and save the decoded data to a new file. The following example decodes the data in the file that you saved in the previous step (PublicKey.b64) and saves the output to a new file named PublicKey.bin.

    $ openssl enc -d -base64 -A -in PublicKey.b64 -out PublicKey.bin

Repeat these two steps for the import token, and then proceed to Step 3: Encrypt the Key Material.