# Create a KMS key with imported key material
Imported key material lets you protect your AWS resources under cryptographic keys that you generate. 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 topics.
1. [Create a KMS key with no key material](importing-keys-create-cmk.md) – 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 compatible with the key spec of the associated AWS KMS key. For more information about compatibility, see [Requirements for imported key material](#importing-keys-material-requirements).
1. [Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md) – 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.
1. [Encrypt the key material](importing-keys-encrypt-key-material.md) – Use the wrapping public key that you downloaded in step 2 to encrypt the key material that you created on your own system.
1. [Import the key material](importing-keys-import-key-material.md) – 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](importing-keys-import-key-material.md#importing-keys-expiration). 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](ct-createkey.md), [download the wrapping public key and import token](ct-getparametersforimport.md), and [import the key material](ct-importkeymaterial.md). AWS KMS also records an entry when you delete imported key material or when AWS KMS [deletes expired key material](ct-deleteexpiredkeymaterial.md).
## 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 AWS 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](customer-managed-policies.md#iam-policy-example-create-key) (IAM policy)
+ To limit this permission to KMS keys with imported key material, use the [kms:KeyOrigin](conditions-kms.md#conditions-kms-key-origin) policy condition with a value of `EXTERNAL`.
```
{
"Sid": "CreateKMSKeysWithoutKeyMaterial",
"Effect": "Allow",
"Resource": "*",
"Action": "kms:CreateKey",
"Condition": {
"StringEquals": {
"kms:KeyOrigin": "EXTERNAL"
}
}
}
```
+ [kms:GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) (Key policy or IAM policy)
+ To limit this permission to requests that use a particular wrapping algorithm and wrapping key spec, use the [kms:WrappingAlgorithm](conditions-kms.md#conditions-kms-wrapping-algorithm) and [kms:WrappingKeySpec](conditions-kms.md#conditions-kms-wrapping-key-spec) policy conditions.
+ [kms:ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) (Key policy or IAM policy)
+ To allow or prohibit key material that expires and control the expiration date, use the [kms:ExpirationModel](conditions-kms.md#conditions-kms-expiration-model) and [kms:ValidTo](conditions-kms.md#conditions-kms-valid-to) policy conditions.
To reimport imported key material, the principal needs the [kms:GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) and [kms:ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) permissions.
To delete imported key material, the principal needs [kms:DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) 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"
]
}
```
## Requirements for imported key material
The key material that you import must be compatible with the [key spec](create-keys.md#key-spec) of the associated KMS key. For asymmetric key pairs, import only the private key of the pair. AWS KMS derives the public key from the private key.
AWS KMS supports the following key specs for KMS keys with imported key material.
+ **Symmetric encryption keys**
+ **Key spec:**
+ SYMMETRIC\$1DEFAULT.
+ **Requirements:**
+ 256-bits (32 bytes) of binary data.
+ In China Regions, it must be a 128-bits (16 bytes) of binary data.
+ **HMAC keys**
+ **Key specs:**
+ HMAC\$1224
+ HMAC\$1256
+ HMAC\$1384
+ HMAC\$1512
+ **Requirements:**
+ HMAC key material must conform to [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104).
+ The key length must be at least the same length specified by the key spec. The maximum key length is 1024-bits.
+ If your key material exceeds 1024 bits, you can hash the key material and import the hash output. The hashing algorithm must match the key spec of the HMAC KMS key you're creating.
+ **Example:**
+ To import 2048 bits of key material into an HMAC\$1256 key, first compute the SHA-256 hash of the 2048-bit key material, then import the resulting 256-bit hash output into the KMS key.
+ **Valid key lengths:**
+ HMAC\$1224: 224–1024 bits
+ HMAC\$1256: 256–1024 bits
+ HMAC\$1384: 384–1024 bits
+ HMAC\$1512: 512–1024 bits
+ **RSA asymmetric private key**
+ **Key specs:**
+ RSA\$12048
+ RSA\$13072
+ RSA\$14096
+ **Requirements:**
+ The RSA asymmetric private key that you import must be part of a key pair that conforms to [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447/).
+ **Modulus:** 2048 bits, 3072 bits or 4096 bits
+ **Number of primes:** 2 (multi-prime RSA keys are not supported)
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
+ **Elliptic curve asymmetric private key**
+ **Key specs:**
+ ECC\$1NIST\$1P256 (secp256r1)
+ ECC\$1NIST\$1P384 (secp384r1)
+ ECC\$1NIST\$1P521 (secp521r1)
+ ECC\$1SECG\$1P256K1 (secp256k1)
+ ECC\$1NIST\$1EDWARDS25519 (ed25519)
+ **Requirements:**
+ The ECC asymmetric private key that you import must be part of a key pair that conforms to [RFC 5915](https://datatracker.ietf.org/doc/html/rfc5915/).
+ **Curve:** NIST P-256, NIST P-384, NIST P-521, Secp256k1, NIST Ed25519.
+ **Parameters:** Named curves only (ECC keys with explicit parameters are rejected).
+ **Public point coordinates:** May be compressed, uncompressed, or projective.
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
+ **ML-DSA key**
+ **Key specs:**
+ ML\$1DSA\$144
+ ML\$1DSA\$165
+ ML\$1DSA\$187
**Important**
Importing ML-DSA keys is not supported.
+ **SM2 asymmetric private key** (China Regions only)
+ **Requirements:**
+ The SM2 asymmetric private key that you import must be part of a key pair that conforms to GM/T 0003.
+ **Curve:** SM2.
+ **Parameters:** Named curve only (SM2 keys with explicit parameters are rejected).
+ **Public point coordinates:** May be compressed, uncompressed, or projective.
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
# Step 1: Create an AWS KMS key without key material
By default, AWS KMS creates key material for you when you create a KMS key. To import your own key material instead, start by creating a KMS key with no key material. Then import the key material. To create a KMS key with no key material, use AWS KMS console or the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
To create a key with no key material, specify an [origin](create-keys.md#key-origin) of `EXTERNAL`. The origin property of a KMS key is immutable. Once you create it, you cannot convert a KMS key designed for imported key material into a KMS key with key material from AWS KMS or any other source.
The [key state](key-state.md) of a KMS key with an `EXTERNAL` origin and no key material is `PendingImport`. A KMS key can remain in `PendingImport` state indefinitely. However, you cannot use a KMS key in `PendingImport` state in cryptographic operations. When you import key material, the key state of the KMS key changes to `Enabled`, and you can use it in cryptographic operations.
AWS KMS records an event in your AWS CloudTrail log when you [create the KMS key](ct-createkey.md), [download the public key and import token](ct-getparametersforimport.md), and [import the key material](ct-importkeymaterial.md). AWS KMS also records a CloudTrail event when you [delete imported key material](ct-deleteimportedkeymaterial.md) or when AWS KMS [deletes expired key material](ct-deleteexpiredkeymaterial.md).
**Topics**
+ [Creating a KMS key with no key material (console)](#importing-keys-create-cmk-console)
+ [Creating a KMS key with no key material (AWS KMS API)](#importing-keys-create-cmk-api)
## Creating a KMS key with no key material (console)
You only need to create a KMS key for the imported key material once. You can import and reimport the same key material into the existing KMS key as often as you need to, but you cannot import different key material into a KMS key. For details, see [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
To find existing KMS keys with imported key material in your **Customer managed keys** table, use the gear icon in the upper right corner to show the **Origin** column in the list of KMS keys. Imported keys have an **Origin** value of **External (Import Key material)**.
To create a KMS key with imported key material, begin by following the [instructions for creating a KMS key of your preferred key type](create-keys.md), with the following exception.
After choosing the key usage, do the following:
1. Expand **Advanced options**.
1. For **Key material origin**, choose **External (Import key material)**.
1. Choose the check box next to **I understand the security and durability implications of using an imported key** to indicate that you understand the implications of using imported key material. To read about these implications, see [Protecting imported key material](import-keys-protect.md).
1. Optional: To create a [multi-Region KMS key](multi-region-keys-overview.md) with imported key material, under **Regionality** select **Multi-Region key**.
1. Return to the basic instructions. The remaining steps of the basic procedure are the same for all KMS keys of that type.
When you choose **Finish**, you have created a KMS key with no key material and a status ([key state](key-state.md)) of **Pending import**.
However. instead of returning to the **Customer managed keys** table, the console displays a page where you can download the public key and import token that you need to import your key material. You can continue with the download step now, or choose **Cancel** to stop at this point. You can return to this download step at any time.
Next: [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
## Creating a KMS key with no key material (AWS KMS API)
To use the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) to create a symmetric encryption KMS key with no key material, send a [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) request with the `Origin` parameter set to `EXTERNAL`. The following example shows how to do this with the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/).
```
$ aws kms create-key --origin EXTERNAL
```
When the command is successful, you see output similar to the following. The AWS KMS key's `Origin` is `EXTERNAL` and its `KeyState` is `PendingImport`.
**Tip**
If the command does not succeed, you might see a `KMSInvalidStateException` or a `NotFoundException`. You can retry the request.
```
{
"KeyMetadata": {
"Origin": "EXTERNAL",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Description": "",
"Enabled": false,
"MultiRegion": false,
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "PendingImport",
"CreationDate": 1568289600.0,
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
Copy the `KeyId` value from your command output to use in later steps, and then proceed to [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
**Note**
This command creates a symmetric encryption KMS key with a `KeySpec` of `SYMMETRIC_DEFAULT` and `KeyUsage` of `ENCRYPT_DECRYPT`. You can use the optional parameters `--key-spec` and `--key-usage` to create an asymmetric or HMAC KMS key. For more information, see the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
# Step 2: Download the wrapping public key and import token
After you [create a AWS KMS key with no key material](importing-keys-create-cmk.md), download a wrapping public key and an import token for that KMS key by using the AWS KMS console or the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) API. The wrapping public key and import token are an indivisible set that must be used together.
You will use the wrapping public key to [encrypt your key material](importing-keys-encrypt-key-material.md) for transport. Before downloading an RSA wrapping key pair, you select the length (key spec) of the RSA wrapping key pair and the wrapping algorithm that you will use to encrypt your imported key material for transport in [step 3](importing-keys-encrypt-key-material.md). AWS KMS also supports the SM2 wrapping key spec (China Regions only).
Each wrapping public key and import token set is valid for 24 hours. If you don't use them to import key material within 24 hours of downloading them, you must download a new set. You can download new wrapping public key and import token sets at any time. This lets you change your RSA wrapping key length ("key spec") or replace a lost set.
You can also download a wrapping public key and import token set to [reimport the same key material](importing-keys-import-key-material.md#reimport-key-material) into a KMS key. You might do this to set or change the expiration time for the key material, or to restore expired or deleted key material. You must download and re-encrypt your key material every time you import it to AWS KMS.
**Use of the wrapping public key**
The download includes a public key that is unique to your AWS account, also called a *wrapping public key*.
Before you import key material, you encrypt the key material with the public wrapping key, and then upload the encrypted key material to AWS KMS. When AWS KMS receives your encrypted key material, it decrypts the key material with the corresponding private key, then reencrypts the key material under an AES symmetric key, all within an AWS KMS hardware security module (HSM).
**Use of the import token**
The download includes an import token with metadata that ensures that your key material is imported correctly. When you upload your encrypted key material to AWS KMS, you must upload the same import token that you downloaded in this step.
## Select a wrapping public key spec
To protect your key material during import, you encrypt it using wrapping public key that you download from AWS KMS, and a supported [wrapping algorithm](#select-wrapping-algorithm). You select a key spec before you download your wrapping public key and import token. All wrapping key pairs are generated in AWS KMS hardware security modules (HSMs). The private key never leaves the HSM in plain text.
**RSA wrapping key specs**
The *key spec* of the wrapping public key determines the length of the keys in the RSA key pair that protects your key material during its transport to AWS KMS. In general, we recommend using the longest wrapping public key that is practical. We offer several wrapping public key specs to support a variety of HSMs and key managers.
AWS KMS supports the following key specs for the RSA wrapping keys used to import key material of all types, except as noted.
+ RSA\$14096 (recommended)
+ RSA\$13072
+ RSA\$12048
**Note**
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
**SM2 wrapping key spec (China Regions only)**
AWS KMS supports the following key spec for the SM2 wrapping keys used to import asymmetric key material.
+ SM2
## Select a wrapping algorithm
To protect your key material during import, you encrypt it using the downloaded wrapping public key and a supported wrapping algorithm.
AWS KMS supports several standard RSA wrapping algorithms and a two-step hybrid wrapping algorithm. In general, we recommend using the most secure wrapping algorithm that is compatible with your imported key material and [wrapping key spec](#select-wrapping-key-spec). Typically, you choose an algorithm that is supported by the hardware security module (HSM) or key management system that protects your key material.
The following table shows the wrapping algorithms that are supported for each type of key material and KMS key. The algorithms are listed in preference order.
| Key material | Supported wrapping algorithm and spec |
| --- | --- |
| Symmetric encryption key 256-bit AES key 128-bit SM4 key (China Regions only) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric RSA private key | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric elliptic curve (ECC) private key You cannot use the RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithms with the RSA\$12048 wrapping key spec to wrap ECC\$1NIST\$1P521 key material. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric SM2 private key (China Regions only) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| HMAC key | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
**Note**
The `RSA_AES_KEY_WRAP_SHA_256` and `RSA_AES_KEY_WRAP_SHA_1` wrapping algorithms are not supported in China Regions.
+ `RSA_AES_KEY_WRAP_SHA_256` – A two-step hybrid wrapping algorithm that combines encrypting your key material with an AES symmetric key that you generate, and then encrypting the AES symmetric key with the downloaded RSA public wrapping key and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm.
An `RSA_AES_KEY_WRAP_SHA_*` wrapping algorithm is required for wrapping RSA private key material, except in China Regions, where you must use the `SM2PKE` wrapping algorithm.
+ `RSA_AES_KEY_WRAP_SHA_1` – A two-step hybrid wrapping algorithm that combines encrypting your key material with an AES symmetric key that you generate, and then encrypting the AES symmetric key with the downloaded RSA wrapping public key and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm.
An `RSA_AES_KEY_WRAP_SHA_*` wrapping algorithm is required for wrapping RSA private key material, except in China Regions, where you must use the `SM2PKE` wrapping algorithm.
+ `RSAES_OAEP_SHA_256` – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-256 hash function.
+ `RSAES_OAEP_SHA_1` – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-1 hash function.
+ `RSAES_PKCS1_V1_5` (Deprecated; as of October 10, 2023, AWS KMS does not support the RSAES\$1PKCS1\$1V1\$15 wrapping algorithm) – The RSA encryption algorithm with the padding format defined in PKCS \$11 Version 1.5.
+ `SM2PKE` (China Regions only) – An elliptic curve based encryption algorithm defined by OSCCA in GM/T 0003.4-2012.
**Topics**
+ [Select a wrapping public key spec](#select-wrapping-key-spec)
+ [Select a wrapping algorithm](#select-wrapping-algorithm)
+ [Downloading the wrapping public key and import token (console)](#importing-keys-get-public-key-and-token-console)
+ [Downloading the wrapping public key and import token (AWS KMS API)](#importing-keys-get-public-key-and-token-api)
## Downloading the wrapping public key and import token (console)
You can use the AWS KMS console to download the wrapping public key and import token.
1. If you just completed the steps to [create a KMS key with no key material](importing-keys-create-cmk.md#importing-keys-create-cmk-console) and you are on the **Download wrapping key and import token** page, skip to [Step 10](#id-wrap-step).
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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
**Tip**
You can import key material only into an KMS key with an **Origin** of **External (Import key material)**. This indicates that the KMS key was created with no key material. To add the **Origin** column to your table, in the upper-right corner of the page, choose the settings icon (![\[Gear or cog icon representing settings or configuration options.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-icon-settings-new.png)). Turn on **Origin**, and then choose **Confirm**.
1. Choose the alias or key ID of the KMS key that is pending import.
1. Choose the **Cryptographic configuration** tab and view its values. The tabs are below the **General configuration** section.
You can only import key material into KMS keys 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](importing-keys.md).
1. Choose the appropriate tab based on your key type.
+ For asymmetric and HMAC keys, choose the **Key material** tab.
+ For symmetric encryption keys, choose the **Key material and rotations** tab.
1. Choose the import action.
+ For asymmetric and HMAC keys, choose **Import key material**.
+ For symmetric encryption keys, choose one of the following:
+ **Import initial key material** (if no key material has been imported yet)
+ **Import new key material** (to add new material for rotation)
+ **Reimport key material** (available from the **Actions** menu in the key materials table)
**Note**
For multi-Region keys, you must first import the new key material into the primary Region key. Then, import the same key material into each replica Region key.
For primary multi-Region keys, the **Key materials** table includes a **Replica import state** column that displays the import status across all replica regions (for example, "0 of 3 imported"). Choose the replica import state value to open a modal that shows the import status for each replica region. The modal provides **Import key material** links for replica regions where the new key material has not been imported.
1. For **Select wrapping key spec**, choose the configuration for your KMS key. After you create this key, you can't change the key spec.
1. For **Select wrapping algorithm**, choose the option that you will use to encrypt your key material. For more information about the options, see [Select a Wrapping Algorithm](#select-wrapping-algorithm).
1. Choose **Download wrapping public key and import token**, and then save the file.
If you have a **Next** option, to continue the process now, choose **Next**. To continue later, choose **Cancel**.
1. Decompress the `.zip` file that you saved in the previous step (`Import_Parameters__`).
The folder contains the following files:
+ A wrapping public key in a file named `WrappingPublicKey.bin`.
+ An import token in a file named `ImportToken.bin`.
+ A text file named README.txt. This file contains information about the wrapping public key, the wrapping algorithm to use to encrypt your key material, and the date and time when the wrapping public key and import token expire.
1. To continue the process, see [encrypt your key material](importing-keys-encrypt-key-material.md).
## Downloading the wrapping public key and import token (AWS KMS API)
To download the public key and import token, use the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) API. Specify the KMS key that will be associated with the imported key material. This KMS key must have an [Origin](create-keys.md#key-origin) value of `EXTERNAL`.
**Note**
You can't import key material for ML-DSA KMS keys.
This example specifies the `RSA_AES_KEY_WRAP_SHA_256` wrapping algorithm, the RSA\$13072 wrapping public key spec, and an example key ID. Replace these example values with valid values for your download. For the key ID, you can use a [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN), but you cannot use an [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) in this operation.
```
$ aws kms get-parameters-for-import \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-algorithm RSA_AES_KEY_WRAP_SHA_256 \
--wrapping-key-spec RSA_3072
```
When the command is successful, you see output similar to the following:
```
{
"ParametersValidTo": 1568290320.0,
"PublicKey": "public key (base64 encoded)",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"ImportToken": "import token (base64 encoded)"
}
```
To prepare the data for the next step, base64 decode the public key and import token and save the decoded values in files.
To base64 decode the public key and import token:
1. Copy the base64 encoded public key (represented by *public key (base64 encoded)* in the example output), paste it into a new file, and then save the file. Give the file a descriptive name, such as `PublicKey.b64`.
1. Use [OpenSSL](https://openssl.org/) to base64 decode the file's contents and save the decoded data to a new file. The following example decodes the data in the file that you saved in the previous step (`PublicKey.b64`) and saves the output to a new file named `WrappingPublicKey.bin`.
```
$ openssl enc -d -base64 -A -in PublicKey.b64 -out WrappingPublicKey.bin
```
1. Copy the base64 encoded import token (represented by *import token (base64 encoded)* in the example output), paste it into a new file, and then save the file. Give the file a descriptive name, for example `importtoken.b64`.
1. Use [OpenSSL](https://openssl.org/) to base64 decode the file's contents and save the decoded data to a new file. The following example decodes the data in the file that you saved in the previous step (`ImportToken.b64`) and saves the output to a new file named `ImportToken.bin`.
```
$ openssl enc -d -base64 -A -in importtoken.b64 -out ImportToken.bin
```
Proceed to [Step 3: Encrypt the key material](importing-keys-encrypt-key-material.md).
# Step 3: Encrypt the key material
After you [download the public key and import token](importing-keys-get-public-key-and-token.md), encrypt your key material using the public key that you downloaded and the wrapping algorithm that you specified. If you need to replace the public key or import token, or change the wrapping algorithm, you must download a new public key and import token. For information about the public keys and wrapping algorithms that AWS KMS supports, see [Select a wrapping public key spec](importing-keys-get-public-key-and-token.md#select-wrapping-key-spec) and [Select a wrapping algorithm](importing-keys-get-public-key-and-token.md#select-wrapping-algorithm).
The key material must be in binary format. For detailed information, see [Requirements for imported key material](importing-keys-conceptual.md#importing-keys-material-requirements).
**Note**
For asymmetric key pairs, encrypt and import only the private key. AWS KMS derives the public key from the private key.
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 and RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithms are not supported in China Regions.
Typically, you encrypt your key material when you export it from your hardware security module (HSM) or key management system. For information about how to export key material in binary format, see the documentation for your HSM or key management system. You can also refer to the following section that provides a proof of concept demonstration using OpenSSL.
When you encrypt your key material, use the same wrapping algorithm that you specified when you [downloaded the public key and import token](importing-keys-get-public-key-and-token.md). To find the wrapping algorithm that you specified, see the CloudTrail log event for the associated [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) request.
## Generate key material for testing
The following OpenSSL commands generate key material of each supported type for testing. These examples are provided only for testing and proof-of-concept demonstrations. For production systems, use a more secure method to generate your key material, such as a hardware security module or key management system.
To convert the private keys of asymmetric key pairs into DER-encoded format, pipe the key material generation command to the following `openssl pkcs8` command. The `topk8` parameter directs OpenSSL to take a private key as input and return a PKCS\$18 formatted key. (The default behavior is the opposite.)
```
openssl pkcs8 -topk8 -outform der -nocrypt
```
The following commands generate test key material for each of the supported key types.
+ Symmetric encryption key (32 bytes)
This command generates a 256-bit symmetric key (32-byte random string) and saves it in the `PlaintextKeyMaterial.bin` file. You do not need to encode this key material.
```
openssl rand -out PlaintextKeyMaterial.bin 32
```
In China Regions only, you must generate a 128-bit symmetric key (16-byte random string).
```
openssl rand -out PlaintextKeyMaterial.bin 16
```
+ HMAC keys
This command generates a random byte string of the specified size. You do not need to encode this key material.
The length of your HMAC key must match the length defined by the key spec of the KMS key. For example, if the KMS key is HMAC\$1384, you must import a 384-bit (48-byte) key.
```
openssl rand -out HMAC_224_PlaintextKey.bin 28
openssl rand -out HMAC_256_PlaintextKey.bin 32
openssl rand -out HMAC_384_PlaintextKey.bin 48
openssl rand -out HMAC_512_PlaintextKey.bin 64
```
+ RSA private keys
```
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:2048 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_2048_PrivateKey.der
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:3072 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_3072_PrivateKey.der
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:4096 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_4096_PrivateKey.der
```
+ ECC private keys
```
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P256_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-384 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P384_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-521 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P521_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:secp256k1 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_SECG_P256K1_PrivateKey.der
```
+ SM2 private keys (China Regions only)
```
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:sm2 | openssl pkcs8 -topk8 -outform der -nocrypt > SM2_PrivateKey.der
```
## Examples of encrypting key material with OpenSSL
The following examples show how to use [OpenSSL](https://openssl.org/) to encrypt your key material with the public key that you downloaded. To encrypt your key material using an SM2 public key (China Regions only), use the [`SM2OfflineOperationHelper` class](offline-operations.md#key-spec-sm-offline-helper). For more information on the key material types that each wrapping algorithm supports, see [Select a wrapping algorithm](importing-keys-get-public-key-and-token.md#select-wrapping-algorithm).
**Important**
These examples are a proof of concept demonstration only. For production systems, use a more secure method (such as a commercial HSM or key management system) to generate and store your key material.
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
------
#### [ RSAES\$1OAEP\$1SHA\$11 ]
AWS KMS supports the RSAES\$1OAEP\$1SHA\$11 for symmetric encryption keys (SYMMETRIC\$1DEFAULT), elliptic curve (ECC) private keys, SM2 private keys, and HMAC keys.
RSAES\$1OAEP\$1SHA\$11 is not supported for RSA private keys. Also, you cannot use an RSA\$12048 public wrapping key with any RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm to wrap an ECC\$1NIST\$1P521 (secp521r1) private key. You must use a larger public wrapping key or an RSA\$1AES\$1KEY\$1WRAP wrapping algorithm.
The following example encrypts your key material with the [public key that you downloaded](importing-keys-get-public-key-and-token.md) and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm, and saves it in the `EncryptedKeyMaterial.bin` file.
In this example:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded wrapping public key.
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are encrypting, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin` or `ECC_NIST_P521_PrivateKey.der`.
```
$ openssl pkeyutl \
-encrypt \
-in PlaintextKeyMaterial.bin \
-out EncryptedKeyMaterial.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha1
```
------
#### [ RSAES\$1OAEP\$1SHA\$1256 ]
AWS KMS supports the RSAES\$1OAEP\$1SHA\$1256 for symmetric encryption keys (SYMMETRIC\$1DEFAULT), elliptic curve (ECC) private keys, SM2 private keys, and HMAC keys.
RSAES\$1OAEP\$1SHA\$1256 is not supported for RSA private keys. Also, you cannot use an RSA\$12048 public wrapping key with any RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm to wrap an ECC\$1NIST\$1P521 (secp521r1) private key. You must use a larger public key or an RSA\$1AES\$1KEY\$1WRAP wrapping algorithm.
The following example encrypts key material with the [public key that you downloaded](importing-keys-get-public-key-and-token.md) and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm, and saves it in the `EncryptedKeyMaterial.bin` file.
In this example:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`).
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are encrypting, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, or `ECC_NIST_P521_PrivateKey.der`.
```
$ openssl pkeyutl \
-encrypt \
-in PlaintextKeyMaterial.bin \
-out EncryptedKeyMaterial.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha256 \
-pkeyopt rsa_mgf1_md:sha256
```
------
#### [ RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 ]
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithm involves two encryption operations.
1. Encrypt your key material with an AES symmetric key that you generate and an AES symmetric encryption algorithm.
1. Encrypt the AES symmetric key that you used with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithm requires OpenSSL version 3.*x* or later.
1.
**Generate a 256-bit AES symmetric encryption key**
This command generates an AES symmetric encryption key consisting of 256 random bits, and saves it in the `aes-key.bin` file
```
# Generate a 32-byte AES symmetric encryption key
$ openssl rand -out aes-key.bin 32
```
1.
**Encrypt your key material with the AES symmetric encryption key**
This command encrypts your key material with the AES symmetric encryption key and saves the encrypted key material in the `key-material-wrapped.bin` file.
In this example command:
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are importing, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, `RSA_3072_PrivateKey.der`, or `ECC_NIST_P521_PrivateKey.der`.
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the previous command.
```
# Encrypt your key material with the AES symmetric encryption key
$ openssl enc -id-aes256-wrap-pad \
-K "$(xxd -p < aes-key.bin | tr -d '\n')" \
-iv A65959A6 \
-in PlaintextKeyMaterial.bin \
-out key-material-wrapped.bin
```
1.
**Encrypt your AES symmetric encryption key with the public key**
This command encrypts your AES symmetric encryption key with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm, DER-encodes it, and save it in the `aes-key-wrapped.bin` file.
In this example command:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the first command in this example sequence.
```
# Encrypt your AES symmetric encryption key with the downloaded public key
$ openssl pkeyutl \
-encrypt \
-in aes-key.bin \
-out aes-key-wrapped.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha1 \
-pkeyopt rsa_mgf1_md:sha1
```
1.
**Generate the file to import**
Concatenate the file with the encrypted key material and the file with the encrypted AES key. Save them in the `EncryptedKeyMaterial.bin` file, which is the file that you'll import in the [Step 4: Import the key material](importing-keys-import-key-material.md).
In this example command:
+ *`key-material-wrapped.bin`* is the file that contains your encrypted key material.
+ *`aes-key-wrapped.bin`* is the file that contains the encrypted AES encryption key.
```
# Combine the encrypted AES key and encrypted key material in a file
$ cat aes-key-wrapped.bin key-material-wrapped.bin > EncryptedKeyMaterial.bin
```
------
#### [ RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 ]
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 wrapping algorithm involves two encryption operations.
1. Encrypt your key material with an AES symmetric key that you generate and an AES symmetric encryption algorithm.
1. Encrypt the AES symmetric key that you used with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 wrapping algorithm requires OpenSSL version 3.*x* or later.
1.
**Generate a 256-bit AES symmetric encryption key**
This command generates an AES symmetric encryption key consisting of 256 random bits, and saves it in the `aes-key.bin` file
```
# Generate a 32-byte AES symmetric encryption key
$ openssl rand -out aes-key.bin 32
```
1.
**Encrypt your key material with the AES symmetric encryption key**
This command encrypts your key material with the AES symmetric encryption key and saves the encrypted key material in the `key-material-wrapped.bin` file.
In this example command:
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are importing, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, `RSA_3072_PrivateKey.der`, or `ECC_NIST_P521_PrivateKey.der`.
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the previous command.
```
# Encrypt your key material with the AES symmetric encryption key
$ openssl enc -id-aes256-wrap-pad \
-K "$(xxd -p < aes-key.bin | tr -d '\n')" \
-iv A65959A6 \
-in PlaintextKeyMaterial.bin \
-out key-material-wrapped.bin
```
1.
**Encrypt your AES symmetric encryption key with the public key**
This command encrypts your AES symmetric encryption key with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm, DER-encodes it, and save it in the `aes-key-wrapped.bin` file.
In this example command:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the first command in this example sequence.
```
# Encrypt your AES symmetric encryption key with the downloaded public key
$ openssl pkeyutl \
-encrypt \
-in aes-key.bin \
-out aes-key-wrapped.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha256 \
-pkeyopt rsa_mgf1_md:sha256
```
1.
**Generate the file to import**
Concatenate the file with the encrypted key material and the file with the encrypted AES key. Save them in the `EncryptedKeyMaterial.bin` file, which is the file that you'll import in the [Step 4: Import the key material](importing-keys-import-key-material.md).
In this example command:
+ *`key-material-wrapped.bin`* is the file that contains your encrypted key material.
+ *`aes-key-wrapped.bin`* is the file that contains the encrypted AES encryption key.
```
# Combine the encrypted AES key and encrypted key material in a file
$ cat aes-key-wrapped.bin key-material-wrapped.bin > EncryptedKeyMaterial.bin
```
------
Proceed to [Step 4: Import the key material](importing-keys-import-key-material.md).
# Step 4: Import the key material
After you [encrypt your key material](importing-keys-encrypt-key-material.md), 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](importing-keys-encrypt-key-material.md) and the import token that you downloaded at [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md). You must import key material into the same KMS key that you specified when you [downloaded the public key and import token](importing-keys-get-public-key-and-token.md). When key material is successfully imported, the [key state](key-state.md) 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](#importing-keys-expiration) for the key material. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. 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 [reimport](#reimport-key-material) the same key material.
For all KMS keys with `EXTERNAL` origin, the first key material imported into it becomes current and permanently associated with it. Symmetric encryption keys with `EXTERNAL` origin support on-demand rotation. You can associate multiple key materials with imported keys that support on-demand rotation. The process for importing new key material differs for single-Region and multi-Region keys as described in the section [Import new key material](#import-new-key-material). You must set the `importType` parameter to `NEW_KEY_MATERIAL` with the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) action to associate new key material with a KMS key. The default value of the optional `ImportType` parameter is `EXISTING_KEY_MATERIAL`. When you omit the `ImportType` parameter or specify it as `EXISTING_KEY_MATERIAL`, you must import a key material that is previously associated with the KMS key.
For asymmetric, or HMAC KMS keys with `EXTERNAL` origin, only one key material can ever be associated with the key. AWS KMS will reject [ ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) API requests with the `ImportType` parameter.
When all key materials permanently associated with a KMS key are imported, the KMS key is available for use in cryptographic operations. If any one of these key materials is deleted or allowed to expire, the KMS key state changes to `PendingImport` and the key is unusable for cryptographic operations.
To import key material, you can use the [AWS KMS console](#importing-keys-import-key-material-console) or the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) API. You can use the API directly by making HTTP requests, or by using an [AWS SDKs](https://aws.amazon.com/tools/#sdk), [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/) or [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/).
When you import the key material, an [ImportKeyMaterial entry](ct-importkeymaterial.md) 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](key-state.md#key-state-table) 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](#reimport-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](imported-key-material-expiration-alarm.md) 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](ct-importkeymaterial.md) and [delete imported key material](ct-deleteimportedkeymaterial.md), and the AWS KMS operation to [delete expired key material](ct-deleteexpiredkeymaterial.md).
AWS KMS cannot restore, recover, or reproduce the deleted key material. Instead of setting an expiration time, you can programmatically [delete](importing-keys-delete-key-material.md) and [reimport](#reimport-key-material) 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. However you can turn expiration on and off, or set a new expiration time by reimporting the key material. Use the `ExpirationModel` parameter of [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) 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.
## Set key material description
Symmetric encryption keys with `EXTERNAL` origin can have multiple key materials associated with them. You can specify an optional key material description when importing key material into such keys. The description can be used to keep track of where the corresponding key material is durably maintained outside AWS KMS.
For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
## Import new key material
To perform on-demand rotation on a symmetric encryption KMS key with imported key material, you'll first need to import new key material, not previously associated with the key.
+ **Single Region keys**
+ Use the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to `NEW_KEY_MATERIAL` to accomplish this task. This key material is not permanently associated with the key until you perform the [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html) operation or rotate the key in the AWS Management Console. Until then, this key material is in `PENDING_ROTATION` state. A KMS key can have at most one key material in `PENDING_ROTATION` state at any time. A key material in `PENDING_ROTATION` state can be deleted without impacting the key's usability in cryptographic operations.
+ **Multi-Region keys**
+ To import key material into a multi-Region key, you must first import the new key material to the primary Region key. You cannot directly import new key materials to replica Region keys. After importing new key material to the primary Region key, you can import the same key materials into the replica Region keys.
+ Use the [https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to **NEW\$1KEY\$1MATERIAL** for the primary Region key to accomplish this task. For the replica Region key, use the **EXISTING\$1KEY\$1MATERIAL** parameter for `ImportType` for the `ImportKeyMaterial` operation.
+ The key material for symmetric-encryption multi-Region keys must be imported into all the replica Region keys and primary Region keys before the key material state changes to `PENDING_ROTATION` state. Until then, the state of the new key material is `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`. A KMS key can have at most one key material in `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`state at any time (see the `KeyMaterialState` description in [RotationsListEntry](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotationsListEntry.html)). A key material in `PENDING_MULTI_REGION_IMPORT_AND_ROTATION` or `PENDING_ROTATION` state is not permanently associated with the key and can be deleted without impacting the key's usability in cryptographic operations.
## 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.
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 procedure to reimport key material is 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](importing-keys-create-cmk.md) of the import procedure.
+ When you reimport key material, you can change the expiration model and expiration date. For symmetric encryption keys, you can also change the key material description.
For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
Each time you import key material to a KMS key, you need to [download and use a new wrapping key and import token](importing-keys-get-public-key-and-token.md) 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 10](#id-key-materials-step).
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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose the key ID or alias of the KMS key for which you downloaded the public key and import token.
1. 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](importing-keys.md).
1. Choose the appropriate tab based on your key type.
+ For asymmetric and HMAC keys, choose the **Key material** tab.
+ For symmetric encryption keys, choose the **Key material and rotations** tab.
1. Choose the import action.
+ For asymmetric and HMAC keys, choose **Import key material**.
+ For symmetric encryption keys, choose one of the following:
+ **Import initial key material** (if no key material has been imported yet)
+ **Import new key material** (to add new material for rotation)
+ **Reimport key material** (available from the **Actions** menu in the key materials table)
**Note**
For Multi-Region keys, you must first import the new key material into the primary Region key. Then, import the same key material into each replica Region key.
For primary multi-Region keys, the **Key materials** table includes a **Replica import state** column that displays the import status across all replica regions (for example, "0 of 3 imported"). Choose the replica import state value to open a modal that shows the import status for each replica region. The modal provides **Import key material** links for replica regions where the new key material has not been imported.
1. If you downloaded the key material, import token, and encrypted the key material, choose **Next**.
**Note**
For Multi-Region keys, you must first import the new key material into the primary Region key. Then you can import the same key material into the replica Region keys.
1. 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.
1. Under **Import token**, choose **Choose file**. Upload the file that contains the import token that you [downloaded](importing-keys-get-public-key-and-token.md#importing-keys-get-public-key-and-token-console).
1. 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.
1. For symmetric encryption keys, you can optionally specify a description for the key material being imported.
1. Choose **Import key material**.
## Import key material (AWS KMS API)
To import key material, use the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation. The following example uses the [AWS CLI](https://aws.amazon.com/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](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN). You cannot use an [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) for this operation.
1. Replace `EncryptedKeyMaterial.bin` with the name of the file that contains the encrypted key material.
1. Replace `ImportToken.bin` with the name of the file that contains the import token.
1. 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
```
1. If you want to import new key material, not previously associated with the KMS key, set the `ImportType` parameter to `NEW_KEY_MATERIAL`. This option can only be used with symmetric encryption keys. For these keys, you can also use the optional `KeyMaterialDescription` parameter to set a description for the imported key material in the following command line example:
```
$ 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 \
--import-type NEW_KEY_MATERIAL \
--key-material-description "Q2 2025 Rotation"
```
1. For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
**Tip**
If the command does not succeed, you might see a `KMSInvalidStateException` or a `NotFoundException`. You can retry the request.