AWS KMS concepts

Learn the basic terms and concepts used in AWS Key Management Service (AWS KMS) and how they work together to help protect your data.

AWS KMS keys

AWS KMS keys (KMS keys) are the primary resource in AWS KMS. You can use a KMS key to encrypt, decrypt, and re-encrypt data. It can also generate data keys that you can use outside of AWS KMS. Typically, you'll use symmetric encryption KMS keys, but you can create and use asymmetric KMS keys for encryption or signing, and create and use HMAC KMS keys to generate and verify HMAC tags.

An AWS KMS key is a logical representation of a cryptographic key. A KMS key contains metadata, such as the key ID, key spec, key usage, creation date, description, and key state. Most importantly, it contains a reference to the key material that is used when you perform cryptographic operations with the KMS key.

You can create a KMS key with cryptographic key material generated in AWS KMS FIPS validated hardware security modules. The key material for symmetric KMS keys and the private keys of asymmetric KMS key never leaves AWS KMS unencrypted. To use or manage your KMS keys, you must use AWS KMS. For information about creating and managing KMS keys, see Managing keys. For information about using KMS keys, see the AWS Key Management Service API Reference.

By default, AWS KMS creates the key material for a KMS key. You cannot extract, export, view, or manage this key material. The only exception is the public key of an asymmetric key pair, which you can export for use outside of AWS. Also, you cannot delete this key material; you must delete the KMS key. However, you can import your own key material into a KMS key, or use a custom key store to create KMS keys that use key material in your AWS CloudHSM cluster, or key material in an external key manager that you own and manage outside of AWS.

AWS KMS also supports multi-Region keys, which let you encrypt data in one AWS Region and decrypt it in a different AWS Region.

For information about creating and managing KMS keys, see Managing keys. For information about using KMS keys, see the AWS Key Management Service API Reference.

Customer keys and AWS keys

The KMS keys that you create are customer managed keys. AWS services that use KMS keys to encrypt your service resources often create keys for you. KMS keys that AWS services create in your AWS account are AWS managed keys. KMS keys that AWS services create in a service account are AWS owned keys.

AWS services that integrate with AWS KMS differ in their support for KMS keys. Some AWS services encrypt your data by default with an AWS owned key or an AWS managed key. Some AWS services support customer managed keys. Other AWS services support all types of KMS keys to allow you the ease of an AWS owned key, the visibility of an AWS managed key, or the control of a customer managed key. For detailed information about the encryption options that an AWS service offers, see the Encryption at Rest topic in the user guide or the developer guide for the service.

Customer managed keys

The KMS keys that you create are customer managed keys. Customer managed keys are KMS keys in your AWS account that you create, own, and manage. You have full control over these KMS keys, including establishing and maintaining their key policies, IAM policies, and grants, enabling and disabling them, rotating their cryptographic material, adding tags, creating aliases that refer to the KMS keys, and scheduling the KMS keys for deletion.

Customer managed keys appear on the Customer managed keys page of the AWS Management Console for AWS KMS. To definitively identify a customer managed key, use the DescribeKey operation. For customer managed keys, the value of the KeyManager field of the DescribeKey response is CUSTOMER.

You can use your customer managed key in cryptographic operations and audit usage in AWS CloudTrail logs. In addition, many AWS services that integrate with AWS KMS let you specify a customer managed key to protect the data stored and managed for you.

Customer managed keys incur a monthly fee and a fee for use in excess of the free tier. They are counted against the AWS KMS quotas for your account. For details, see AWS Key Management Service Pricing and Quotas.

AWS managed keys

AWS managed keys are KMS keys in your account that are created, managed, and used on your behalf by an AWS service integrated with AWS KMS.

Some AWS services let you choose an AWS managed key or a customer managed key to protect your resources in that service. In general, unless you are required to control the encryption key that protects your resources, an AWS managed key is a good choice. You don't have to create or maintain the key or its key policy, and there's never a monthly fee for an AWS managed key.

