About imported key material Protecting imported key material Permissions for importing key material Requirements for imported key material

Planning to import key material

Imported key material lets you protect your AWS resources under cryptographic keys that you generate. The key material that you import is associated with a particular KMS key. You can reimport the same key material into the same KMS key, but you cannot import different key material into the KMS key and you cannot convert a KMS key designed for imported key material into a KMS key with AWS KMS key material.

Learn more:

About imported key material

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 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 time. When the expiration time arrives, AWS 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.

You cannot 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.

You cannot 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 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 re-import 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 details, see Importing key material into multi-Region keys.

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.

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.

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 or Amazon S3 client-side encryption, 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 to encrypt your message under a key that is independent of AWS KMS.

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.

Protecting imported key material

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-2 Cryptographic Module Validation Program. 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 that you set on the KMS key. In addition, you can use aliases and tags to identify and control access to the KMS key. You can enable and disable the key, view and edit its properties, and monitor 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 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 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, although you can rotate it.
When you manually delete imported key material, AWS 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 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. 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.

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 (IAM policy)

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


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

kms:GetParametersForImport (Key policy or IAM policy)
- To limit this permission to requests that use a particular wrapping algorithm and wrapping key spec, use the kms:WrappingAlgorithm and kms:WrappingKeySpec policy conditions.
kms:ImportKeyMaterial (Key policy or IAM policy)
- To allow or prohibit key material that expires and control the expiration date, use the kms:ExpirationModel and kms:ValidTo policy conditions.

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

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

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


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

Requirements for imported key material

The key material that you import must be compatible with the 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. In China Regions, imported key material is supported only for the SYMMETRIC_DEFAULT key spec.

KMS key key spec	Key material requirements
Symmetric encryption keys SYMMETRIC_DEFAULT	256-bits (32 bytes) of binary data In China Regions, it must be a 128-bits (16 bytes) of binary data.
HMAC keys HMAC_224 HMAC_256 HMAC_384 HMAC_512	HMAC key material must conform to RFC 2104. The key length must match the length specified by the key spec.
RSA asymmetric private key RSA_2048 RSA_3072 RSA_4096	The RSA asymmetric private key that you import must be part of a key pair that conforms to RFC 3447. 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-encoding in Public-Key Cryptography Standards (PKCS) #8 format that complies with RFC 5208.
Elliptic curve asymmetric private key ECC_NIST_P256 (secp256r1) ECC_NIST_P384 (secp384r1) ECC_NIST_P521 (secp521r1) ECC_SECG_P256K1 (secp256k1)	The ECC asymmetric private key that you import must be part of a key pair that conforms to RFC 5915. Curve: NIST P-256, NIST P-384, NIST P-521, or Secp256k1 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-encoding in Public-Key Cryptography Standards (PKCS) #8 format that complies with RFC 5208.

KMS key key spec

Key material requirements

Symmetric encryption keys

SYMMETRIC_DEFAULT

256-bits (32 bytes) of binary data

In China Regions, it must be a 128-bits (16 bytes) of binary data.

HMAC keys

HMAC_224

HMAC_256

HMAC_384

HMAC_512

HMAC key material must conform to RFC 2104

The key length must match the length specified by the key spec.

RSA asymmetric private key

RSA_2048

RSA_3072

RSA_4096

The RSA asymmetric private key that you import must be part of a key pair that conforms to RFC 3447

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-encoding in Public-Key Cryptography Standards (PKCS) #8 format that complies with RFC 5208.

Elliptic curve asymmetric private key

ECC_NIST_P256 (secp256r1)

ECC_NIST_P384 (secp384r1)

ECC_NIST_P521 (secp521r1)

ECC_SECG_P256K1 (secp256k1)

The ECC asymmetric private key that you import must be part of a key pair that conforms to RFC 5915.

Curve: NIST P-256, NIST P-384, NIST P-521, or Secp256k1

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-encoding in Public-Key Cryptography Standards (PKCS) #8 format that complies with RFC 5208.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Imported key material

Managing imported key material