Importing key material in Amazon KMS keys - Amazon Key Management Service
About imported key materialPermissions for importing key materialSetting an expiration time (optional)How to import key materialHow to reimport key materialHow to identify KMS keys with imported key materialHow to create an expiration alarmHow to delete imported key material
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 (PDF).

Importing key material in Amazon KMS keys

You can create a Amazon KMS keys (KMS key) with key material that you supply.

A KMS key is a logical representation of an encryption key. The metadata for a KMS key includes the ID of key material used to encrypt and decrypt data. When you create a KMS key, by default, Amazon KMS generates the key material for that KMS key. But you can create a KMS key without key material and then import your own key material into that KMS key, a feature often known as "bring your own key" (BYOK).

Note

Amazon KMS does not support decrypting any Amazon KMS ciphertext outside of Amazon KMS, even if the ciphertext was encrypted under a KMS key with imported key material. Amazon KMS does not publish the ciphertext format this task requires, and the format might change without notice.

Imported key material is supported only for symmetric encryption KMS keys in Amazon KMS key stores, including multi-Region symmetric encryption KMS keys. It is not supported on asymmetric KMS keys, HMAC KMS keys, or KMS keys in custom key stores.

When you use imported key material, you remain responsible for the key material while allowing Amazon KMS to use a copy of it. You might choose to do this for one or more of the following reasons:

  • To prove that you generated the key material using a source of entropy that meets your requirements.

  • To use key material from your own infrastructure with Amazon services, and to use Amazon KMS to manage the lifecycle of that key material within Amazon.

  • To set an expiration time for the key material in Amazon and to manually delete it, but to also make it available again in the future. In contrast, scheduling key deletion requires a waiting period of 7 to 30 days, after which you cannot recover the deleted KMS key.

  • To own the original copy of the key material, and to keep it outside of Amazon for additional durability and disaster recovery during the complete lifecycle of the key material.

When your import key material, you protect it in transit by encrypting it with the public key of an RSA key pair that Amazon KMS generates and sending it with an import token that uniquely identifies the KMS key. Before storing your imported key material, Amazon KMS re-encrypts it under an AES symmetric key within an Amazon KMS hardware security module.

You can monitor the use and management of a KMS key with imported key material. Amazon KMS records an entry in your Amazon CloudTrail log when you create the KMS key, download the public key and import token, and import the key material. Amazon KMS also records an entry when you manually delete imported key material or when Amazon KMS deletes expired key material.

For information about important differences between KMS keys with imported key material and those with key material generated by Amazon KMS, see About imported key material.

Regions

Imported key material is supported in all Amazon Web Services Regions that Amazon KMS supports. The requirements for imported key material are different in China Regions. For details, see Importing key material step 3: Encrypt the key material

Topics

About imported key material

Before you decide to import key material into Amazon KMS, you should understand the following characteristics of imported key material.

You generate the key material

You are responsible for generating the key material using a source of randomness that meets your security requirements. The key material you import must be a 256-bit symmetric encryption key, except in China Regions, where it must be a 128-bit symmetric encryption key.

You can delete the key material

You can delete imported key material from a KMS key, immediately rendering the KMS key unusable. Also, each time you import key material into your KMS key, you can turn expiration on and off and change the expiration time. When the expiration time arrives, Amazon KMS deletes the key material. Without key material, the KMS key cannot be used in any cryptographic operation. To restore the key, you must reimport the same key material into the key.

Can't change 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. Also, you cannot enable automatic key rotation for a KMS key with imported key material. However, you can manually rotate a KMS key with imported key material.

Can't change the key material origin

KMS keys designed for imported key material have an origin value of EXTERNAL that cannot be changed. You cannot convert a KMS key for imported key material to use key material from any other source, including Amazon KMS.

Can't decrypt with any other KMS key

When you encrypt data under a KMS key, the ciphertext is permanently associated with the KMS key and its key material. It cannot be decrypted with any other KMS key, including a different KMS key with the same key material. This is a security feature of KMS keys.

The only exception is multi-Region keys, which are designed to be interoperable. For details, see Why aren't all KMS keys with imported key material interoperable?.

No portability or escrow features

The symmetric ciphertexts that Amazon KMS produces are not portable. Amazon KMS does not publish the symmetric ciphertext format that portability requires, and the format might change without notice.

  • Amazon KMS cannot decrypt symmetric ciphertexts that you encrypt outside of Amazon, even if you use key material that you have imported.

  • Amazon KMS does not support decrypting any Amazon KMS symmetric ciphertext outside of Amazon KMS, even if the ciphertext was encrypted under a KMS key with imported key material.

Also, you cannot use any Amazon tools, such as the Amazon Encryption SDK or Amazon S3 client-side encryption, to decrypt Amazon KMS symmetric ciphertexts.

As a result, you cannot use keys with imported key material to support key escrow arrangements where an authorized third party with conditional access to key material can decrypt certain ciphertexts outside of Amazon KMS. To support key escrow, use the Amazon Encryption SDK to encrypt your message under a key that is independent of Amazon KMS.

You're responsible for availability and durability