You have permission to view the AWS managed keys in your account, view their key policies, and audit their use in AWS CloudTrail logs. However, you cannot change any properties of AWS managed keys, rotate them, change their key policies, or schedule them for deletion. And, you cannot use AWS managed keys in cryptographic operations directly; the service that creates them uses them on your behalf.

AWS managed keys appear on the AWS managed keys page of the AWS Management Console for AWS KMS. You can also identify AWS managed keys by their aliases, which have the format aws/service-name, such as aws/redshift. To definitively identify an AWS managed keys, use the DescribeKey operation. For AWS managed keys, the value of the KeyManager field of the DescribeKey response is AWS.

All AWS managed keys are automatically rotated every year. You cannot change this rotation schedule.

There is no monthly fee for AWS managed keys. They can be subject to fees for use in excess of the free tier, but some AWS services cover these costs for you. For details, see the Encryption at Rest topic in the user guide or developer guide for the service. For details, see AWS Key Management Service Pricing.

AWS managed keys do not count against resource quotas on the number of KMS keys in each Region of your account. But when used on behalf of a principal in your account, the KMS keys count against request quotas. For details, see Quotas.

AWS owned keys

AWS owned keys are a collection of KMS keys that an AWS service owns and manages for use in multiple AWS accounts. Although AWS owned keys are not in your AWS account, an AWS service can use an AWS owned key to protect the resources in your account.

Some AWS services let you choose an AWS owned key or a customer managed key. In general, unless you are required to audit or control the encryption key that protects your resources, an AWS owned key is a good choice. AWS owned keys are completely free of charge (no monthly fees or usage fees), they do not count against the AWS KMS quotas for your account, and they're easy to use. You don't need to create or maintain the key or its key policy.

The rotation of AWS owned keys varies across services. For information about the rotation of a particular AWS owned key, see the Encryption at Rest topic in the user guide or developer guide for the service.

Symmetric encryption KMS keys

When you create an AWS KMS key, by default, you get a KMS key for symmetric encryption. This is the basic and most commonly used type of KMS key.

In AWS KMS, a symmetric encryption KMS key represents a 256-bit AES-GCM encryption key, except in China Regions, where it represents a 128-bit SM4 encryption key. Symmetric key material never leaves AWS KMS unencrypted. To use a symmetric encryption KMS key, you must call AWS KMS. Symmetric encryption keys are used in symmetric encryption, where the same key is used for encryption and decryption. Unless your task explicitly requires asymmetric encryption, symmetric encryption KMS keys, which never leave AWS KMS unencrypted, are a good choice.

AWS services that are integrated with AWS KMS use only symmetric encryption KMS keys to encrypt your data. These services do not support encryption with asymmetric KMS keys. For help determining whether a KMS key is symmetric or asymmetric, see Identifying asymmetric KMS keys.

Technically, the key spec for a symmetric key is SYMMETRIC_DEFAULT, the key usage is ENCRYPT_DECRYPT, and the encryption algorithm is SYMMETRIC_DEFAULT. For details, see SYMMETRIC_DEFAULT key spec.

You can use a symmetric encryption KMS key in AWS KMS to encrypt, decrypt, and re-encrypt data, and generate data keys and data key pairs. You can create multi-Region symmetric encryption KMS keys, import your own key material into a symmetric encryption KMS key, and create symmetric encryption KMS keys in custom key stores. For a table comparing the operations that you can perform on KMS keys of different types, see Key type reference.

Asymmetric KMS keys

You can create asymmetric KMS keys in AWS KMS. An asymmetric KMS key represents a mathematically related public key and private key pair. The private key never leaves AWS KMS unencrypted. To use the private key, you must call AWS KMS. You can use the public key within AWS KMS by calling the AWS KMS API operations, or you can download the public key and use it outside of AWS KMS. You can also create multi-Region asymmetric KMS keys.

