Create a KMS key with imported key material - AWS Key Management Service
Permissions for importing key materialRequirements for imported key material

Create a KMS key with imported 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.

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 topic.

  1. Create a KMS key with no key material – 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 compatable with the key spec of the associated AWS KMS key. For more information about compatability, see Requirements for imported key material.

  2. Download the wrapping public key and import token – 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.

  3. Encrypt the key material – Use the wrapping public key that you downloaded in step 2 to encrypt the key material that you created on your own system.

  4. Import the key material – Upload the encrypted key material that you created in step 3 and the import token that you downloaded in step 2.

    At this stage, you can set an optional expiration time. 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, download the wrapping public key and import token, and import the key material. AWS KMS also records an entry when you delete imported key material or when AWS KMS deletes expired key material.

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)

  • kms:ImportKeyMaterial (Key policy or IAM policy)

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

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

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.

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-encoded 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-encoded in Public-Key Cryptography Standards (PKCS) #8 format that complies with RFC 5208.
SM2 asymmetric private key (China Regions only)

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) #8 format that complies with RFC 5208.