Amazon KMS concepts - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Amazon KMS concepts

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

Amazon KMS keys

Amazon KMS keys (KMS keys) are the primary resource in Amazon 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 Amazon 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.

Note

Amazon KMS is replacing the term customer master key (CMK) with Amazon KMS key and KMS key. The concept has not changed. To prevent breaking changes, Amazon KMS is keeping some variations of this term.

An Amazon 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 run cryptographic operations with the KMS key.

You create KMS keys in Amazon KMS. Symmetric KMS keys and the private keys of asymmetric KMS key never leave Amazon KMS unencrypted. To use or manage your KMS keys, you must use Amazon KMS. For information about creating and managing KMS keys, see Managing keys. For information about using KMS keys, see the Amazon Key Management Service API Reference.

By default, Amazon KMS creates the key material for a KMS key. You cannot extract, export, view, or manage this key material. 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 create the key material for a KMS key in the Amazon CloudHSM cluster associated with an Amazon KMS custom key store.

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

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

Customer keys and Amazon keys

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

Type of KMS key Can view KMS key metadata Can manage KMS key Used only for my Amazon Web Services account Automatic rotation
Customer managed key Yes Yes Yes Optional. Every year (approximately 365 days)
Amazon managed key Yes No Yes Required. Every year (approximately 365 days)
Amazon owned key No No No Varies

Amazon services that integrate with Amazon KMS differ in their support for KMS keys. Some Amazon services encrypt your data by default with an Amazon owned key or an Amazon managed key. Some Amazon services support customer managed keys. Other Amazon services support all types of KMS keys to allow you the ease of an Amazon owned key, the visibility of an Amazon managed key, or the control of a customer managed key. For detailed information about the encryption options that an Amazon 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 Amazon Web Services 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 Amazon Web Services Management Console for Amazon 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 Amazon CloudTrail logs. In addition, many Amazon services that integrate with Amazon 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 Amazon KMS quotas for your account. For details, see Amazon Key Management Service Pricing and Quotas.

Amazon managed keys

Amazon managed keys are KMS keys in your account created, managed, and used on your behalf by an Amazon service integrated with Amazon KMS. Some Amazon services support only an Amazon managed key. Others use an Amazon owned key or offer you a choice of KMS keys.

You can view the Amazon managed keys in your account, view their key policies, and audit their use in Amazon CloudTrail logs. However, you cannot manage these KMS keys, rotate them, or change their key policies. And, you cannot use Amazon managed keys in cryptographic operations directly; the service that creates them uses them on your behalf.

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

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

Note

In May 2022, Amazon KMS changed the rotation schedule for Amazon managed keys from every three years (approximately 1,095 days) to every year (approximately 365 days).

New Amazon managed keys are automatically rotated one year after they are created, and approximately every year thereafter.

Existing Amazon managed keys are automatically rotated one year after their most recent rotation, and every year thereafter.

You do not pay a monthly fee for Amazon managed keys. They can be subject to fees for use in excess of the free tier, but some Amazon 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 Amazon Key Management Service Pricing.

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

Amazon owned keys

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

You do not need to create or manage the Amazon owned keys. However, you cannot view, use, track, or audit them. Amazon does not charge you a monthly fee or usage fee for Amazon owned keys and they do not count against the Amazon KMS quotas for your account.

The rotation of Amazon owned keys varies across services. For information about the rotation of a particular Amazon 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 a Amazon 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 Amazon KMS, a symmetric encryption KMS key represents a 256-bit encryption key that never leaves Amazon KMS unencrypted. To use a symmetric encryption KMS key, you must call Amazon 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 Amazon KMS unencrypted, are a good choice.

Amazon services that are integrated with Amazon 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 Amazon 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 Amazon KMS. An asymmetric KMS key represents a mathematically related public key and private key pair. The private key never leaves Amazon KMS unencrypted. To use the private key, you must call Amazon KMS. You can use the public key within Amazon KMS by calling the Amazon KMS API operations, or you can download the public key and use it outside of Amazon KMS. You can also create multi-Region asymmetric KMS keys.

You can create asymmetric KMS keys that represent RSA key pairs 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 Amazon 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 Amazon 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 Amazon 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 Amazon KMS.

When Amazon 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 Amazon KMS to decrypt the encrypted data key.

Amazon KMS generates, encrypts, and decrypts data keys. However, Amazon 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 Amazon KMS. For help using the data keys securely, see the Amazon Encryption SDK.

Create a data key

To create a data key, call the GenerateDataKey operation. Amazon 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.


          Generate a data key

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

Encrypt data with a data key