You can create asymmetric KMS keys that represent RSA key pairs or SM2 key pairs (China Regions only) for public key encryption or signing and verification, or elliptic curve key pairs for signing and verification.

For more information about creating and using asymmetric KMS keys, see Asymmetric keys in AWS KMS.

HMAC KMS keys

An HMAC KMS key represents a symmetric key of varying length that is used to generate and verify hash-based message authentication codes (HMAC). The key material for an HMAC key never leaves AWS KMS unencrypted. To use an HMAC key, call the GenerateMac or VerifyMac API operations.

You can also create multi-Region HMAC KMS keys.

For more information about creating and using HMAC KMS keys, see HMAC keys in AWS KMS.

Data keys

Data keys are symmetric keys you can use to encrypt data, including large amounts of data and other data encryption keys. Unlike symmetric KMS keys, which can't be downloaded, data keys are returned to you for use outside of AWS KMS.

When AWS KMS generates data keys, it returns a plaintext data key for immediate use (optional) and an encrypted copy of the data key that you can safely store with the data. When you are ready to decrypt the data, you first ask AWS KMS to decrypt the encrypted data key.

AWS KMS generates, encrypts, and decrypts data keys. However, AWS KMS does not store, manage, or track your data keys, or perform cryptographic operations with data keys. You must use and manage data keys outside of AWS KMS. For help using the data keys securely, see the AWS Encryption SDK.

Create a data key

To create a data key, call the GenerateDataKey operation. AWS KMS generates the data key. Then it encrypts a copy of the data key under a symmetric encryption KMS key that you specify. The operation returns a plaintext copy of the data key and the copy of the data key encrypted under the KMS key. The following image shows this operation.

AWS KMS also supports the GenerateDataKeyWithoutPlaintext operation, which returns only an encrypted data key. When you need to use the data key, ask AWS KMS to decrypt it.

Encrypt data with a data key

AWS KMS cannot use a data key to encrypt data. But you can use the data key outside of AWS KMS, such as by using OpenSSL or a cryptographic library like the AWS Encryption SDK.

After using the plaintext data key to encrypt data, remove it from memory as soon as possible. You can safely store the encrypted data key with the encrypted data so it is available to decrypt the data.

Decrypt data with a data key

To decrypt your data, pass the encrypted data key to the Decrypt operation. AWS KMS uses your KMS key to decrypt the data key and then returns the plaintext data key. Use the plaintext data key to decrypt your data and then remove the plaintext data key from memory as soon as possible.

The following diagram shows how to use the Decrypt operation to decrypt an encrypted data key.

How unusable KMS keys affect data keys

When a KMS key becomes unusable, the effect is almost immediate (subject to eventual consistency). The key state of the KMS key changes to reflect its new condition, and all requests to use the KMS key in cryptographic operations fail.

However, the effect on data keys encrypted by the KMS key, and on data encrypted by the data key, is delayed until the KMS key is used again, such as to decrypt the data key.

KMS keys can become unusable for a variety of reasons, including the following actions that you might perform.

This effect is particularly important for the many AWS services that use data keys to protect the resources that the service manages. The following example uses Amazon Elastic Block Store (Amazon EBS) and Amazon Elastic Compute Cloud (Amazon EC2). Different AWS services use data keys in different ways. For details, see the Data protection section of the Security chapter for the AWS service.

For example, consider this scenario:

Data key pairs

Data key pairs are asymmetric data keys consisting of a mathematically-related public key and private key. They are designed for use in client-side encryption and decryption or signing and verification outside of AWS KMS.

Unlike the data key pairs that tools like OpenSSL generate, AWS KMS protects the private key in each data key pair under a symmetric encryption KMS key in AWS KMS that you specify. However, AWS KMS does not store, manage, or track your data key pairs, or perform cryptographic operations with data key pairs. You must use and manage data key pairs outside of AWS KMS.

AWS KMS supports the following types of data key pairs:

