Importing key material step 2: Download the public key and import token - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Importing key material step 2: Download the public key and import token

After you create a symmetric Amazon KMS key with no key material, you download a public key and an import token for that KMS key. You need these items to import your key material. You can download both items in one step by using the Amazon Web Services Management Console or the Amazon KMS API.

You can also download these items when you want to reimport the same key material into a KMS key. You might do this to change the expiration time for the key material, or to restore expired or deleted key material.

Use of the public key

When you import key material, you don't upload the raw key material to Amazon 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 Amazon KMS. When Amazon KMS receives your encrypted key material, it uses the corresponding private key to decrypt it. The public key that you receive from Amazon KMS is a 2048-bit RSA public key and is always unique to your Amazon Web Services 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 Amazon 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 Amazon 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 Amazon Web Services Management Console or the Amazon KMS API. You can use the API directly by making HTTP requests, or by using an Amazon SDKs, Amazon Command Line Interface or Amazon Tools for PowerShell.

When you download the public key and import token, a GetParametersForImport entry is added to your Amazon CloudTrail log to record the GetParametersForImport operation. The CloudTrail entry is the same whether you use the Amazon KMS console or the Amazon KMS API.

Downloading the public key and import token (console)

You can use the Amazon Web Services Management Console to download the public key and import token.

  1. If you just completed the steps to create a KMS key with no key material and you are on the Download wrapping key and import token page, skip to Step 8.

  2. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  3. To change the Amazon 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 only into a symmetric KMS key with an Origin of EXTERNAL. This indicates that the KMS key 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 KMS key that is pending import.

  6. Choose the Cryptographic configuration tab and view its values. The tabs are below the General configuration section.

    You can only import key material into KMS keys with a Key type of Symmetric and an Origin of EXTERNAL. For information about creating KMS keys with imported key material, see, Importing key material in Amazon KMS keys.

  7. Choose the Key material tab and then choose Download wrapping key and import token.

    The Key material tab appears only for symmetric KMS keys that have an Origin value of EXTERNAL.

  8. 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.

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

  9. 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.

  10. 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_KMS key_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_KMS key_key_ID_timestamp (for example, importToken_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909).

    • A text file named README_KMS key_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.

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

Downloading the public key and import token (Amazon KMS API)

To use the Amazon KMS API to download the public key and import token, send a GetParametersForImport request that specifies the KMS key for which you are downloading these items. The following example shows how to do this with the Amazon 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 KMS key for which to download the public key and import token. You can use the KMS key'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": 1568290320.0, "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.