Step 4: Import the key material

After you encrypt your key material, you can import the key material to use with an AWS KMS key. To import key material, you upload the encrypted key material from Step 3: Encrypt the key material and the import token that you downloaded at Step 2: Download the wrapping public key and import token. You must import key material into the same KMS key that you specified when you downloaded the public key and import token. When key material is successfully imported, the key state of the KMS key changes to Enabled, and you can use the KMS key in cryptographic operations.

When you import key material, you can set an optional expiration time for the key material. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. To use the KMS key in cryptographic operations, you must reimport the same key material. After you import your key material, you cannot set, change, or cancel the expiration date for the current import. To change these values, you must delete and reimport the same key material.

To import key material, you can use the AWS KMS console or the ImportKeyMaterial API. You can use the API directly by making HTTP requests, or by using an AWS SDKs, AWS Command Line Interface or AWS Tools for PowerShell.

When you import the key material, an ImportKeyMaterial entry is added to your AWS CloudTrail log to record the ImportKeyMaterial operation. The CloudTrail entry is the same whether you use the AWS KMS console or the AWS KMS API.

Setting an expiration time (optional)

When you import the key material for your KMS key, you can set an optional expiration date and time for the key material of up to 365 days from the import date. When imported key material expires, AWS KMS deletes it. This action changes the key state of the KMS key to PendingImport, which prevents it from being used in any cryptographic operation. To use the KMS key, you must reimport a copy of the original key material.

Ensuring that imported key material expires frequently can help you to satisfy regulatory requirements, but it introduces an additional a risk to data encrypted under the KMS key. Until you reimport a copy of the original key material, a KMS key with expired key material is unusable, and any data encrypted under the KMS key is inaccessible. If you fail to reimport the key material for any reason, including losing your copy of the original key material, the KMS key is permanently unusable, and data encrypted under the KMS key is unrecoverable.

To mitigate this risk, make sure that your copy of the imported key material is accessible, and design a system to delete and reimport the key material before it expires and interrupts your AWS workload. We recommend that you set an alarm for the expiration of your imported key material that gives you plenty of time to reimport the key material before it expires. You can also use your CloudTrail logs to audit operations that import (and reimport) key material and delete imported key material, and the AWS KMS operation to delete expired key material.

You cannot import different key material into the KMS key, and AWS KMS cannot restore, recover, or reproduce the deleted key material. Instead of setting an expiration time, you can programmatically delete and reimport the imported key material periodically, but the requirements for retaining a copy of the original key material are the same.

You determine whether and when imported key material expires when you import the key material. But you can turn expiration on and off, or set a new expiration time by deleting and reimporting the key material. Use the ExpirationModel parameter of ImportKeyMaterial to turn expiration on (KEY_MATERIAL_EXPIRES) and off (KEY_MATERIAL_DOES_NOT_EXPIRE) and the ValidTo parameter to set the expiration time. The maximum time is 365 days from the import data; there is no minimum, but the time must be in the future.

Reimport key material

If you manage a KMS key with imported key material, you might need to reimport the key material. You might reimport key material to replace expiring or deleted key material, or to change the expiration model or expiration date of the key material.

When you import key material into a KMS key, the KMS key is permanently associated with that key material. You can reimport the same key material, but you cannot import different key material into that KMS key. You cannot rotate the key material and AWS KMS cannot create key material for a KMS key with imported key material.

You can reimport key material at any time, on any schedule that meets your security requirements. You do not have to wait until the key material is at or close to its expiration time.

The procedures to reimport key material are the same the same procedure that you use to import the key material the first time, with the following exceptions.

• Use an existing KMS key, instead of creating a new KMS key. You can skip Step 1 of the import procedure.

• When you reimport key material, you can change the expiration model and expiration date.

Each time you import key material to a KMS key, you need to download and use a new wrapping key and import token for the KMS key. The wrapping procedure does not affect the content of the key material, so you can use different wrapping public keys and different wrapping algorithms to import the same key material.

Import key material (console)

You can use the AWS Management Console to import key material.

1. If you are on the Upload your wrapped key material page, skip to Step 8.

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.

5. Choose the key ID or alias of the KMS key for which you downloaded the public key and import token.

6. Choose the Cryptographic configuration tab and view its values. The tabs are on the detail page for a KMS key below the General configuration section.

   You can only import key material into KMS keys with an Origin of External (Import key material). For information about creating KMS keys with imported key material, see Importing key material for AWS KMS keys.

7. Choose the Key material tab and then choose Import key material. The Key material tab appears only for KMS keys with an Origin value of External (Import key material).

   If you downloaded the key material, import token, and encrypted the key material, choose Next.

8. In the Encrypted key material and import token section, do the following.

   1. Under Wrapped key material, choose Choose file. Then upload the file that contains your wrapped (encrypted) key material.

   2. Under Import token, choose Choose file. Upload the file that contains the import token that you downloaded.

9. In the Expiration option section, you determine whether the key material expires. To set an expiration date and time, choose Key material expires, and use the calendar to select a date and time. You can specify a date up to 365 days from the current date and time.

10. Choose Upload key material.

Import key material (AWS KMS API)

To import key material, use the ImportKeyMaterial operation. The following example uses the AWS CLI, but you can use any supported programming language.

To use this example:

1. Replace 1234abcd-12ab-34cd-56ef-1234567890ab with a key ID of the KMS key that you specified when you downloaded the public key and import token. To identify the KMS key, use its key ID or key ARN. You cannot use an alias name or alias ARN for this operation.

2. Replace EncryptedKeyMaterial.bin with the name of the file that contains the encrypted key material.

3. Replace ImportToken.bin with the name of the file that contains the import token.

4. If you want the imported key material to expire, set the value of the expiration-model parameter to its default value, KEY_MATERIAL_EXPIRES, or omit the expiration-model parameter. Then, replace the value of the valid-to parameter with the date and time that you want the key material to expire. The date and time can be up to 365 days from the time of the request.

   $ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
       --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
       --import-token fileb://ImportToken.bin \
       --expiration-model KEY_MATERIAL_EXPIRES \
       --valid-to 2023-06-17T12:00:00-08:00

   If you do not want the imported key material to expire, set the value of the expiration-model parameter to KEY_MATERIAL_DOES_NOT_EXPIRE and omit the valid-to parameter from the command.

   $ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
       --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
       --import-token fileb://ImportToken.bin \
       --expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

Tip

If the command does not succeed, you might see a KMSInvalidStateException or a NotFoundException. You can retry the request.