# Importing key material for AWS KMS keys
<a name="importing-keys"></a>

You can create an AWS KMS keys (KMS key) with key material that you supply. 

A KMS key is a logical representation of a data key. The metadata for a KMS key includes the ID of the key material used to perform cryptographic operations. When you [create a KMS key](create-keys.md), by default, AWS 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).

![\[Key icon that highlights the key material that it represents.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/import-key.png)


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

When you use imported key material, you remain responsible for the key material while allowing AWS KMS to use a copy of it. You might choose to do this for one or more of the following reasons:
+ To prove the key material was generated using a source of entropy that meets your requirements. 
+ To use key material from your own infrastructure with AWS services, and to use AWS KMS to manage the lifecycle of that key material within AWS.
+ To use existing, well-established keys in AWS KMS, such as keys for code signing, PKI certificate signing, and certificate pinned applications
+ To set an expiration time for the key material in AWS and to [manually delete it](importing-keys-delete-key-material.md), but to also make it available again in the future. In contrast, [scheduling key deletion](deleting-keys.md#deleting-keys-how-it-works) 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 AWS for additional durability and disaster recovery during the complete lifecycle of the key material.
+ For asymmetric keys and HMAC keys, importing creates compatible and interoperable keys that operate within and outside of AWS.

**Supported KMS key types**

AWS KMS supports imported key material for the following types of KMS keys. You cannot import key material into KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview).
+ [Symmetric encryption KMS keys](symm-asymm-choose-key-spec.md#symmetric-cmks)
+ [Asymmetric KMS keys (except ML-DSA keys)](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ [Multi-Region keys](multi-region-keys-overview.md) of all supported types.

**Regions**

Imported key material is supported in all AWS Regions that AWS KMS supports.

In China Regions, the key material requirements for symmetric encryption KMS keys differ from other Regions. For details, see [Step 3: Encrypt the key material](importing-keys-encrypt-key-material.md).

**Learn more**
+ To create KMS keys with imported key material, see [Create a KMS key with imported key material](importing-keys-conceptual.md).
+ To create an alarm that notifies you when the imported key material in a KMS key is approaching its expiration time, see [Create a CloudWatch alarm for expiration of imported key material](imported-key-material-expiration-alarm.md).
+ To reimport key material into a KMS key, see [Reimport key material](importing-keys-import-key-material.md#reimport-key-material).
+ To import new key material into a KMS key for on-demand rotation, see [Import new key material](importing-keys-import-key-material.md#import-new-key-material) and [Perform on-demand key rotation](rotating-keys-on-demand.md). 
+ To identify and view KMS keys with imported key material, see [Identify KMS keys with imported key material](identify-key-types.md#identify-imported-keys).
+ To learn about special considerations for deleting KMS keys with imported key material, see [Deleting KMS keys with imported key material](deleting-keys.md#import-delete-key).

# Special considerations for imported key material
<a name="importing-keys-considerations"></a>

Before you decide to import key material into AWS 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.

**You're responsible for availability and durability**  
AWS KMS is designed to keep imported key material highly available. But AWS KMS does not maintain the durability of imported key material at the same level as key material that AWS KMS generates. For details, see [Protecting imported key material](import-keys-protect.md).

**You can delete the key material**  
You can [delete imported key material](importing-keys-delete-key-material.md) 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 time](importing-keys-import-key-material.md#importing-keys-expiration). When the expiration time arrives, AWS KMS [deletes the key material](importing-keys-delete-key-material.md). 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. 

**You cannot change the key material for asymmetric, and HMAC keys**  
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](importing-keys-import-key-material.md#reimport-key-material), but you cannot import different key material into that KMS key. Also, you cannot [enable automatic key rotation](rotate-keys.md) for a KMS key with imported key material. However, you can [manually rotate a KMS key](rotate-keys-manually.md) with imported key material. 

**You can perform on-demand rotation on symmetric encryption keys**  
Symmetric encryption keys with imported key material support on-demand rotation. You can [import multiple key materials ](importing-keys-import-key-material.md#import-new-key-material) into these keys and use [on-demand rotation](rotating-keys-on-demand.md) to update the current key material. The current key material is used for both encryption and decryption but other (non-current) key materials can only be used for decryption. 

**You cannot change the key material origin**  
KMS keys designed for imported key material have an [origin](create-keys.md#key-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 AWS KMS. Similarly, you cannot convert a KMS key with AWS KMS key material into one designed for imported key material.

**You cannot export key material**  
You cannot export any key material that you imported. AWS KMS cannot return the imported key material to you in any form. You must maintain a copy of your imported key material outside of AWS, preferably in a key manager, such as a hardware security module (HSM), so you can reimport the key material if you delete it or it expires.

**You can create multi-Region keys with imported key material**  
Multi-Region with imported key material have the features of KMS keys with imported key material, and can interoperate between AWS Regions. To create a multi-Region key with imported key material, you must import the same key material into the primary KMS key and into each replica key. For more details on importing key materials for multi-Region keys, see [Import new key material](importing-keys-import-key-material.md#import-new-key-material).

**Asymmetric keys and HMAC keys are portable and interoperable**  
You can use your asymmetric key material and HMAC key material outside of AWS to interoperate with AWS KMS keys with the same imported key material.   
Unlike the AWS KMS symmetric ciphertext, which is inextricably bound to the KMS key used in the algorithm, AWS KMS uses standard HMAC and asymmetric formats for encryption, signing, and MAC generation. As a result, the keys are portable and support traditional escrow key scenarios.  
When your KMS key has imported key material, you can use the imported key material outside of AWS to perform the following operations.  
+ HMAC keys — You can verify a HMAC tag that was generated by the HMAC KMS key with imported key material. You can also use the HMAC KMS key with the imported key material to verify an HMAC tag that was generated by the key material outside of AWS.
+ Asymmetric encryption keys — You can use your private asymmetric encryption key outside of AWS to decrypt a ciphertext encrypted by the KMS key with the corresponding public key. You can also use your asymmetric KMS key to decrypt an asymmetric ciphertext that was generated outside of AWS.
+ Asymmetric signing keys — You can use your asymmetric signing KMS key with imported key material to verify digital signatures generated by your private signing key outside of AWS. You can also use your asymmetric public signing key outside of AWS to verify signatures generated by your asymmetric KMS key.
+ Asymmetric key agreement keys — You can use your asymmetric key agreement KMS key with imported key material to derive shared secrets with a peer outside of AWS.
If you import the same key material into different KMS keys in the same AWS Region, those keys are also interoperable. To create interoperable KMS keys in different AWS Regions, create a multi-Region key with imported key material.  

**RSA private keys**
+ AWS KMS requires imported RSA private keys to have prime factors that conform to the test described in [FIPS 186-5, Section A. 1.3](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf). Other software or devices may use different algorithms for validating these prime factors of RSA private keys. In rare instances, keys validated using other algorithms may not be accepted by AWS KMS.

**Symmetric encryption keys are not portable or interoperable**  
The symmetric ciphertexts that AWS KMS produces are not portable or interoperable. AWS KMS does not publish the symmetric ciphertext format that portability requires, and the format might change without notice.   
+ AWS KMS cannot decrypt symmetric ciphertexts that you encrypt outside of AWS, even if you use key material that you have imported. 
+ AWS KMS does not support decrypting any AWS KMS symmetric ciphertext outside of AWS KMS, even if the ciphertext was encrypted under a KMS key with imported key material.
+ KMS keys with the same imported key material are not interoperable. The symmetric ciphertext that AWS KMS generates ciphertext that is specific to each KMS key. This ciphertext format guarantees that only the KMS key that encrypted data can decrypt it. 
Also, you cannot use any AWS tools, such as the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/) or [Amazon S3 client-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingClientSideEncryption.html), to decrypt AWS 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 AWS KMS. To support key escrow, use the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/java-example-code.html#java-example-multiple-providers) to encrypt your message under a key that is independent of AWS KMS.

# Protecting imported key material
<a name="import-keys-protect"></a>

The key material that you import is protected in transit and at rest. Before importing the key material, you encrypt (or "wrap") the key material with the public key of an RSA key pair generated in AWS KMS hardware security modules (HSMs) validated under the [FIPS 140-3 Cryptographic Module Validation Program](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884). You can encrypt the key material directly with the wrapping public key, or encrypt the key material with an AES symmetric key, and then encrypt the AES symmetric key with the RSA public key.

Upon receipt, AWS KMS decrypts the key material with the corresponding private key in a AWS KMS HSM and re-encrypts it under an AES symmetric key that exists only in the volatile memory of the HSM. Your key material never leaves the HSM in plain text. It is decrypted only while it is in use and only within AWS KMS HSMs.

Use of your KMS key with imported key material is determined solely by the [access control policies](control-access.md) that you set on the KMS key. In addition, you can use [aliases](kms-alias.md) and [tags](tagging-keys.md) to identify and [control access](abac.md) to the KMS key. You can [enable and disable](enabling-keys.md) the key, [view](viewing-keys.md), and [monitor](monitoring-overview.md) it using services like AWS CloudTrail. 

However, you maintain the only failsafe copy of your key material. In return for this extra measure of control, you are responsible for durability and overall availability of the imported key material. AWS KMS is designed to keep imported key material highly available. But AWS KMS does not maintain the durability of imported key material at the same level as key material that AWS KMS generates.

This difference in durability is meaningful in the following cases:
+ When you [set an expiration time](importing-keys-import-key-material.md#importing-keys-expiration) for your imported key material, AWS KMS deletes the key material after it expires. AWS KMS does not delete the KMS key or its metadata. You can [create a Amazon CloudWatch alarm](imported-key-material-expiration-alarm.md) that notifies you when imported key material is approaching its expiration date.

  You cannot delete key material that AWS KMS generates for a KMS key and you cannot set AWS KMS key material to expire.
+ When you [manually delete imported key material](importing-keys-delete-key-material.md), AWS KMS deletes the key material but does not delete the KMS key or its metadata. In contrast, [scheduling key deletion](deleting-keys.md#deleting-keys-how-it-works) requires a waiting period of 7 to 30 days, after which AWS KMS permanently deletes the KMS key, its metadata, and its key material.
+ In the unlikely event of certain region-wide failures that affect AWS KMS (such as a total loss of power), AWS KMS cannot automatically restore your imported key material. However, AWS KMS can restore the KMS key and its metadata.

You *must* retain a copy of the imported key material outside of AWS 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 an HSM. As a best practice, you should store a reference to the KMS key ARN and the key material ID generated by AWS KMS alongside the exportable copy of the key material. If your imported key material is deleted or expires, its associated KMS key becomes unusable until you reimport the same key material. If your imported key material is permanently lost, any ciphertext encrypted under the KMS key is unrecoverable. 

**Important**  
Symmetric encryption keys can have multiple key materials associated with them. The entire KMS key becomes unusable as soon as you delete any one of those key materials or if any one of those key materials expires (unless the deleted or expiring key material is `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`). You must reimport any expired or deleted key materials associated with such a key before the key becomes usable for cryptographic operations.