The type of data key pair that you select usually depends on your use case or regulatory requirements. Most certificates require RSA keys. Elliptic curve keys are often used for digital signatures. ECC_SECG_P256K1 keys are commonly used for cryptocurrencies. AWS KMS recommends that you use ECC key pairs for signing, and use RSA key pairs for either encryption or signing, but not both. However, AWS KMS cannot enforce any restrictions on the use of data key pairs outside of AWS KMS.

Create a data key pair

To create a data key pair, call the GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext operations. Specify the symmetric encryption KMS key you want to use to encrypt the private key.

GenerateDataKeyPair returns a plaintext public key, a plaintext private key, and an encrypted private key. Use this operation when you need a plaintext private key immediately, such as to generate a digital signature.

GenerateDataKeyPairWithoutPlaintext returns a plaintext public key and an encrypted private key, but not a plaintext private key. Use this operation when you don't need a plaintext private key immediately, such as when you're encrypting with a public key. Later, when you need a plaintext private key to decrypt the data, you can call the Decrypt operation.

The following image shows the GenerateDataKeyPair operation. The GenerateDataKeyPairWithoutPlaintext operation omits the plaintext private key.

Encrypt data with a data key pair

When you encrypt with a data key pair, you use the public key of the pair to encrypt the data and the private key of the same pair to decrypt the data. Typically, you use data key pairs when many parties need to encrypt data that only the party with the private key can decrypt.

The parties with the public key use that key to encrypt data, as shown in the following diagram.

Decrypt data with a data key pair

To decrypt your data, use the private key in the data key pair. For the operation to succeed, the public and private keys must be from the same data key pair, and you must use the same encryption algorithm.

To decrypt the encrypted private key, pass it to the Decrypt operation. Use the plaintext private key to decrypt the data. Then remove the plaintext private key from memory as soon as possible.

The following diagram shows how to use the private key in a data key pair to decrypt ciphertext.

Sign messages with a data key pair

To generate a cryptographic signature for a message, use the private key in the data key pair. Anyone with the public key can use it to verify that the message was signed with your private key and that it has not changed since it was signed.

If you encrypt your private key, pass the encrypted private key to the Decrypt operation. AWS KMS uses your KMS key to decrypt the data key and then it returns the plaintext private key. Use the plaintext private key to generate the signature. Then remove the plaintext private key from memory as soon as possible.

To sign a message, create a message digest using a cryptographic hash function, such as the dgst command in OpenSSL. Then, pass your plaintext private key to the signing algorithm. The result is a signature that represents the contents of the message. (You might be able to sign shorter messages without first creating a digest. The maximum message size varies with the signing tool you use.)

The following diagram shows how to use the private key in a data key pair to sign a message.

Verify a signature with a data key pair

Anyone who has the public key in your data key pair can use it to verify the signature that you generated with your private key. Verification confirms that an authorized user signed the message with the specified private key and signing algorithm, and the message hasn't changed since it was signed.

To be successful, the party verifying the signature must generate the same type of digest, use the same algorithm, and use the public key that corresponds to the private key used to sign the message.

The following diagram shows how to use the public key in a data key pair to verify a message signature.

Aliases

Use an alias as a friendly name for a KMS key. For example, you can refer to a KMS key as test-key instead of 1234abcd-12ab-34cd-56ef-1234567890ab.

Aliases make it easier to identify a KMS key in the AWS Management Console. You can use an alias to identify a KMS key in some AWS KMS operations, including cryptographic operations. In applications, you can use a single alias to refer to different KMS keys in each AWS Region.

You can also allow and deny access to KMS keys based on their aliases without editing policies or managing grants. This feature is part of AWS KMS support for attribute-based access control (ABAC). For details, see ABAC for AWS KMS.

In AWS KMS, aliases are independent resources, not properties of a KMS key. As such, you can add, change, and delete an alias without affecting the associated KMS key.

Learn more:

Custom key stores