Amazon KMS cannot use a data key to encrypt data. But you can use the data key outside of Amazon KMS, such as by using OpenSSL or a cryptographic library like the Amazon 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.


          Encrypt user data outside of Amazon KMS

Decrypt data with a data key

To decrypt your data, pass the encrypted data key to the Decrypt operation. Amazon 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.


          Decrypting a data key

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 Amazon KMS.

Unlike the data key pairs that tools like OpenSSL generate, Amazon KMS protects the private key in each data key pair under a symmetric encryption KMS key in Amazon KMS that you specify. However, Amazon 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 Amazon KMS.

Amazon KMS supports the following types of data key pairs:

  • RSA key pairs: RSA_2048, RSA_3072, and RSA_4096

  • Elliptic curve key pairs, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, and ECC_SECG_P256K1

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. Amazon KMS recommends that you use ECC key pairs for signing, and use RSA key pairs for either encryption or signing, but not both. However, Amazon KMS cannot enforce any restrictions on the use of data key pairs outside of Amazon 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 GenerateDataKeyWithoutPlaintext operation omits the plaintext private key.


          Generate a data key pair

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.


          Encrypt user data with the public key of a data key pair outside of Amazon KMS

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.


          Decrypt the data with the private key in a data key pair outside of
            Amazon KMS.

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


          Generate a cryptographic signature with the private key in a data key pair outside
            of Amazon KMS.

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.


          Verify a cryptographic signature with the public key in a data key pair outside of
            Amazon KMS.

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 Amazon Web Services Management Console. You can use an alias to identify a KMS key in some Amazon KMS operations, including cryptographic operations. In applications, you can use a single alias to refer to different KMS keys in each Amazon Web Services 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 Amazon KMS support for attribute-based access control (ABAC). For details, see ABAC for Amazon KMS.

In Amazon 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 Amazon KMS resource associated with FIPS 140-2 Level 3 hardware security modules (HSMs) in a Amazon CloudHSM cluster that you own and manage.

When you create a Amazon KMS key (KMS key) in your custom key store, Amazon KMS generates a 256-bit, persistent, non-exportable Advanced Encryption Standard (AES) symmetric key in the associated Amazon CloudHSM cluster. This key material never leaves the HSMs unencrypted. When you use a KMS key in a custom key store, the cryptographic operations are performed in the HSMs in the cluster.

For more information, see Custom key stores.

Cryptographic operations

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

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

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

Operation Key type Key usage
Decrypt Any ENCRYPT_DECRYPT
Encrypt Any ENCRYPT_DECRYPT
GenerateDataKey Symmetric ENCRYPT_DECRYPT
GenerateDataKeyPair Symmetric [1] ENCRYPT_DECRYPT
GenerateDataKeyPairWithoutPlaintext Symmetric [1] ENCRYPT_DECRYPT
GenerateDataKeyWithoutPlaintext Symmetric ENCRYPT_DECRYPT
GenerateMac HMAC GENERATE_VERIFY_MAC
GenerateRandom N/A. This operation doesn't use a KMS key. N/A
ReEncrypt Any ENCRYPT_DECRYPT
Sign Asymmetric SIGN_VERIFY
Verify Asymmetric SIGN_VERIFY
VerifyMac HMAC GENERATE_VERIFY_MAC

[1] GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext generate an asymmetric data key pair that is protected by a symmetric encryption KMS key.

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

To make Amazon KMS responsive and highly functional for all users, Amazon 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 as 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 Amazon KMS API operations, key policies, IAM policies, and grants.

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

In the Amazon 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 Amazon 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 Amazon Key Management Service API Reference.

Note

When using the Amazon KMS API, be careful about the key identifier that you use. Different APIs require different key identifiers. In general, use the most complete and practical key identifier for your task.

Amazon KMS supports the following key identifiers.

Key ARN

The key ARN is the Amazon Resource Name (ARN) of a KMS key. It is a unique, fully qualified identifier for the KMS key. A key ARN includes the Amazon Web Services account, Region, and the key ID. For help finding the key ARN of a KMS key, see Finding the key ID and key ARN.

The format of a key ARN is as follows:

arn:<partition>:kms:<region>:<account-id>:key/<key-id>

The following is an example key ARN for a single-Region KMS key.

arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

The key-id element of the key ARNs of multi-Region keys begin with the mrk- prefix. The following is an example key ARN for a multi-Region key.

arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
Key ID

The key ID uniquely identifies a KMS key within an account and Region. For help finding the key ID of a KMS key, see Finding the key ID and key ARN.

The following is an example key ID for a single-Region KMS key.