You are responsible for the key material's overall availability and durability. Amazon KMS is designed to keep imported key material highly available. But Amazon KMS does not maintain the durability of imported key material at the same level as key material that Amazon KMS generates. To restore imported key material that has been deleted from a KMS key, you must retain a copy of the key material in a system that you control. We recommend that you store an exportable copy of the imported key material in a key management system, such as a hardware security module (HSM).

This difference is meaningful in the following cases:

  • When you set an expiration time for your imported key material, Amazon KMS deletes the key material after it expires. Amazon KMS does not delete the KMS key or its metadata. You can create a Amazon CloudWatch alarm that notifies you when imported key material is approaching its expiration date.

    You cannot delete key material that Amazon KMS generates for a KMS key and you cannot set Amazon KMS key material to expire, although you can rotate it.

  • When you manually delete imported key material, Amazon KMS deletes the key material but does not delete the KMS key or its metadata. In contrast, scheduling key deletion requires a waiting period of 7 to 30 days, after which Amazon KMS permanently deletes the KMS key, its metadata, and its key material.

  • In the unlikely event of certain region-wide failures that affect Amazon KMS (such as a total loss of power), Amazon KMS cannot automatically restore your imported key material. However, Amazon KMS can restore the KMS key and the metadata.

Permissions for importing key material

To create and manage KMS keys with imported key material, the user needs permission for the operations in this process. You can provide the kms:GetParametersForImport, kms:ImportKeyMaterial, and kms:DeleteImportedKeyMaterial permissions in the key policy when you create the KMS key. In the Amazon KMS console, these permissions are added automatically for key administrators when you create a key with an External key material origin.

To create KMS keys with imported key material, the principal needs the following permissions.

  • kms:CreateKey (IAM policy)

    • To limit this permission to KMS keys with imported key material, use the kms:KeyOrigin policy condition with a value of EXTERNAL.

      {
  "Sid": "CreateKMSKeysWithoutKeyMaterial",
  "Effect": "Allow",
  "Resource": "*",
  "Action": "kms:CreateKey",
  "Condition": {
    "StringEquals": {
      "kms:KeyOrigin": "EXTERNAL"
    }
  }
}

  • kms:GetParametersForImport (Key policy or IAM policy)

  • kms:ImportKeyMaterial (Key policy or IAM policy)

To reimport imported key material, the principal needs the kms:GetParametersForImport and kms:ImportKeyMaterial permissions.

To delete imported key material, the principal needs kms:DeleteImportedKeyMaterial permission.

For example, to give the example KMSAdminRole permission to manage all aspects of a KMS key with imported key material, include a key policy statement like the following one in the key policy of the KMS key.

{
  "Sid": "Manage KMS keys with imported key material",
  "Effect": "Allow",
  "Resource": "*",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/KMSAdminRole"
  },
  "Action": [
    "kms:GetParametersForImport",
    "kms:ImportKeyMaterial",
    "kms:DeleteImportedKeyMaterial"
  ]  
}

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, Amazon 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. When you reimport the key material, you can turn expiration on and off and set a new expiration time.

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 Amazon 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 Amazon KMS operation to delete expired key material.

You cannot import different key material into the KMS key, and Amazon 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.

How to import key material

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

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

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

  3. Encrypt the key material – Use the 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, Amazon 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.

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

How to 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 set, eliminate, or change the expiration time of the key material. You cannot convert a KMS key designed for imported key material to one with Amazon KMS 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.

  • You must reimport the same key material that was originally imported into the KMS key. You cannot import different key material into a KMS key.

  • If the KMS key has imported key material, you must delete the existing imported key material before you reimport the key material.

  • You must download a new public key and import token for each import operation. You can use the same or a different wrapping algorithm for each import operation on a KMS key.

  • When you reimport key material, you can turn expiration on and off, and change the expiration time.

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 keys (and different import tokens) to import the same key material.

How to identify 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 Amazon 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 Amazon KMS console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services 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 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 (Amazon 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-03-08T12: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, Amazon 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 Amazon 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.

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, Amazon KMS deletes the key material. In either case, Amazon KMS deletes the key material immediately, the key state of the KMS key changes to pending import, and the KMS key can't be used in any cryptographic operations.

However, these actions do not delete the KMS key. To use the KMS key again, you must reimport the same key material into the KMS key. In contrast, deleting a KMS key is irreversible. If you schedule key deletion and the required waiting period expires, Amazon KMS deletes the key material and all metadata associated with the KMS key.

To delete key material, 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 anAmazon SDK, the Amazon Command Line Interface (Amazon CLI), or Amazon Tools for PowerShell.

Amazon KMS records an entry in your Amazon CloudTrail log when you delete imported key material and when Amazon KMS deletes expired key material.

How deleting key material affects Amazon 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 the KMS key is used again, such as to decrypt the data key. This issue affects Amazon Web 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 Amazon Web Services Management Console to delete key material.

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

  2. To change the Amazon Web Services 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 (Amazon KMS API)

To use the Amazon KMS API to delete key material, send a DeleteImportedKeyMaterial request. The following example shows how to do this with the Amazon 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