A custom key store is an AWS KMS resource backed by a key manager outside of AWS KMS that you own and manage. When you use a KMS key in a custom key store for a cryptographic operation, the cryptographic operation is actually performed in your key manager using its cryptographic keys.

AWS KMS supports AWS CloudHSM key stores backed by an AWS CloudHSM cluster and external key stores that are backed by an external key manager outside of AWS.

For more information, see Custom key stores.

Cryptographic operations

In AWS KMS, cryptographic operations are API operations that use KMS keys to protect data. Because KMS keys remain within AWS KMS, you must call AWS KMS to use a KMS key in a cryptographic operation.

To perform cryptographic operations with KMS keys, use the AWS SDKs, AWS Command Line Interface (AWS CLI), or the AWS Tools for PowerShell. You cannot perform cryptographic operations in the AWS KMS console. For examples of calling the cryptographic operations in several programming languages, see Programming the AWS KMS API.

The following table lists the AWS KMS cryptographic operations. It also shows the key type and key usage requirements for KMS keys used in the operation.

[1] Generates an asymmetric data key pair that is protected by a symmetric encryption KMS key.

For information about the permissions for cryptographic operations, see the AWS KMS permissions.

To make AWS KMS responsive and highly functional for all users, AWS KMS establishes quotas on number of cryptographic operations called in each second. For details, see Shared quotas for cryptographic operations.

Key identifiers (KeyId)

Key identifiers act like names for your KMS keys. They help you to recognize your KMS keys in the console. You use them to indicate which KMS keys you want to use in AWS KMS API operations, key policies, IAM policies, and grants. The key identifier values are completely unrelated to the key material associated with the KMS key.

AWS KMS defines several key identifiers. When you create a KMS key, AWS KMS generates a key ARN and key ID, which are properties of the KMS key. When you create an alias, AWS KMS generates an alias ARN based on the alias name that you define. You can view the key and alias identifiers in the AWS Management Console and in the AWS KMS API.

In the AWS KMS console, you can view and filter KMS keys by their key ARN, key ID, or alias name, and sort by key ID and alias name. For help finding the key identifiers in the console, see Finding the key ID and key ARN.

In the AWS KMS API, the parameters you use to identify a KMS key are named KeyId or a variation, such as TargetKeyId or DestinationKeyId. However, the values of those parameters are not limited to key IDs. Some can take any valid key identifier. For information about the values for each parameter, see the parameter description in the AWS Key Management Service API Reference.

AWS KMS supports the following key identifiers.

Key material

Key material is the string of bits used in a cryptographic algorithm. Secret key material must be kept secret to protect the cryptographic operations that use it. Public key material is designed to be shared.

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 the AWS CloudHSM cluster of a custom key store, or import your own key material. If you use AWS KMS key material for your symmetric encryption KMS key, you can enable automatic rotation of your 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.

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.

To find the key material origin of a KMS key, use the DescribeKey operation, or see the Origin value on the Cryptographic configuration tab of the detail page for a KMS key in the AWS KMS console. For help, see Viewing Keys.

KMS keys can have one of the following key material origin values.

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.

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, or GENERATE_VERIFY_MAC. 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.

For help choosing the key usage for your KMS key, see Selecting the key usage. To find the key usage of a KMS key, use the DescribeKey operation, or choose the Cryptographic configuration tab on the detail page for a KMS key in the AWS KMS console. For help, see Viewing Keys.

Envelope encryption

When you encrypt your data, your data is protected, but you have to protect your encryption key. One strategy is to encrypt it. Envelope encryption is the practice of encrypting plaintext data with a data key, and then encrypting the data key under another key.

You can even encrypt the data encryption key under another encryption key, and encrypt that encryption key under another encryption key. But, eventually, one key must remain in plaintext so you can decrypt the keys and your data. This top-level plaintext key encryption key is known as the root key.

AWS KMS helps you to protect your encryption keys by storing and managing them securely. Root keys stored in AWS KMS, known as AWS KMS keys, never leave the AWS KMS FIPS validated hardware security modules unencrypted. To use a KMS key, you must call AWS KMS.

