Create a KMS key - AWS Key Management Service
Permissions for creating KMS keysChoosing what type of KMS key to create

Create a KMS key

You can create AWS KMS keys in the AWS Management Console, or by using the CreateKey operation or the AWS::KMS::Key AWS CloudFormation resource. During this process, you set the key policy for the KMS key, which you can change at any time. You also select the following values that define the type of KMS key that you create. You cannot change these properties after the KMS key is created.

KMS key type

Key type is a property that determines what type of cryptographic key is created. AWS KMS offers three key types to protect data:

  • Advanced Encryption Standard (AES) symmetric keys

    256-bit keys that are used under the Galois Counter Mode (GCM) mode of AES to provide authenticated encryption/decryption of data under 4KB in size. This is the most common type of key and is used to protect other data encryption keys used in your applications and by AWS services that encrypt your data on your behalf.

  • RSA, elliptic curve, or SM2 (China Regions only) asymmetric keys

    These keys are available in various sizes and support many algorithms. They can be used for encryption and decryption, sign and verify, or derive shared secrets operations depending on the algorithm choice.

  • Symmetric keys for performing hash-based message authentication codes (HMAC) operations

    These keys are 256-bit keys used for sign and verify operations.

    KMS keys cannot be exported from the service in plaintext. They are generated by and can only be used within the hardware security modules (HSMs) used by the service. This is the foundational security property of AWS KMS to ensure that keys are not compromised.

Key usage

Key usage is a property that determines the cryptographic operations the key supports. KMS keys can have a key usage of ENCRYPT_DECRYPT, SIGN_VERIFY, GENERATE_VERIFY_MAC, or KEY_AGREEMENT. Each KMS key can have only one key usage. Using a KMS key for more than one type of operation makes the product of both operations more vulnerable to attack.

Key spec

Key spec is a property that represents the cryptographic configuration of a key. The meaning of the key spec differs with the key type.

For KMS keys, the key spec determines whether the KMS key is symmetric or asymmetric. It also determines the type of its key material, and the algorithms it supports.

The default key spec, SYMMETRIC_DEFAULT, represents a 256-bit symmetric encryption key. For a detailed description of all supported key specs, see Key spec reference.

Key material origin

Key material origin is a KMS key property that identifies the source of the key material in the KMS key. You choose the key material origin when you create the KMS key, and you cannot change it. The source of the key material affects the security, durability, availability, latency, and throughput characteristics of the KMS key.

Each KMS key includes a reference to its key material in its metadata. The key material origin of symmetric encryption KMS keys can vary. You can use key material that AWS KMS generates, key material that is generated in a custom key store, or import your own key material.

By default, each KMS key has unique key material. However, you can create a set of multi-Region keys with the same key material.

KMS keys can have one of the following key material origin values: AWS_KMS, EXTERNAL (imported key material), AWS_CLOUDHSM (KMS key in a AWS CloudHSM key store), or EXTERNAL_KEY_STORE (KMS key in an external key store).

Topics

Permissions for creating KMS keys

To create a KMS key in the console or by using the APIs, you must have the following permission in an IAM policy. Whenever possible, use condition keys to limit the permissions. For example, you can use the kms:KeySpec condition key in an IAM policy to allow principals to create only symmetric encryption keys.

For an example of an IAM policy for principals who create keys, see Allow a user to create KMS keys.

Note

Be cautious when giving principals permission to manage tags and aliases. Changing a tag or alias can allow or deny permission to the customer managed key. For details, see ABAC for AWS KMS.

The kms:PutKeyPolicy permission is not required to create the KMS key. The kms:CreateKey permission includes permission to set the initial key policy. But you must add this permission to the key policy while creating the KMS key to ensure that you can control access to the KMS key. The alternative is using the BypassLockoutSafetyCheck parameter, which is not recommended.

KMS keys belong to the AWS account in which they were created. The IAM user who creates a KMS key is not considered to be the key owner and they don't automatically have permission to use or manage the KMS key that they created. Like any other principal, the key creator needs to get permission through a key policy, IAM policy, or grant. However, principals who have the kms:CreateKey permission can set the initial key policy and give themselves permission to use or manage the key.

Choosing what type of KMS key to create

The type of KMS key that you create depends largely on how you plan to use the KMS key, your security requirements, and your authorization requirements. The key type and key usage of a KMS key determine what cryptographic operations the key can perform. Each KMS key has only one key usage. Using a KMS key for more than one type of operation makes the product of all operations more vulnerable to attack.

