Key Management Service:Import key material into a symmetric key

How it works

A KMS key consists of a key ID, metadata (such as key status), and key material. When you set the key material origin to External (Import Key Material), KMS creates the key without any key material. You then supply the material in four steps:

1. Create a symmetric key with an external origin. The key starts in Pending Import status.

2. Download a wrapping public key and an import token from KMS.

3. Encrypt your key material locally using the wrapping public key.

4. Upload the encrypted key material and the import token to KMS.

Once imported, the key material is permanently bound to that key. You cannot replace it with different key material, but you can re-import the same key material if it expires or is deleted.

Supported key types

The following key management types support importing symmetric key material.

For more information about key management types, see Key management types and key specifications.

Usage notes

• Use a compliant random number generator to produce the key material.

• Once you import key material into a key, that key is permanently bound to it. You cannot import different key material into the same key.

• You can re-import the same key material multiple times — for example, after it expires or is deleted.

• KMS does not export key material after import. Store your key material securely in a separate, durable location.

Prerequisites

Before you begin, ensure that you have:

• A KMS instance (purchased and enabled). For more information, see Purchase and enable a KMS instance.

A KMS instance is not required to import key material for a default customer master key.

Step 1: Create a symmetric key with an external key material origin

Before importing key material, create a key with the key material origin set to External.

Step 2: Download a wrapping public key and an import token

KMS issues a wrapping public key and an import token as a matched pair. The wrapping public key encrypts your key material locally before it leaves your environment. The import token authorizes the upload operation.

1. Find the target key and click Details in the Actions column. In the Key Material and Version section, click Import Initial Key Material.

2. In the Import Key Material panel, select a Public key type and an Encryption algorithm.

All key management types use RSA_2048 as the wrapping public key type. Select an encryption algorithm based on your key management type:

1. Download the wrapping public key and the import token, and store them securely.

   • Wrapping key format: PEM (default filename: publickey_****.pem`) or DER (default filename: `publickey_****.bin).

   • Import token: Default filename is token_******.txt.

Step 3: Encrypt the key material

Use the wrapping public key from Step 2 and the RSAES_OAEP_SHA_256 algorithm to encrypt your key material before uploading it.

The following example uses OpenSSL.

1. Generate a 32-byte random number as your key material. Skip this step if you already have key material.

   openssl rand -out KeyMaterial.bin 32

2. Encrypt the key material with the wrapping public key.

   - The public key file in this example is in DER format. If you downloaded a PEM file, replace -keyform DER with -keyform PEM. - Replace PublicKey.bin with the actual filename of the public key you downloaded in Step 2.

   openssl pkeyutl -encrypt \
     -in KeyMaterial.bin \
     -inkey PublicKey.bin \
     -keyform DER \
     -pubin \
     -out EncryptedKeyMaterial.bin \
     -pkeyopt rsa_padding_mode:oaep \
     -pkeyopt rsa_oaep_md:sha256 \
     -pkeyopt rsa_mgf1_md:sha256

3. Base64-encode the encrypted key material and save it to a text file.

   openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt

   The file EncryptedKeyMaterial_base64.txt contains the key material ready for import.

Step 4: Import the key material

In the Import Key Material panel, upload the files and set an expiration policy, then click OK.

After a successful import, the key status changes from Pending Import to Enabling.

FAQ

What's next

• Overview of Key Management Service

• Key management types and key specifications

• Import key material into an asymmetric key