Create a KMS key
You can create AWS KMS keys in the AWS Management Console, or by using theCreateKey operation or theAWS::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, orKEY_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, thekey 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, seeKey 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 acustom key store, orimport your own key material.
By default, each KMS key has unique key material. However, you can create a set ofmulti-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), orEXTERNAL_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, usecondition keys to limit the permissions. For example, you can use thekms: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, seeAllow a user to create KMS keys.
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, seeABAC for AWS KMS.
kms:CreateKey is required.
kms:CreateAlias is required to create a KMS key in the console where an alias is required for every new KMS key.
kms:TagResource is required to add tags while creating the KMS key.
iam:CreateServiceLinkedRole is required to create multi-Region primary keys. For details, seeControl access to multi-Region keys.
Thekms:PutKeyPolicy permission is not required to create the KMS key. Thekms: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 theBypassLockoutSafetyCheck 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 thekms: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 touse 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 thekms:KeyUsage condition key. You can also use thekms: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 asymmetric 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 anencryption 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 anasymmetric KMS key. You can use a KMS key with akey spec that represents an RSA key pair, an elliptic curve (ECC) key pair, an ML-DSA 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. Use an ML-DSA key pair when migrating from RSA or ECC keys to post-quantum keys. 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 anasymmetric KMS key with anRSA key spec or anSM2 key spec (China Regions only). To encrypt data in AWS KMS with the public key of a KMS key pair, use theEncrypt operation. You can alsodownload 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, seeSpecial Considerations for Downloading Public Keys.
To decrypt data that was encrypted with the public key outside of AWS KMS, call theDecrypt operation. The
Decryptoperation fails if the data was encrypted under a public key from a KMS key with a key usage ofSIGN_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, seeKey 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 theGetPublicKey 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 withNIST-recommended elliptic curve orSM2 (China Regions only) key material. AWS KMS uses theElliptic 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 followNIST 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
Symmetrickey type.- Use with AWS services
To create a KMS key for use with anAWS service that is integrated with AWS KMS, consult the documentation for the service. AWS services that encrypt your data require asymmetric 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, seeAWS Key Management Service Pricing. For information about request quotas, seeRequest quotas.