To allow principals to create KMS keys only for a particular key usage, use the kms:KeyUsage condition key. You can also use the kms:KeyUsage condition key to allow principals to call API operations for a KMS key based on its key usage. For example, you can allow permission to disable a KMS key only if its key usage is SIGN_VERIFY.

Use the following guidance to determine which type of KMS key you need based on your use case.

Encrypt and decrypt data

Use a symmetric KMS key for most use cases that require encrypting and decrypting data. The symmetric encryption algorithm that AWS KMS uses is fast, efficient, and assures the confidentiality and authenticity of data. It supports authenticated encryption with additional authenticated data (AAD), defined as an encryption context. This type of KMS key requires both the sender and recipient of encrypted data to have valid AWS credentials to call AWS KMS.

If your use case requires encryption outside of AWS by users who cannot call AWS KMS, asymmetric KMS keys are a good choice. You can distribute the public key of the asymmetric KMS key to allow these users to encrypt data. And your applications that need to decrypt that data can use the private key of the asymmetric KMS key within AWS KMS.

Sign messages and verify signatures

To sign messages and verify signatures, you must use an asymmetric KMS key. You can use a KMS key with a key spec that represents an RSA key pair, an elliptic curve (ECC) key pair, or an SM2 key pair (China Regions only). The key spec you choose is determined by the signing algorithm that you want to use. The ECDSA signing algorithms that ECC key pairs support are recommended over the RSA signing algorithms. However, you might need to use a particular key spec and signing algorithm to support users who verify signatures outside of AWS.

Encrypt with asymmetric key pairs

To encrypt data with an asymmetric key pair, you must use an asymmetric KMS key with an RSA key spec or an SM2 key spec (China Regions only). To encrypt data in AWS KMS with the public key of a KMS key pair, use the Encrypt operation. You can also download the public key and share it with the parties that need to encrypt data outside of AWS KMS.

When you download the public key of an asymmetric KMS key, you can use it outside of AWS KMS. But it is no longer subject to the security controls that protect the KMS key in AWS KMS. For example, you cannot use AWS KMS key policies or grants to control use of the public key. Nor can you control whether the key is used only for encryption and decryption using the encryption algorithms that AWS KMS supports. For more details, see Special Considerations for Downloading Public Keys.

To decrypt data that was encrypted with the public key outside of AWS KMS, call the Decrypt operation. The Decrypt operation fails if the data was encrypted under a public key from a KMS key with a key usage of SIGN_VERIFY. It will also fail if it was encrypted by using an algorithm that AWS KMS does not support for the key spec you selected. For more information on key specs and supported algorithms, see Key spec reference.

To avoid these errors, anyone using a public key outside of AWS KMS must store the key configuration. The AWS KMS console and the GetPublicKey response provide the information that you must include when you share the public key.

Derive shared secrets

To derive shared secrets, use a KMS key with NIST-recommended elliptic curve or SM2 (China Regions only) key material. AWS KMS uses the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive (ECDH) to establish a key agreement between two peers by deriving a shared secret from their elliptic curve public-private key pairs. You can use the raw shared secret that the DeriveSharedSecret operation returns to derive a symmetric key that can encrypt and decrypt data that is sent between two parties, or generate and verify HMACs. AWS KMS recommends that you follow NIST recommendations for key derivation when using the raw shared secret to derive a symmetric key.

Generate and verify HMAC codes

To generate and verify hash-based message authentication codes, use an HMAC KMS key. When you create an HMAC key in AWS KMS, AWS KMS creates and protects your key material and ensures that you use the correct MAC algorithms for your key. HMAC codes can also be used as pseudo-random numbers, and in certain scenarios for symmetric signing and tokenizing.

HMAC KMS keys are symmetric keys. When creating an HMAC KMS key in the AWS KMS console, choose the Symmetric key type.

Use with AWS services

To create a KMS key for use with an AWS service that is integrated with AWS KMS, consult the documentation for the service. AWS services that encrypt your data require a symmetric encryption KMS key.

In addition to these considerations, cryptographic operations on KMS keys with different key specs have different prices and different request quotas. For information about AWS KMS pricing, see AWS Key Management Service Pricing. For information about request quotas, see Request quotas.