1234abcd-12ab-34cd-56ef-1234567890ab

The key IDs of multi-Region keys begin with the mrk- prefix. The following is an example key ID for a multi-Region key.

mrk-1234abcd12ab34cd56ef1234567890ab
Alias ARN

The alias ARN is the Amazon Resource Name (ARN) of an Amazon KMS alias. It is a unique, fully qualified identifier for the alias, and for the KMS key it represents. An alias ARN includes the Amazon Web Services account, Region, and the alias name.

At any given time, an alias ARN identifies one particular KMS key. However, because you can change the KMS key associated with the alias, the alias ARN can identify different KMS keys at different times. For help finding the alias ARN of a KMS key, see Finding the alias name and alias ARN.

The format of an alias ARN is as follows:

arn:<partition>:kms:<region>:<account-id>:alias/<alias-name>

The following is the alias ARN for a fictitious ExampleAlias.

arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
Alias name

The alias name is a string of up to 256 characters. It uniquely identifies an associated KMS key within an account and Region. In the Amazon KMS API, alias names always begin with alias/. For help finding the alias name of a KMS key, see Finding the alias name and alias ARN.

The format of an alias name is as follows:

alias/<alias-name>

For example:

alias/ExampleAlias

The aws/ prefix for an alias name is reserved for Amazon managed keys. You cannot create an alias with this prefix. For example, the alias name of the Amazon managed key for Amazon Simple Storage Service (Amazon S3) is the following.

alias/aws/s3

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 Amazon KMS generates, key material that is generated in the Amazon CloudHSM cluster of a custom key store, or import your own key material. If you use Amazon 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. 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 Amazon KMS console. For help, see Viewing Keys.

The key origin for asymmetric KMS keys and HMAC KMS keys is always AWS_KMS, which indicates that Amazon KMS generated it.

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

AWS_KMS

Amazon KMS creates and manages the key material for the KMS key in Amazon KMS. This is the default and the recommended value for most KMS keys.

For help creating keys with key material from Amazon KMS, see Creating keys.

EXTERNAL

The KMS key has imported key material. When you create a KMS key with an External key material origin, the KMS key has no key material. Later, you can import key material into the KMS key. When you use imported key material, you need to secure and manage that key material outside of Amazon KMS, including replacing the key material if it expires. For details, see About imported key material.

For help creating a KMS key for imported key material, see Step 1: Create a KMS key with no key material.

AWS_CLOUDHSM

Amazon KMS created the key material for the KMS key in the Amazon CloudHSM cluster associated with your custom key store.

For help creating a KMS key in a custom key store, see Creating KMS keys in a custom key store.

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.

  • Amazon 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 cryptographic algorithms it supports. You choose the key spec when you create the KMS key, and you cannot change it.

    Note

    The KeySpec for an KMS key was known as a CustomerMasterKeySpec. The CustomerMasterKeySpec parameter of the CreateKey operation is deprecated. Instead, use the KeySpec parameter, which works the same way. To prevent breaking changes, the response of the CreateKey and DescribeKey operations now includes both KeySpec and CustomerMasterKeySpec members with the same values.

    For a list of key specs and help with choosing a key spec, see Selecting the key spec. To find the key spec of a KMS key, use the DescribeKey operation, or see the Cryptographic configuration tab on the detail page for a KMS key in the Amazon KMS console. For help, see Viewing Keys.

    To limit the key specs that principals can use when creating KMS keys, use the kms:KeySpec condition key. You can also use the kms:KeySpec condition key to allow principals to call Amazon KMS operations only on KMS keys with a particular key spec. For example, you can deny permission to schedule deletion of any KMS key with an RSA_4096 key spec.

  • Data keys (GenerateDataKey) — The key spec determines the length of an AES data key.

  • Data keys pairs (GenerateDataKeyPair) — The key pair spec determines the type of key material in the data key pair.

Key usage

Key usage is a property that determines whether a KMS key is used for encryption and decryption (ENCRYPT_DECRYPT) -or- signing and verification (SIGN_VERIFY) -or- generate and verify MAC (GENERATE_VERIFY_MAC). Each KMS key can have only one 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 Amazon 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.


        Envelope encryption

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


        Envelope encryption with multiple key encryption keys

Envelope encryption offers several benefits:

  • Protecting data keys

    When you encrypt a data key, you don't have to worry about storing the encrypted data key, because the data key is inherently protected by encryption. You can safely store the encrypted data key alongside the encrypted data.

  • Encrypting the same data under multiple keys

    Encryption operations can be time consuming, particularly when the data being encrypted are large objects. Instead of re-encrypting raw data multiple times with different keys, you can re-encrypt only the data keys that protect the raw data.

  • Combining the strengths of multiple algorithms

    In general, symmetric key algorithms are faster and produce smaller ciphertexts than public key algorithms. But public key algorithms provide inherent separation of roles and easier key management. Envelope encryption lets you combine the strengths of each strategy.

