Managing imported key material

These topics explain how to import and reimport key material into a KMS key and how to create imported key material that automatically expires.

Overview of importing key material

The following overview explains how to import your key material into AWS KMS. For more details about each step in the process, see the corresponding topic.

1. Create a KMS key with no key material – The origin must be EXTERNAL. A key origin of EXTERNAL indicates that the key is designed for imported key material and prevents AWS KMS from generating key material for the KMS key. In a later step you will import your own key material into this KMS key.

   The key material that you import must be compatable with the key spec of the associated AWS KMS key. For more information about compatability, see Requirements for imported key material.

2. Download the wrapping public key and import token – After completing step 1, download a wrapping public key and an import token. These items protect your key material while it's imported to AWS KMS.

   In this step, you choose the type ("key spec") of the RSA wrapping key and the wrapping algorithm that you'll use to encrypt your data in transit to AWS KMS. You can choose a different wrapping key spec and wrapping key algorithm each time you import or reimport the same key material.

3. Encrypt the key material – Use the wrapping public key that you downloaded in step 2 to encrypt the key material that you created on your own system.

4. Import the key material – Upload the encrypted key material that you created in step 3 and the import token that you downloaded in step 2.

   At this stage, you can set an optional expiration time. When imported key material expires, AWS KMS deletes it, and the KMS key becomes unusable. To continue to use the KMS key, you must reimport the same key material.

   When the import operation completes successfully, the key state of the KMS key changes from PendingImport to Enabled. You can now use the KMS key in cryptographic operations.

AWS KMS records an entry in your AWS CloudTrail log when you create the KMS key, download the wrapping public key and import token, and import the key material. AWS KMS also records an entry when you delete imported key material or when AWS KMS deletes expired key material.

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

To reimport key material, use the same procedure that you used 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.

Identifying KMS keys with imported key material

When you create a KMS key with no key material, the value of the Origin property of the KMS key is EXTERNAL, and it cannot be changed. Unlike the key state, the Origin value doesn't depend on the presence or absence of key material.

You can use the EXTERNAL origin value to identify KMS keys designed for imported key material. You can find the key origin in the AWS KMS console or by using the DescribeKey operation. You can also view the properties of the key material, such as whether and when it expires by using the console or the APIs.

To identify KMS keys with imported key material (console)

1. Open the AWS KMS console at https://console.aws.amazon.com/kms.

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

3. Use either of the following techniques to view the Origin property of your KMS keys.

   • To add an Origin column to your KMS key table, in the upper right corner, choose the Settings icon. Choose Origin and choose Confirm. The Origin column makes it easy to identify KMS keys with an External (Import Key material) origin property value.

   • To find the value of the Origin property of a particular KMS key, choose the key ID or alias of the KMS key. Then choose the Cryptographic configuration tab. The tabs are below the General configuration section.

4. To view detailed information about the key material, choose the Key material tab. This tab appears on the detail page only for KMS keys with imported key material.

To identify KMS keys with imported key material (AWS KMS API)

Use the DescribeKey operation. The response includes the Origin property of the KMS key, the expiration model, and the expiration date, as shown in the following example.

