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 KMS keys, but you can create and use asymmetric KMS keys for encryption or signing.

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 an encryption key. In addition to the key material used to encrypt and decrypt data, a KMS key includes metadata, such as the key ID, creation date, description, and key state.

KMS keys can be symmetric or asymmetric. A symmetric KMS key represents a 256-bit key used for encryption and decryption. An asymmetric KMS key can represent an RSA key pair used for encryption and decryption or signing and verification (but not both). Or an asymmetric KMS key can represent an elliptic curve (ECC) key pair used for signing and verification. For detailed information about symmetric and asymmetric KMS keys, see Asymmetric keys in Amazon KMS.

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.

Amazon KMS supports three types of KMS keys: customer managed keys, Amazon managed keys, and 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 365 days (1 year).
Amazon managed key Yes No Yes Required. Every 1095 days (3 years).
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. Other Amazon services offer to encrypt your data under a customer managed key that you choose. And 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

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.

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. 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 Amazon Key Management Service Pricing and 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.

Amazon owned key rotation - For information about the types of KMS key that an Amazon service supports, including Amazon owned keys, see the Encryption at Rest topic in the user guide or developer guide for the service.

Symmetric KMS keys

When you create a Amazon KMS key, by default, you get a symmetric KMS key.

In Amazon KMS, a symmetric KMS key represents a 256-bit encryption key that never leaves Amazon KMS unencrypted. To use a symmetric KMS key, you must call Amazon KMS. Symmetric keys are used in symmetric encryption, where the same key is used for encryption and decryption. Unless your task explicitly requires asymmetric encryption, symmetric KMS keys, which never leave Amazon KMS unencrypted, are a good choice.

Amazon services that are integrated with Amazon KMS use symmetric 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 symmetric and 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 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 KMS keys, import your own key material into a symmetric KMS key, and create symmetric 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.

Data keys

Data keys are encryption keys you can use to encrypt data, including large amounts of data and other data encryption keys. Unlike 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 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 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 your 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 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 KMS key key type KMS key 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
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

[1] GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext generate an asymmetric data key pair that is protected by a symmetric 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 secret string of bits used in a cryptographic algorithm. Key material must be kept secret to protect the cryptographic operations that use it.

Each KMS key includes key material along with metadata, such as its key ID and key policy. The key material origin 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, 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.

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

KMS (default)

API value: AWS_KMS

Amazon KMS creates and manages the key material for the KMS key in its own key store. 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

API value: 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.

Custom key store (CloudHSM)

API value: AWS_CLOUDHSM

Amazon KMS created the key material for the KMS key in 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 encryption algorithms or signing 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 for a KMS key based on its key spec. For example, you can deny permission to schedule deletion of a 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 -or- signing and verification. A key cannot support both. Using a KMS key for more than one type of operations makes the product of both operations more vulnerable to attack.

The key usage for symmetric KMS keys is always encryption and decryption. The key usage for elliptic curve (ECC) KMS keys is always signing and verification. You only need to choose a key usage for RSA KMS keys. You choose the key usage when you create the KMS key, and you cannot change it. If you've chosen the wrong key usage, delete the KMS key, and create a new one.

For choosing the key usage, 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.

To allow principals to create KMS keys only for signing and verification or only for encryption and decryption, 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.

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

You cannot specify an encryption context in a cryptographic operation with an asymmetric KMS key. The standard asymmetric encryption algorithms that Amazon KMS uses do not support an encryption context.

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. It appears in plaintext in Amazon CloudTrail Logs so you can use it to identify and categorize your cryptographic operations.

An encryption context can consist of any keys and values. However, because it is not secret and not encrypted, 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.

The key and value in an encryption context pair must be simple literal strings. They cannot be integers or objects, or any type that is not fully resolved. If you use a different type, such as an integer or float, Amazon KMS interprets it as a string.

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

The encryption context key and value can include special characters, such as underscores (_), dashes (-), slashes (/, \) and colons (:).

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.

The encryption context is used primarily to verify integrity and authenticity. But you can also use the encryption context to control access to symmetric 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 Using 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 Using 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.