Encryption context

All Amazon KMS cryptographic operations with symmetric encryption KMS keys accept an encryption context, an optional set of key–value pairs that can contain additional contextual information about the data. Amazon 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.

Note

You cannot specify an encryption context in a cryptographic operation with an asymmetric KMS key or an HMAC KMS key. Asymmetric algorithms and MAC algorithms do not support an encryption context.

The encryption context is not secret and not encrypted. It appears in plaintext in Amazon 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 Amazon 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 Amazon Key Management Service and EncryptionContext on the Amazon Security Blog.

More about encryption context.

Amazon KMS enforces the following rules for encryption context keys and values.

  • The key and value in an encryption context pair must be simple literal strings. If you use a different type, such as an integer or float, Amazon KMS interprets it as a string.

  • The keys and values in an encryption context can include Unicode characters. If an encryption context includes characters that are not permitted in key policies or IAM policies, you won't be able to specify the encryption context in policy condition keys, such as kms:EncryptionContext:context-key and kms:EncryptionContextKeys. For details about key policy document rules, see Key policy format. For details about IAM policy document rules, see IAM name requirements in the IAM User Guide.

The encryption context is used primarily to verify integrity and authenticity. But you can also use the encryption context to control access to symmetric encryption Amazon KMS keys in key policies and IAM policies.

The kms:EncryptionContext: and kms:EncryptionContextKeys condition keys allow (or deny) a permission only when the request includes particular encryption context keys or key–value pairs.

For example, the following key policy statement allows the RoleForExampleApp role to use the KMS key in Decrypt operations. It uses the kms:EncryptionContext:context-key condition key to allow this permission only when the encryption context in the request includes an AppName:ExampleApp encryption context pair.

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

For more information about these encryption context condition keys, see Using policy conditions with Amazon KMS.

When you create a grant, you can include grant constraints that establish conditions for the grant permissions. Amazon KMS supports two grant constraints, EncryptionContextEquals and EncryptionContextSubset, both of which involve the encryption context in a request for a cryptographic operation. When you use these grant constraints, the permissions in the grant are effective only when the encryption context in the request for the cryptographic operation satisfies the requirements of the grant constraints.

For example, you can add an EncryptionContextEquals grant constraint to a grant that allows the GenerateDataKey operation. With this constraint, the grant allows the operation only when the encryption context in the request is a case-sensitive match for the encryption context in the grant constraint.

$ 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}

A request like the following from the grantee principal would satisfy the EncryptionContextEquals constraint.

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

For details about the grant constraints, see Using grant constraints. For detailed information about grants, see Grants in Amazon KMS.

Amazon KMS uses Amazon CloudTrail to log the encryption context so you can determine which KMS keys and data have been accessed. The log entry shows exactly which KMS keys was used to encrypt or decrypt specific data referenced by the encryption context in the log entry.

Important

Because the encryption context is logged, it must not contain sensitive information.

To simplify use of any encryption context when you call the Decrypt or ReEncrypt operations, you can store the encryption context alongside the encrypted data. We recommend that you store only enough of the encryption context to help you create the full encryption context when you need it for encryption or decryption.

For example, if the encryption context is the fully qualified path to a file, store only part of that path with the encrypted file contents. Then, when you need the full encryption context, reconstruct it from the stored fragment. If someone tampers with the file, such as renaming it or moving it to a different location, the encryption context value changes and the decryption request fails.

Key policy

When you create a KMS keys, you determine who can use and manage that KMS keys. 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 Amazon managed keys. For more information, see Key policies in Amazon KMS.

Grant

A grant is a policy instrument that allows Amazon principals to use Amazon KMS keys in cryptographic operations. It also can let them view a KMS keys (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 Amazon KMS.

Auditing KMS key usage

You can use Amazon CloudTrail to audit key usage. CloudTrail creates log files that contain a history of Amazon API calls and related events for your account. These log files include all Amazon KMS API requests made with the Amazon Management Console, Amazon SDKs, and command line tools. The log files also include requests to Amazon KMS that Amazon 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 Amazon CloudTrail and the Amazon 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). Amazon KMS operates the key infrastructure for you. Amazon KMS creates and securely stores your root keys, called Amazon KMS keys. For more information about how Amazon KMS operates, see Amazon Key Management Service Cryptographic Details.