Envelope encryption offers several benefits:

Encryption context

All AWS KMS cryptographic operations with symmetric encryption KMS keys accept an encryption context, an optional set of non-secret key–value pairs that can contain additional contextual information about the data. AWS KMS uses the encryption context as additional authenticated data (AAD) to support authenticated encryption.

When you include an encryption context in an encryption request, it is cryptographically bound to the ciphertext such that the same encryption context is required to decrypt (or decrypt and re-encrypt) the data. If the encryption context provided in the decryption request is not an exact, case-sensitive match, the decrypt request fails. Only the order of the key-value pairs in the encryption context can vary.

The encryption context is not secret and not encrypted. It appears in plaintext in AWS CloudTrail Logs so you can use it to identify and categorize your cryptographic operations. Your encryption context should not include sensitive information. We recommend that your encryption context describe the data being encrypted or decrypted. For example, when you encrypt a file, you might use part of the file path as encryption context.

"encryptionContext": {
    "department": "10103.0"
}    

For example, when encrypting volumes and snapshots created with the Amazon Elastic Block Store (Amazon EBS) CreateSnapshot operation, Amazon EBS uses the volume ID as encryption context value.

"encryptionContext": {
  "aws:ebs:id": "vol-abcde12345abc1234"
}

You can also use the encryption context to refine or limit access to AWS KMS keys in your account. You can use the encryption context as a constraint in grants and as a condition in policy statements.

To learn how to use encryption context to protect the integrity of encrypted data, see the post How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext on the AWS Security Blog.

More about encryption context.

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp"
  },
  "Action": "kms:Decrypt",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:EncryptionContext:AppName": "ExampleApp"
    }
  }
}

$ aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::111122223333:user/exampleUser \
    --retiring-principal arn:aws:iam::111122223333:role/adminRole \
    --operations GenerateDataKey \
    --constraints EncryptionContextEquals={Purpose=Test}

$ aws kms generate-data-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-spec AES_256 \
    --encryption-context Purpose=Test

Key policy

When you create a KMS key, you determine who can use and manage that KMS key. These permissions are contained in a document called the key policy. You can use the key policy to add, remove, or change permissions at any time for a customer managed keys. But you cannot edit the key policy for an AWS managed keys. For more information, see Key policies in AWS KMS.

Grant

A grant is a policy instrument that allows AWS principals to use AWS KMS keys in cryptographic operations. It also can let them view a KMS key (DescribeKey) and create and manage grants. When authorizing access to a KMS key, grants are considered along with key policies and IAM policies. Grants are often used for temporary permissions because you can create one, use its permissions, and delete it without changing your key policies or IAM policies. Because grants can be very specific, and are easy to create and revoke, they are often used to provide temporary permissions or more granular permissions.

For detailed information about grants, including grant terminology, see Grants in AWS KMS.

Auditing KMS key usage

You can use AWS CloudTrail to audit key usage. CloudTrail creates log files that contain a history of AWS API calls and related events for your account. These log files include all AWS KMS API requests made with the AWS Management Console, AWS SDKs, and command line tools. The log files also include requests to AWS KMS that AWS services make on your behalf. You can use these log files to find important information, including when the KMS keys was used, the operation that was requested, the identity of the requester, and the source IP address. For more information, see Logging with AWS CloudTrail and the AWS CloudTrail User Guide.

Key management infrastructure

A common practice in cryptography is to encrypt and decrypt with a publicly available and peer-reviewed algorithm such as AES (Advanced Encryption Standard) and a secret key. One of the main problems with cryptography is that it's very hard to keep a key secret. This is typically the job of a key management infrastructure (KMI). AWS KMS operates the key infrastructure for you. AWS KMS creates and securely stores your root keys, called AWS KMS keys. For more information about how AWS KMS operates, see AWS Key Management Service Cryptographic Details.