Importing key material in Amazon KMS keys - 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 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.

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

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

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, when you import key material into a KMS key, you can determine whether the key expires and set its expiration date. When the expiration date 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 ciphertexts that Amazon KMS produces are not portable. 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.

Also, you cannot use any Amazon tools, such as the Amazon Encryption SDK or Amazon S3 client-side encryption, to decrypt Amazon KMS 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. Then, you can reimport it into the KMS key.

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 cannot delete key material that Amazon KMS generates from 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. The kms:ImportKeyMaterial permission is not included in the default permissions for key administrators, so you need to add it manually.

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.

      { "Version": "2012-10-17", "Statement": { "Sid": "IAM policy to create KMS keys with no key material" "Effect": "Allow", "Resource": "*", "Principal": { "AWS": "arn:aws:iam::111122223333:role/KMSAdminRole" }, "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.

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.

    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 expired or deleted key material. You might also reimport key material to change the expiration model or expiration date of the key material.

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. Also, Amazon KMS cannot create key material for a KMS key that is created without key material.

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.

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

  • 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 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": 1568894400.0, "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "AWSAccountId": "111122223333", "CreationDate": 1568289600.0, "Enabled": false, "MultiRegion": false, "Description": "", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "PendingImport", "KeyManager": "CUSTOMER", "KeySpec": "SYMMETRIC_DEFAULT", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ] } }