$  aws kms describe-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "KeyMetadata": {
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Origin": "EXTERNAL",
        "ExpirationModel": "KEY_MATERIAL_EXPIRES"
        "ValidTo": 2023-06-05T12:00:00+00:00,
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": 2018-06-09T00:06:50.831000+00:00,
        "Enabled": false,
        "MultiRegion": false,
        "Description": "",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "PendingImport",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

Creating a CloudWatch alarm for expiration of imported key material

You can create a CloudWatch alarm that notifies you when the imported key material in a KMS key is approaching its expiration time. For example, the alarm can notify you when the time to expire is less than 30 days away.

When you import key material into a KMS key, you can optionally specify a date and time when the key material expires. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. To use the KMS key again, you must reimport the key material. However, if you reimport the key material before it expires, you can avoid disrupting processes that use that KMS key.

This alarm uses the SecondsUntilKeyMaterialExpires metric that AWS KMS publishes to CloudWatch for KMS keys with imported key material that expires. Each alarm uses this metric to monitor the imported key material for a particular KMS key. You cannot create a single alarm for all KMS keys with expiring key material or an alarm for KMS keys that you might create in the future.

Requirements

The following resources are required for a CloudWatch alarm that monitors the expiration of imported key material.

• A KMS key with imported key material that expires. For help, see Identifying KMS keys with imported key material.

• An Amazon SNS topic. For details, see Creating an Amazon SNS topic in the Amazon CloudWatch User Guide.

Create the alarm

Follow the instructions in Create a CloudWatch alarm based on a static threshold using the following required values. For other fields, accept the default values and provide names as requested.

Field	Value
Select metric	Choose KMS, then choose Per-Key Metrics. Choose the row with the KMS key and the SecondsUntilKeyMaterialExpires metric. Then choose Select metric. The Metrics list displays the SecondsUntilKeyMaterialExpires metric only for KMS keys with imported key material that expires. If you don't have KMS keys with these properties in the account and Region, this list is empty.
Statistic	Minimum
Period	1 minute
Threshold type	Static
Whenever ...	Whenever metric-name is Greater than 1

Deleting imported key material

You can delete the imported key material from a KMS key at any time. Also, when imported key material with an expiration date expires, AWS KMS deletes the key material. In either case, when the key material is deleted, the key state of the KMS key changes to pending import, and the KMS key can't be used in any cryptographic operations until you reimport the same key material. (You cannot import any other key material into the KMS key.)

Along with disabling the KMS key and withdrawing permissions, deleting key material can be used as a strategy to quickly, but temporarily, halt the use of the KMS key. In contrast, scheduling the deletion of a KMS key with imported key material also quickly halts the use of the KMS key. However, if the deletion is not canceled during the waiting period, the KMS key, the key material, and all key metadata are permanently deleted. For details, see Deleting a KMS key with imported key material.

To delete key material, you can use the AWS KMS console or the DeleteImportedKeyMaterial API operation. AWS KMS records an entry in your AWS CloudTrail log when you delete imported key material and when AWS KMS deletes expired key material.

Topics

• How deleting key material affects AWS services
• Delete key material (console)
• Delete key material (AWS KMS API)

How deleting key material affects AWS services

When you delete key material, the KMS key with no key material becomes unusable right away (subject to eventual consistency). However, resources encrypted with data keys protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see How unusable KMS keys affect data keys.

Delete key material (console)

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

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

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

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

4. Do one of the following:

   • Select the check box for a KMS key with imported key material. Choose Key actions, Delete key material.

   • Choose the alias or key ID of a KMS key with imported key material. Choose the Key material tab and then choose Delete key material.

5. Confirm that you want to delete the key material and then choose Delete key material. The KMS key's status, which corresponds to its key state, changes to Pending import.

Delete key material (AWS KMS API)

To use the AWS KMS API to delete key material, send a DeleteImportedKeyMaterial request. The following example shows how to do this with the AWS CLI.

Replace 1234abcd-12ab-34cd-56ef-1234567890ab with the key ID of the KMS key whose key material you want to delete. You can use the KMS key's key ID or ARN but you cannot use an alias for this operation.

$ aws kms delete-imported-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Deleting a KMS key with imported key material

Deleting the key material of a KMS key with imported key material is temporary and reversible. To restore the key, reimport its key material.

In contrast, deleting a KMS key is irreversible. If you schedule key deletion and the required waiting period expires, AWS KMS permanently and irreversibly deletes the KMS key, its key material, and all metadata associated with the KMS key.

However, the risk and consequence of deleting a KMS key with imported key material depends on the type ("key spec") of the KMS key.

• Symmetric encryption keys — If you delete a symmetric encryption KMS key, all remaining ciphertexts encrypted by that key are unrecoverable. You cannot create a new symmetric encryption KMS key that can decrypt the ciphertexts of a deleted symmetric encryption KMS key, even if you have the same key material. Metadata unique to each KMS key is cryptographically bound to each symmetric ciphertext. This security feature guarantees that only the KMS key that encrypted the symmetric ciphertext can decrypt it, but it prevents you from recreating an equivalent KMS key.

• Asymmetric and HMAC keys — If you have the original key material, you can create a new KMS key with the same cryptographic properties as an asymmetric or HMAC KMS key that was deleted. AWS KMS generates standard RSA ciphertexts and signatures, ECC signatures, and HMAC tags, which do not include any unique security features. Also, you can use an HMAC key or the private key of an asymmetric key pair outside of AWS.

  A new KMS key that you create with the same asymmetric or HMAC key material will have a different key identifier. You will have to create a new key policy, recreate any aliases, and update existing IAM policies and grants to refer to the new key.