# KMS key access and permissions To use AWS KMS, you must have credentials that AWS can use to authenticate your requests. The credentials must include permissions to access AWS resources: AWS KMS keys and [aliases](kms-alias.md). No AWS principal has any permissions to a KMS key unless that permission is provided explicitly and never denied. There are no implicit or automatic permission to use or manage a KMS key. To control access to your KMS keys, you can use the following policy mechanisms. + [Key policy](key-policies.md) – Every KMS key has a key policy. It is the primary mechanism for controlling access to a KMS key. You can use the key policy alone to control access, which means the full scope of access to the KMS key is defined in a single document (the key policy). For more information about using key policies, see [Key policies](key-policies.md). + [IAM policies](iam-policies.md) – You can use IAM policies in combination with the key policy and grants to control access to a KMS key. Controlling access this way enables you to manage all of the permissions for your IAM identities in IAM. To use an IAM policy to allow access to a KMS key, the key policy must explicitly allow it. For more information about using IAM policies, see [IAM policies](iam-policies.md). + [Grants](grants.md) – You can use grants in combination with the key policy and IAM policies to allow access to a KMS key. Controlling access this way enables you to allow access to the KMS key in the key policy, and to allow identities to delegate their access to others. For more information about using grants, see [Grants in AWS KMS](grants.md). ## KMS key policies The primary way to manage access to your AWS KMS resources is with *policies*. Policies are documents that describe which principals can access which resources. Policies attached to an IAM identity are called *identity-based policies* (or *IAM policies*), and policies attached to other kinds of resources are called *resource policies*. AWS KMS resource policies for KMS keys are called *key policies*. All KMS keys have a key policy. If you don't provide one, AWS KMS creates one for you. The [default key policy](key-policy-default.md) that AWS KMS uses differs depending on whether you create the key in the AWS KMS console or you use the AWS KMS API. We recommend that you edit the default key policy to align with your organization’s requirements for [least-privilege permissions](least-privilege.md). You can use the key policy alone to control access if the key and the IAM principal are in the same AWS account, which means the full scope of access to the KMS key is defined in a single document (the key policy). However, when a caller in one account must access a key in a different account, you cannot use key policy alone to grant access. In the cross-account scenario, an IAM policy must be attached to the caller's user or role that explicitly allows the caller to make the API call. You can also use IAM policies in combination with key policies and grants to control access to a KMS key. To use an IAM policy to control access to a KMS key, the key policy must give the account permission to use IAM policies. You can either specify a [key policy statement that enables IAM policies](key-policy-default.md#key-policy-default-allow-root-enable-iam), or you can explicitly [specify allowed principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#Principal_specifying) in the key policy. When writing policies, ensure that you have strong controls restricting who can perform the following actions: + Update, create, and delete IAM and KMS key policies + Attach and detach IAM policies from users, roles, and groups + Attach and detach KMS key polices from your KMS keys ## KMS key grants In addition to IAM and key policies, AWS KMS supports [grants](grants.md). Grants provide a flexible and powerful way to delegate permissions. You can use grants to issue time-bound KMS key access to IAM principals in your AWS account, or in other AWS accounts. We recommend issuing time-bound access if you don't know the names of the principals at the time that the policies are created, or if the principals that require access frequently change. The [grantee principal](grants.md#terms-grantee-principal) can be in the same account as the KMS key or a different account. If the principal and KMS key are in different accounts, then you must specify an IAM policy in addition to the grant. Grants require additional management because you must call an API to create the grant and to retire or revoke the grant when it is no longer needed. # Key policies in AWS KMS A key policy is a resource policy for an AWS KMS key. Key policies are the primary way to control access to KMS keys. Every KMS key must have exactly one key policy. The statements in the key policy determine who has permission to use the KMS key and how they can use it. You can also use [IAM policies](iam-policies.md) and [grants](grants.md) to control access to the KMS key, but every KMS key must have a key policy. No AWS principal, including the account root user or key creator, has any permissions to a KMS key unless they are explicitly allowed, and never denied, in a key policy, IAM policy, or grant. Unless the key policy explicitly allows it, you cannot use IAM policies to *allow* access to a KMS key. Without permission from the key policy, IAM policies that allow permissions have no effect. (You can use an IAM policy to *deny* a permission to a KMS key without permission from a key policy.) The default key policy enables IAM policies. To enable IAM policies in your key policy, add the policy statement described in [Allows access to the AWS account and enables IAM policies](key-policy-default.md#key-policy-default-allow-root-enable-iam). Unlike IAM policies, which are global, key policies are Regional. A key policy controls access only to a KMS key in the same Region. It has no effect on KMS keys in other Regions. **Topics** + [ # Creating a key policy ](key-policy-overview.md) + [ # Default key policy ](key-policy-default.md) + [ # View a key policies ](key-policy-viewing.md) + [ # Change a key policy ](key-policy-modifying.md) + [Permissions for AWS services](key-policy-services.md) # Creating a key policy You can create and manage key policies in the AWS KMS console or by using AWS KMS API operations, such as [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html), [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html), and [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html). When you create a KMS key in the AWS KMS console, the console walks you through the steps of creating a key policy based on the [default key policy for the console](key-policy-default.md). When you use the `CreateKey` or `ReplicateKey` APIs, if you don't specify a key policy, these APIs apply the [default key policy for keys created programmatically](key-policy-default.md). When you use the `PutKeyPolicy` API, you are required to specify a key policy. Each policy document can have one or more policy statements. The following example shows a valid key policy document with one policy statement. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "DescribePolicyStatement", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/Alice" }, "Action": "kms:DescribeKey", "Resource": "*", "Condition": { "StringEquals": { "kms:KeySpec": "SYMMETRIC_DEFAULT" } } } ] } ``` ------ **Topics** + [ ## Key policy format ](#key-policy-format) + [ ## Elements in a key policy ](#key-policy-elements) + [ ## Example key policy ](#key-policy-example) ## Key policy format A key policy document must conform to the following rules: + Up to 32 kilobytes (32,768 bytes) + The `Sid` element in a key policy statement can include spaces. (Spaces are prohibited in the `Sid` element of an IAM policy document.) A key policy document can include only the following characters: + Printable ASCII characters + Printable characters in the Basic Latin and Latin-1 Supplement character set + The tab (`\u0009`), line feed (`\u000A`), and carriage return (`\u000D`) special characters ## Elements in a key policy A key policy document must have the following elements: **Version** Specifies the key policy document version. Set the version to `2012-10-17` (the latest version). **Statement** Encloses the policy statements. A key policy document must have at least one statement. Each key policy statement consists of up to six elements. The `Effect`, `Principal`, `Action`, and `Resource` elements are required. **Sid ** (Optional) The statement identifier (`Sid`) an arbitrary string you can use to describe the statement. The `Sid` in a key policy can include spaces. (You can't include spaces in an IAM policy `Sid` element.) **Effect** (Required) Determines whether to allow or deny the permissions in the policy statement. Valid values are `Allow` or `Deny`. If you don't explicitly allow access to a KMS key, access is implicitly denied. You can also explicitly deny access to a KMS key. You might do this to make sure that a user cannot access it, even when a different policy allows access. **Principal** (Required) The [principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#Principal_specifying) is the identity that gets the permissions specified in the policy statement. You can specify AWS accounts, IAM users, IAM roles, and some AWS services as principals in a key policy. IAM [user groups](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) are not a valid principal in any policy type. An asterisk value, such as `"AWS": "*"` represents all AWS identities in all accounts. Do not set the Principal to an asterisk (\$1) in any key policy statement that allows permissions unless you use [conditions](policy-conditions.md) to limit the key policy. An asterisk gives every identity in every AWS account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other AWS accounts can use your KMS key whenever they have corresponding permissions in their own account. IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. When the principal in a key policy statement is an [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts) expressed as `arn:aws:iam::111122223333:root"`, the policy statement doesn't give permission to any IAM principal. Instead, it gives the AWS account permission to use IAM policies to delegate the permissions specified in the key policy. (A principal in `arn:aws:iam::111122223333:root"` format does *not* represent the [AWS account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html), despite the use of "root" in the account identifier. However, the account principal represents the account and its administrators, including the account root user.) When the principal is another AWS account or its principals, the permissions are effective only when the account is enabled in the Region with the KMS key and key policy. For information about Regions that are not enabled by default ("opt-in Regions"), see [Managing AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the *AWS General Reference*. To allow a different AWS account or its principals to use a KMS key, you must provide permission in a key policy and in an IAM policy in the other account. For details, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md). **Action** (Required) Specify the API operations to allow or deny. For example, the `kms:Encrypt` action corresponds to the AWS KMS [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) operation. You can list more than one action in a policy statement. For more information, see [Permissions reference](kms-api-permissions-reference.md). If the required `Action` element is missing from a key policy statement, the policy statement has no effect. A key policy statement without an `Action` element doesn't apply to any KMS key. When a key policy statement is missing its `Action` element, the AWS KMS console correctly reports an error, but the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) and [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) APIs succeed, even though the policy statement is ineffective. **Resource** (Required) In a key policy, the value of the Resource element is `"*"`, which means "this KMS key." The asterisk (`"*"`) identifies the KMS key to which the key policy is attached. If the required `Resource` element is missing from a key policy statement, the policy statement has no effect. A key policy statement without a `Resource` element doesn't apply to any KMS key. When a key policy statement is missing its `Resource` element, the AWS KMS console correctly reports an error, but the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) and [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) APIs succeed, even though the policy statement is ineffective. **Condition** (Optional) Conditions specify requirements that must be met for a key policy to take effect. With conditions, AWS can evaluate the context of an API request to determine whether or not the policy statement applies. To specify conditions, you use predefined *condition keys*. AWS KMS supports [AWS global condition keys](conditions-aws.md) and [AWS KMS condition keys](conditions-kms.md). To support attribute-based access control (ABAC), AWS KMS provides condition keys that control access to a KMS key based on tags and aliases. For details, see [ABAC for AWS KMS](abac.md). The format for a condition is: ``` "Condition": {"condition operator": {"condition key": "condition value"}} ``` such as: ``` "Condition": {"StringEquals": {"kms:CallerAccount": "111122223333"}} ``` For more information about AWS policy syntax, see [AWS IAM Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the *IAM User Guide*. ## Example key policy The following example shows a complete key policy for a symmetric encryption KMS key. You can use it for reference as you read about the key policy concepts in this chapter. This key policy combines the example policy statements from the preceding [default key policy](key-policy-default.md) section into a single key policy that accomplishes the following: + Allows the example AWS account, 111122223333, full access to the KMS key. It allows the account and its administrators, including the account root user (for emergencies), to use IAM policies in the account to allow access to the KMS key. + Allows the `ExampleAdminRole` IAM role to administer the KMS key. + Allows the `ExampleUserRole` IAM role to use the KMS key. ------ #### [ JSON ] **** ``` { "Id": "key-consolepolicy", "Version":"2012-10-17", "Statement": [ { "Sid": "EnableIAMUserPermissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "AllowKeyAdministratorsAccess", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleAdminRole" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion", "kms:RotateKeyOnDemand" ], "Resource": "*" }, { "Sid": "AllowKeyUse", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleUserRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, { "Sid": "AllowAttachmentPersistentResources", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleUserRole" }, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } } ] } ``` ------ # Default key policy When you create a KMS key, you can specify the key policy for the new KMS key. If you don't provide one, AWS KMS creates one for you. The default key policy that AWS KMS uses differs depending on whether you create the key in the AWS KMS console or you use the AWS KMS API. **Default key policy when you create a KMS key programmatically** When you create a KMS key programmatically with the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) (including by using the [AWS SDKs](https://aws.amazon.com/tools/#sdk), [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/) or [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/)), and you don't specify a key policy, AWS KMS applies a very simple default key policy. This default key policy has one policy statement that gives the AWS account that owns the KMS key permission to use IAM policies to allow access to all AWS KMS operations on the KMS key. For more information about this policy statement, see [Allows access to the AWS account and enables IAM policies](#key-policy-default-allow-root-enable-iam). **Default key policy when you create a KMS key with the AWS Management Console** When you [create a KMS key with the AWS Management Console](create-keys.md), the key policy begins with the policy statement that [allows access to the AWS account and enables IAM policies](#key-policy-default-allow-root-enable-iam). The console then adds a [key administrators statement](#key-policy-default-allow-administrators), a [key users statement](#key-policy-default-allow-users), and (for most key types) a statement that allows principals to use the KMS key with [other AWS services](#key-policy-service-integration). You can use the features of the AWS KMS console to specify the IAM users, IAM roles, and AWS accounts who are key administrators and those who are key users (or both). **Permissions** + [Allows access to the AWS account and enables IAM policies](#key-policy-default-allow-root-enable-iam) + [Allows key administrators to administer the KMS key](#key-policy-default-allow-administrators) + [Allows key users to use the KMS key](#key-policy-default-allow-users) + [Allows key users to use a KMS key for cryptographic operations](#key-policy-users-crypto) + [Allows key users to use the KMS key with AWS services](#key-policy-service-integration) ## Allows access to the AWS account and enables IAM policies The following default key policy statement is critical. + It gives the AWS account that owns the KMS key full access to the KMS key. Unlike other AWS resource policies, an AWS KMS key policy does not automatically give permission to the account or any of its identities. To give permission to account administrators, the key policy must include an explicit statement that provides this permission, like this one. + It allows the account to use IAM policies to allow access to the KMS key, in addition to the key policy. Without this permission, IAM policies that allow access to the key are ineffective, although IAM policies that deny access to the key are still effective. + It reduces the risk of the key becoming unmanageable by giving access control permission to the account administrators, including the account root user, which cannot be deleted. The following key policy statement is the entire default key policy for KMS keys created programmatically. It's the first policy statement in the default key policy for KMS keys created in the AWS KMS console. ``` { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" } ``` **Allows IAM policies to allow access to the KMS key.** The key policy statement shown above gives the AWS account that owns the key permission to use IAM policies, as well as key policies, to allow all actions (`kms:*`) on the KMS key. The principal in this key policy statement is the [account principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts), which is represented by an ARN in this format: `arn:aws:iam::account-id:root`. The account principal represents the AWS account and its administrators. When the principal in a key policy statement is the account principal, the policy statement doesn't give any IAM principal permission to use the KMS key. Instead, it allows the account to use IAM policies to *delegate* the permissions specified in the policy statement. This default key policy statement allows the account to use IAM policies to delegate permission for all actions (`kms:*`) on the KMS key. ** Reduces the risk of the KMS key becoming unmanageable.** Unlike other AWS resource policies, an AWS KMS key policy does not automatically give permission to the account or any of its principals. To give permission to any principal, including the [account principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts), you must use a key policy statement that provides the permission explicitly. You are not required to give the account principal, or any principal, access to the KMS key. However, giving access to the account principal helps you prevent the key from becoming unmanageable. For example, suppose you create a key policy that gives only one user access to the KMS key. If you then delete that user, the key becomes unmanageable and you must [contact AWS Support](https://console.aws.amazon.com/support/home#/case/create) to regain access to the KMS key. The key policy statement shown above gives the [account principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts) permission to control the key. The account principal represents the AWS account and its administrators, including the [account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html). The account root user is the only principal that cannot be deleted unless you delete the AWS account. IAM best practices discourage acting on behalf of the account root user, except in an emergency. However, you might need to act as the account root user if you delete all other users and roles with access to the KMS key. ## Allows key administrators to administer the KMS key The default key policy created by the console allows you to choose IAM users and roles in the account and make them *key administrators*. This statement is called the *key administrators statement*. Key administrators have permissions to manage the KMS key, but do not have permissions to use the KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations). You can add IAM users and roles to the list of key administrators when you create the KMS key in the default view or the policy view. **Warning** Because key administrators have permission to change the key policy and create grants, they can give themselves and others AWS KMS permissions not specified in this policy. Principals who have permission to manage tags and aliases can also control access to a KMS key. For details, see [ABAC for AWS KMS](abac.md). **Note** IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. The following example shows the key administrators statement in the default view of the AWS KMS console. ![\[Key administrators in the console's default key policy, default view\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-key-policy-administrators-60.png) The following is an example key administrators statement in the policy view of the AWS KMS console. This key administrators statement is for a single-Region symmetric encryption KMS key. **Note** The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement. ``` { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": {"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"}, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion", "kms:RotateKeyOnDemand" ], "Resource": "*" } ``` The default key administrators statement for the most common KMS key, a single-Region symmetric encryption KMS key, allows the following permissions. For detailed information about each permission, see the [AWS KMS permissions](kms-api-permissions-reference.md). When you use the AWS KMS console to create a KMS key, the console adds the users and roles you specify to the `Principal` element in the key administrators statement. Many of these permissions contain the wildcard character (`*`), which allows all permissions that begin with the specified verb. As a result, when AWS KMS adds new API operations, key administrators are automatically allowed to use them. You don't have to update your key policies to include the new operations. If you prefer to limit your key administrators to a fixed set of API operations, you can [change your key policy](key-policy-modifying.md). **`kms:Create*`** Allows [`kms:CreateAlias`](kms-alias.md) and [`kms:CreateGrant`](grants.md). (The `kms:CreateKey` permission is valid only in an IAM policy.) **`kms:Describe*`** Allows [`kms:DescribeKey`](viewing-keys.md). The `kms:DescribeKey` permission is required to view the key details page for a KMS key in the AWS Management Console. **`kms:Enable*`** Allows [`kms:EnableKey`](enabling-keys.md). For symmetric encryption KMS keys, it also allows [`kms:EnableKeyRotation`](rotate-keys.md). **`kms:List*`** Allows [`kms:ListGrants`](grants.md), [https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyPolicies.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyPolicies.html), and [`kms:ListResourceTags`](tagging-keys.md). (The `kms:ListAliases` and `kms:ListKeys` permissions, which are required to view KMS keys in the AWS Management Console, are valid only in IAM policies.) **`kms:Put*`** Allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html). This permission allows key administrators to change the key policy for this KMS key. **`kms:Update*`** Allows [`kms:UpdateAlias`](alias-update.md) and [https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateKeyDescription.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateKeyDescription.html). For multi-Region keys, it allows [`kms:UpdatePrimaryRegion`](multi-region-update.md#update-primary-console) on this KMS key. **`kms:Revoke*`** Allows [`kms:RevokeGrant`](grant-delete.md), which allows key administrators to [delete a grant](grant-delete.md) even if they are not a [retiring principal](grants.md#terms-retiring-principal) in the grant. **`kms:Disable*`** Allows [`kms:DisableKey`](enabling-keys.md). For symmetric encryption KMS keys, it also allows [`kms:DisableKeyRotation`](rotate-keys.md). **`kms:Get*`** Allows [`kms:GetKeyPolicy`](key-policy-viewing.md) and [`kms:GetKeyRotationStatus`](rotate-keys.md). For KMS keys with imported key material, it allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html). For asymmetric KMS keys, it allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html). The `kms:GetKeyPolicy` permission is required to view the key policy of a KMS key in the AWS Management Console. **`kms:Delete*`** Allows [`kms:DeleteAlias`](kms-alias.md). For keys with imported key material, it allows [`kms:DeleteImportedKeyMaterial`](importing-keys.md). The `kms:Delete*` permission does not allow key administrators to delete the KMS key (`ScheduleKeyDeletion`). **`kms:TagResource`** Allows [`kms:TagResource`](tagging-keys.md), which allows key administrators to add tags to the KMS key. Because tags can also be used to control access to the KMS key, this permission can allow administrators to allow or deny access to the KMS key. For details, see [ABAC for AWS KMS](abac.md). **`kms:UntagResource`** Allows [`kms:UntagResource`](tagging-keys.md), which allows key administrators to delete tags from the KMS key. Because tags can be used to control access to the key, this permission can allow administrators to allow or deny access to the KMS key. For details, see [ABAC for AWS KMS](abac.md). **`kms:ScheduleKeyDeletion`** Allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html), which allows key administrators to [delete this KMS key](deleting-keys.md). To delete this permission, clear the **Allow key administrators to delete this key** option. **`kms:CancelKeyDeletion`** Allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_CancelKeyDeletion.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CancelKeyDeletion.html), which allows key administrators to [cancel deletion of this KMS key](deleting-keys.md). To delete this permission, clear the **Allow key administrators to delete this key** option. **`kms:RotateKeyOnDemand`** Allows [https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html), which allows key administrators to [perform on-demand rotation of the key material in this KMS key](rotating-keys-on-demand.md).   AWS KMS adds the following permissions to the default key administrators statement when you create special-purpose keys. **`kms:ImportKeyMaterial`** The [https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) permission allows key administrators to import key material into the KMS key. This permission is included in the key policy only when you [create a KMS key with no key material](importing-keys-create-cmk.md). **`kms:ReplicateKey`** The [https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) permission allows key administrators to [create a replica of a multi-Region primary key](multi-region-keys-replicate.md) in a different AWS Region. This permission is included in the key policy only when you create a multi-Region primary or replica key. **`kms:UpdatePrimaryRegion`** The [https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) permission allows key administrators to [change a multi-Region replica key to a multi-Region primary key](multi-region-update.md). This permission is included in the key policy only when you create a multi-Region primary or replica key. ## Allows key users to use the KMS key The default key policy that the console creates for KMS keys allows you to choose IAM users and IAM roles in the account, and external AWS accounts, and make them *key users*. The console adds two policy statements to the key policy for key users. + [Use the KMS key directly](#key-policy-users-crypto) — The first key policy statement gives key users permission to use the KMS key directly for all supported [cryptographic operations](kms-cryptography.md#cryptographic-operations) for that type of KMS key. + [Use the KMS key with AWS services](#key-policy-service-integration) — The second policy statement gives key users permission to allow AWS services that are integrated with AWS KMS to use the KMS key on their behalf to protect resources, such as Amazon S3 buckets and Amazon DynamoDB tables. You can add IAM users, IAM roles, and other AWS accounts to the list of key users when you create the KMS key. You can also edit the list with the console's default view for key policies, as shown in the following image. The default view for key policies is on the key details page. For more information about allowing users in other AWS accounts to use the KMS key, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md). **Note** IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. ![\[Key users in the console's default key policy, default view\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-key-policy-users-sm.png) The default *key users statements* for a single-Region symmetric allows the following permissions. For detailed information about each permission, see the [AWS KMS permissions](kms-api-permissions-reference.md). When you use the AWS KMS console to create a KMS key, the console adds the users and roles you specify to the `Principal` element in each key users statement. **Note** The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::111122223333:role/ExampleRole", "arn:aws:iam::444455556666:root" ]}, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, { "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": [ "arn:aws:iam::111122223333:role/ExampleRole", "arn:aws:iam::444455556666:root" ]}, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} } ``` ## Allows key users to use a KMS key for cryptographic operations Key users have permission to use the KMS key directly in all [cryptographic operations](kms-cryptography.md#cryptographic-operations) supported on the KMS key. They can also use the [DescribeKey ](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)operation to get detailed information about the KMS key in the AWS KMS console or by using the AWS KMS API operations. By default, the AWS KMS console adds key users statements like those in the following examples to the default key policy. Because they support different API operations, the actions in the policy statements for symmetric encryption KMS keys, HMAC KMS keys, asymmetric KMS keys for public key encryption, and asymmetric KMS keys for signing and verification are slightly different. **Symmetric encryption KMS keys** The console adds the following statement to the key policy for symmetric encryption KMS keys. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole"}, "Action": [ "kms:Decrypt", "kms:DescribeKey", "kms:Encrypt", "kms:GenerateDataKey*", "kms:ReEncrypt*" ], "Resource": "*" } ``` **HMAC KMS keys** The console adds the following statement to the key policy for HMAC KMS keys. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole"}, "Action": [ "kms:DescribeKey", "kms:GenerateMac", "kms:VerifyMac" ], "Resource": "*" } ``` **Asymmetric KMS keys for public key encryption** The console adds the following statement to the key policy for asymmetric KMS keys with a key usage of **Encrypt and decrypt**. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:DescribeKey", "kms:GetPublicKey" ], "Resource": "*" } ``` **Asymmetric KMS keys for signing and verification** The console adds the following statement to the key policy for asymmetric KMS keys with a key usage of **Sign and verify**. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole"}, "Action": [ "kms:DescribeKey", "kms:GetPublicKey", "kms:Sign", "kms:Verify" ], "Resource": "*" } ``` **Asymmetric KMS keys for deriving shared secrets** The console adds the following statement to the key policy for asymmetric KMS keys with a key usage of **Key agreement**. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole"}, "Action": [ "kms:DescribeKey", "kms:GetPublicKey", "kms:DeriveSharedSecret" ], "Resource": "*" } ``` The actions in these statements give the key users the following permissions. [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) Allows key users to encrypt data with this KMS key. [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) Allows key users to decrypt data with this KMS key. [https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) Allows key users to derive shared secrets with this KMS key. [https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) Allows key users to get detailed information about this KMS key including its identifiers, creation date, and key state. It also allows the key users to display details about the KMS key in the AWS KMS console. `kms:GenerateDataKey*` Allows key users to request a symmetric data key or an asymmetric data key pair for client-side cryptographic operations. The console uses the \$1 wildcard character to represent permission for the following API operations: [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), and [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html). These permissions are valid only on the symmetric KMS keys that encrypt the data keys. [kms:GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) Allows key users to use an HMAC KMS key to generate an HMAC tag. [kms:GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) Allows key users to download the public key of the asymmetric KMS key. Parties with whom you share this public key can encrypt data outside of AWS KMS. However, those ciphertexts can be decrypted only by calling the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation in AWS KMS. [kms:ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html)\$1 Allows key users to re-encrypt data that was originally encrypted with this KMS key, or to use this KMS key to re-encrypt previously encrypted data. The [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) operation requires access to both source and destination KMS keys. To accomplish this, you can allow the `kms:ReEncryptFrom` permission on the source KMS key and `kms:ReEncryptTo` permission on the destination KMS key. However, for simplicity, the console allows `kms:ReEncrypt*` (with the `*` wildcard character) on both KMS keys. [kms:Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) Allows key users to sign messages with this KMS key. [kms:Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) Allows key users to verify signatures with this KMS key. [kms:VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) Allows key users to use an HMAC KMS key to verify an HMAC tag. ## Allows key users to use the KMS key with AWS services The default key policy in the console also gives key users the grant permissions they need to protect their data in AWS services that use grants. AWS services often use grants to get specific and limited permission to use a KMS key. This key policy statement allows the key user to create, view, and revoke grants on the KMS key, but only when the grant operation request comes from an [AWS service integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration). The [kms:GrantIsForAWSResource](conditions-kms.md#conditions-kms-grant-is-for-aws-resource) policy condition doesn't allow the user to call these grant operations directly. When the key user allows it, an AWS service can create a grant on the user's behalf that allows the service to use the KMS key to protect the user's data. Key users require these grant permissions to use their KMS key with integrated services, but these permissions are not sufficient. Key users also need permission to use the integrated services. For details about giving users access to an AWS service that integrates with AWS KMS, consult the documentation for the integrated service. ``` { "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/ExampleKeyUserRole"}, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} } ``` For example, key users can use these permissions on the KMS key in the following ways. + Use this KMS key with Amazon Elastic Block Store (Amazon EBS) and Amazon Elastic Compute Cloud (Amazon EC2) to attach an encrypted EBS volume to an EC2 instance. The key user implicitly gives Amazon EC2 permission to use the KMS key to attach the encrypted volume to the instance. For more information, see [How Amazon Elastic Block Store (Amazon EBS) uses AWS KMS](services-ebs.md). + Use this KMS key with Amazon Redshift to launch an encrypted cluster. The key user implicitly gives Amazon Redshift permission to use the KMS key to launch the encrypted cluster and create encrypted snapshots. For more information, see [How Amazon Redshift uses AWS KMS](services-redshift.md). + Use this KMS key with other [AWS services integrated with AWS KMS](service-integration.md) that use grants to create, manage, or use encrypted resources with those services. The default key policy allows key users to delegate their grant permission to *all* integrated services that use grants. However, you can create a custom key policy that restricts the permission to specified AWS services. For more information, see the [kms:ViaService](conditions-kms.md#conditions-kms-via-service) condition key. # View a key policies You can view the key policy for an AWS KMS [customer managed key](concepts.md#customer-mgn-key) or an [AWS managed key](concepts.md#aws-managed-key) in your account by using the AWS KMS console or the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation in the AWS KMS API. You cannot use these techniques to view the key policy of a KMS key in a different AWS account. To learn more about AWS KMS key policies, see [Key policies in AWS KMS](key-policies.md). To learn how to determine which users and roles have access to a KMS key, see [Determining access to AWS KMS keys](determining-access.md). ## Using the AWS KMS console Authorized users can view the key policy for an [AWS managed key](concepts.md#aws-managed-key) or a [customer managed key](concepts.md#customer-mgn-key) on the **Key policy** tab of the AWS Management Console. To view the key policy for a KMS key in the AWS Management Console, you must have [kms:ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html), [kms:DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), and [kms:GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) permissions. 1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms). 1. To change the AWS Region, use the Region selector in the upper-right corner of the page. 1. To view the keys in your account that AWS creates and manages for you, in the navigation pane, choose **AWS managed keys**. To view the keys in your account that you create and manage, in the navigation pane choose **Customer managed keys**. 1. In the list of KMS keys, choose the alias or key ID of the KMS key that you want to examine. 1. Choose the **Key policy** tab. On the **Key policy** tab, you might see the key policy document. This is *policy view*. In the key policy statements, you can see the principals who have been given access to the KMS key by the key policy, and you can see the actions they can perform. The following example shows the policy view for the [default key policy](key-policy-default.md). ![\[View of the default key policy in policy view in the AWS KMS console\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-key-policy-view.png) Or, if you created the KMS key in the AWS Management Console, you will see the *default view* with sections for **Key administrators**, **Key deletion**, and **Key Users**. To see the key policy document, choose **Switch to policy view**. The following example shows the default view for the [default key policy](key-policy-default.md). ![\[View of the default key policy in default view in the AWS KMS console\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-key-policy-full-vsm.png) ## Using the AWS KMS API To get the key policy for a KMS key in your AWS account, use the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation in the AWS KMS API. You cannot use this operation to view a key policy in a different account. The following example uses the [get-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) command in the AWS Command Line Interface (AWS CLI), but you can use any AWS SDK to make this request. Note that the `PolicyName` parameter is required even though `default` is its only valid value. Also, this command requests the output in text, rather than JSON, to make it easier to view. Before running this command, replace the example key ID with a valid one from your account. ``` $ aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default --output text ``` The response should be similar to the following one, which returns the [default key policy](key-policy-default.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id" : "key-consolepolicy-3", "Statement" : [ { "Sid" : "EnableIAMUserPermissions", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] } ``` ------ # Change a key policy You can change the key policy for a KMS key in your AWS account by using the AWS Management Console or the [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operation. You cannot use these techniques to change the key policy of a KMS key in a different AWS account. When changing a key policy, keep in mind the following rules: + You can view the key policy for an [AWS managed key](concepts.md#aws-managed-key) or a [customer managed key](concepts.md#customer-mgn-key), but you can only change the key policy for a customer managed key. The policies of AWS managed keys are created and managed by the AWS service that created the KMS key in your account. You cannot view or change the key policy for an [AWS owned key](concepts.md#aws-owned-key). + You can add or remove IAM users, IAM roles, and AWS accounts in the key policy, and change the actions that are allowed or denied for those principals. For more information about the ways to specify principals and permissions in a key policy, see [Key policies](key-policies.md). + You cannot add IAM groups to a key policy, but you can add multiple IAM users and IAM roles. For more information, see [Allowing multiple IAM principals to access a KMS key](iam-policies.md#key-policy-modifying-multiple-iam-users). + If you add external AWS accounts to a key policy, you must also use IAM policies in the external accounts to give permissions to IAM users, groups, or roles in those accounts. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md). + The resulting key policy document cannot exceed 32 KB (32,768 bytes). ## How to change a key policy You can change a key policy in three different ways as explained in the following sections. **Topics** + [ ### Using the AWS Management Console default view ](#key-policy-modifying-how-to-console-default-view) + [ ### Using the AWS Management Console policy view ](#key-policy-modifying-how-to-console-policy-view) + [ ### Using the AWS KMS API ](#key-policy-modifying-how-to-api) ### Using the AWS Management Console default view You can use the console to change a key policy with a graphical interface called the *default view*. If the following steps don't match what you see in the console, it might mean that this key policy was not created by the console. Or it might mean that the key policy has been modified in a way that the console's default view does not support. In that case, follow the steps at [Using the AWS Management Console policy view](#key-policy-modifying-how-to-console-policy-view) or [Using the AWS KMS API](#key-policy-modifying-how-to-api). 1. View the key policy for a customer managed key as described in [Using the AWS KMS console](key-policy-viewing.md#key-policy-viewing-console). (You cannot change the key policies of AWS managed keys.) 1. Decide what to change. + To add or remove [key administrators](key-policy-default.md#key-policy-default-allow-administrators), and to allow or prevent key administrators from [deleting the KMS key](deleting-keys.md), use the controls in the **Key administrators** section of the page. Key administrators manage the KMS key, including enabling and disabling it, setting key policy, and [enabling key rotation](rotate-keys.md). + To add or remove [key users](key-policy-default.md#key-policy-default-allow-users), and to allow or disallow external AWS accounts to use the KMS key, use the controls in the **Key users** section of the page. Key users can use the KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations), such as encrypting, decrypting, re-encrypting, and generating data keys. ### Using the AWS Management Console policy view You can use the console to change a key policy document with the console's *policy view*. 1. View the key policy for a customer managed key as described in [Using the AWS KMS console](key-policy-viewing.md#key-policy-viewing-console). (You cannot change the key policies of AWS managed keys.) 1. In the **Key Policy** section, choose **Switch to policy view**. 1. Choose **Edit**. 1. Decide what to change. + To add a new statement, choose **Add new statement**. Then, you can select the actions, principals, and conditions for your new key policy statement from the options listed in the statement builder panel, or manually enter the policy statement elements. + To remove a statement from your key policy, select the statement and then choose **Remove**. Review the selected policy statement and confirm that you want to remove it. If you decide that you do not want to proceed with removing the statement, choose **Cancel**. + To edit an existing key policy statement, select the statement. Then, you can use the statement builder panel to choose specific elements that you want to modify, or manually edit the statement. 1. Choose **Save changes**. ### Using the AWS KMS API You can use the [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operation to change the key policy of a KMS key in your AWS account. You cannot use this API on a KMS key in a different AWS account. 1. Use the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation to get the existing key policy document, and then save the key policy document to a file. For sample code in multiple programming languages, see [Use `GetKeyPolicy` with an AWS SDK or CLI](example_kms_GetKeyPolicy_section.md). 1. Open the key policy document in your preferred text editor, edit the key policy document, and then save the file. 1. Use the [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operation to apply the updated key policy document to the KMS key. For sample code in multiple programming languages, see [Use `PutKeyPolicy` with an AWS SDK or CLI](example_kms_PutKeyPolicy_section.md). For an example of copying a key policy from one KMS key to another, see the [GetKeyPolicy example](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html#examples) in the AWS CLI Command Reference. # Permissions for AWS services in key policies Many AWS services use AWS KMS keys to protect the resources they manage. When a service uses [AWS owned keys](concepts.md#aws-owned-key) or [AWS managed keys](concepts.md#aws-managed-key), the service establishes and maintains the key policies for these KMS keys. However, when you use a [customer managed key](concepts.md#customer-mgn-key) with an AWS service, you set and maintain the key policy. That key policy must allow the service the minimum permissions that it requires to protect the resource on your behalf. We recommend that you follow the principle of least privilege: give the service only the permissions that it requires. You can do this effectively by learning which permissions the service needs and using [AWS global condition keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) and [AWS KMS condition keys](policy-conditions.md) to refine the permissions. To find the permissions that the service requires on a customer managed key, see the encryption documentation for the service. The following list includes links to some services documentation: + **AWS CloudTrail** permissions - [Configure AWS KMS key policies for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail.html#create-kms-key-policy-for-cloudtrail-decrypt) + **Amazon Elastic Block Store** permissions - [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html#ebs-encryption-permissions) and [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EBSEncryption.html#ebs-encryption-permissions) + **AWS Lambda** permissions - [Data encryption at rest for Lambda](https://docs.aws.amazon.com/lambda/latest/dg/security-encryption-at-rest.html) + **Amazon Q** permissions - [Data encryption for Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-encryption.html) + **Amazon Relational Database Service** permissions - [AWS KMS key management](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.Keys.html) + **AWS Secrets Manager** permissions - [Authorizing use of the KMS key](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html#security-encryption-authz) + **Amazon Simple Queue Service** permissions - [Amazon SQS Key management](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html) # Using IAM policies with AWS KMS You can use IAM policies, along with [key policies](key-policies.md), [grants](grants.md), and [VPC endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#edit-vpc-endpoint-policy), to control access to your AWS KMS keys in AWS KMS. **Note** To use an IAM policy to control access to a KMS key, the key policy for the KMS key must give the account permission to use IAM policies. Specifically, the key policy must include the [policy statement that enables IAM policies](key-policy-default.md#key-policy-default-allow-root-enable-iam). This section explains how to use IAM policies to control access to AWS KMS operations. For more general information about IAM, see the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/). All KMS keys must have a key policy. IAM policies are optional. To use an IAM policy to control access to a KMS key, the key policy for the KMS key must give the account permission to use IAM policies. Specifically, the key policy must include the [policy statement that enables IAM policies](key-policy-default.md#key-policy-default-allow-root-enable-iam). IAM policies can control access to any AWS KMS operation. Unlike key policies, IAM policies can control access to multiple KMS keys and provide permissions for the operations of several related AWS services. But IAM policies are particularly useful for controlling access to operations, such as [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html), that can't be controlled by a key policy because they don't involve any particular KMS key. If you access AWS KMS through an Amazon Virtual Private Cloud (Amazon VPC) endpoint, you can also use a VPC endpoint policy to limit access to your AWS KMS resources when using the endpoint. For example, when using the VPC endpoint, you might only allow the principals in your AWS account to access your customer managed keys. For details, see [VPC endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#edit-vpc-endpoint-policy). For help writing and formatting a JSON policy document, see the [IAM JSON Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the *IAM User Guide*. You can use IAM policies in the following ways: + **Attach a permissions policy to a role for federation or cross-account permissions** – You can attach an IAM policy to an IAM role to enable identity federation, allow cross-account permissions, or give permissions to applications running on EC2 instances. For more information about the various use cases for IAM roles, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *IAM User Guide*. + **Attach a permissions policy to a user or a group** – You can attach a policy that allows a user or group of users to call AWS KMS operations. However, IAM best practices recommend that you use identities with temporary credentials, such as IAM roles, whenever possible. The following example shows an IAM policy with AWS KMS permissions. This policy allows the IAM identities to which it is attached to list all KMS keys and aliases. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:ListKeys", "kms:ListAliases" ], "Resource": "*" } } ``` ------ Like all IAM policies, this policy doesn't have a `Principal` element. When you attach an IAM policy to an IAM identity, that identity gets the permissions specified in the policy. For a table showing all of the AWS KMS API actions and the resources that they apply to, see the [Permissions reference](kms-api-permissions-reference.md). ## Allowing multiple IAM principals to access a KMS key IAM groups are not valid principals in a key policy. To allow multiple users and roles to access a KMS key, do one of the following: + Use an IAM role as the principal in the key policy. Multiple authorized users can assume the role as needed. For details, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *IAM User Guide*. While you can list multiple IAM users in a key policy, this practice is not recommended because it requires that you update the key policy every time the list of authorized users changes. Also, IAM best practices discourage the use of IAM users with long-term credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. + Use an IAM policy to give permission to an IAM group. To do this, ensure that the key policy includes the statement that [enables IAM policies to allow access to the KMS key](key-policy-default.md#key-policy-default-allow-root-enable-iam), [create an IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#create-managed-policy-console) that allows access to the KMS key, and then [attach that policy to an IAM group](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) that contains the authorized IAM users. Using this approach, you don't need to change any policies when the list of authorized users changes. Instead, you only need to add or remove those users from the appropriate IAM group. For details, see [IAM user groups](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) in the *IAM User Guide* For more information about how AWS KMS key policies and IAM policies work together, see [Troubleshooting AWS KMS permissions](policy-evaluation.md). # Best practices for IAM policies Securing access to AWS KMS keys is critical to the security of all of your AWS resources. KMS keys are used to protect many of the most sensitive resources in your AWS account. Take the time to design the [key policies](key-policies.md), IAM policies, [grants](grants.md), and VPC endpoint policies that control access to your KMS keys. In IAM policy statements that control access to KMS keys, use the [least privileged principle](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). Give IAM principals only the permissions they need on only the KMS keys they must use or manage. The following best practices apply to IAM policies that control access to AWS KMS keys and aliases. For general IAM policy best practice guidance, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. **Use key policies** Whenever possible, provide permissions in key policies that affect one KMS key, rather than in an IAM policy that can apply to many KMS keys, including those in other AWS accounts. This is particularly important for sensitive permissions like [kms:PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) and [kms:ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) but also for cryptographic operations that determine how your data is protected. **Limit CreateKey permission** Give permission to create keys ([kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html)) only to principals who need it. Principals who create a KMS key also set its key policy, so they can give themselves and others permission to use and manage the KMS keys they create. When you allow this permission, consider limiting it by using [policy conditions](policy-conditions.md). For example, you can use the [kms:KeySpec](conditions-kms.md#conditions-kms-key-spec) condition to limit the permission to symmetric encryption KMS keys. **Specify KMS keys in an IAM policy** As a best practice, specify the [key ARN](concepts.md#key-id-key-ARN) of each KMS key to which the permission applies in the `Resource` element of the policy statement. This practice restricts the permission to the KMS keys that principal requires. For example, this `Resource` element lists only the KMS keys the principal needs to use. ``` "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" ] ``` When specifying KMS keys is impractical, use a `Resource` value that limits access to KMS keys in a trusted AWS account and Region, such as `arn:aws:kms:region:account:key/*`. Or limit access to KMS keys in all Regions (\$1) of a trusted AWS account, such as `arn:aws:kms:*:account:key/*`. You cannot use a [key ID](concepts.md#key-id-key-id), [alias name](concepts.md#key-id-alias-name), or [alias ARN](concepts.md#key-id-alias-ARN) to represent a KMS key in the `Resource` field of an IAM policy. If you specify an alias ARN, the policy applies to the alias, not to the KMS key. For information about IAM policies for aliases, see [Controlling access to aliases](alias-access.md) **Avoid "Resource": "\$1" in an IAM policy** Use wildcard characters (\$1) judiciously. In a key policy, the wildcard character in the `Resource` element represents the KMS key to which the key policy is attached. But in an IAM policy, a wildcard character alone in the `Resource` element (`"Resource": "*"`) applies the permissions to all KMS keys in all AWS accounts that the principal's account has permission to use. This might include [KMS keys in other AWS accounts](key-policy-modifying-external-accounts.md), as well as KMS keys in the principal's account. For example, to use a KMS key in another AWS account, a principal needs permission from the key policy of the KMS key in the external account, and from an IAM policy in their own account. Suppose that an arbitrary account gave your AWS account [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) permission on their KMS keys. If so, an IAM policy in your account that gives a role `kms:Decrypt` permission on all KMS keys (`"Resource": "*"`) would satisfy the IAM part of the requirement. As a result, principals who can assume that role can now decrypt ciphertexts using the KMS key in the untrusted account. Entries for their operations appear in the CloudTrail logs of both accounts. In particular, avoid using `"Resource": "*"` in a policy statement that allows the following API operations. These operations can be called on KMS keys in other AWS accounts. + [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) + [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) + [Cryptographic operations](kms-cryptography.md#cryptographic-operations) ([Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html), [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html), [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html), [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html), [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html), [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html)) + [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html), [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html), [ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html), [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html), [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) **When to use "Resource": "\$1"** In an IAM policy, use a wildcard character in the `Resource` element only for permissions that require it. Only the following permissions require the `"Resource": "*"` element. + [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) + [kms:GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) + [kms:ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) + [kms:ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) + Permissions for custom key stores, such as [kms:CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) and [kms:ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html). Permissions for alias operations ([kms:CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html), [kms:UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html), [kms:DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html)) must be attached to the alias and the KMS key. You can use `"Resource": "*"` in an IAM policy to represent the aliases and the KMS keys, or specify the aliases and KMS keys in the `Resource` element. For examples, see [Controlling access to aliases](alias-access.md).   The examples in this topic provide more information and guidance for designing IAM policies for KMS keys. For IAM best practices for all AWS resources, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. # Specifying KMS keys in IAM policy statements You can use an IAM policy to allow a principal to use or manage KMS keys. KMS keys are specified in the `Resource` element of the policy statement. + To specify a KMS key in an IAM policy statement, you must use its [key ARN](concepts.md#key-id-key-ARN). You cannot use a [key id](concepts.md#key-id-key-id), [alias name](concepts.md#key-id-alias-name), or [alias ARN](concepts.md#key-id-alias-ARN) to identify a KMS key in an IAM policy statement. For example: "`Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`" To control access to a KMS key based on its aliases, use the [kms:RequestAlias](conditions-kms.md#conditions-kms-request-alias) or [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition keys. For details, see [ABAC for AWS KMS](abac.md). Use an alias ARN as the resource only in a policy statement that controls access to alias operations, such as [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/CreateAlias.html), [UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/UpdateAlias.html), or [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/DeleteAlias.html). For details, see [Controlling access to aliases](alias-access.md). + To specify multiple KMS keys in the account and Region, use wildcard characters (\$1) in the Region or resource ID positions of the key ARN. For example, to specify all KMS keys in the US West (Oregon) Region of an account, use "`Resource": "arn:aws:kms:us-west-2:111122223333:key/*`". To specify all KMS keys in all Regions of the account, use "`Resource": "arn:aws:kms:*:111122223333:key/*`". + To represent all KMS keys, use a wildcard character alone (`"*"`). Use this format for operations that don't use any particular KMS key, namely [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html), [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html), [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html), and [ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html). When writing your policy statements, it's a [best practice](iam-policies-best-practices.md) to specify only the KMS keys that the principal needs to use, rather than giving them access to all KMS keys. For example, the following IAM policy statement allows the principal to call the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operations only on the KMS keys listed in the `Resource` element of the policy statement. Specifying KMS keys by key ARN, which is a best practice, ensures that the permissions are limited only to the specified KMS keys. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/01234abcd-12ab-34cd-56ef-1234567890ab" ] } } ``` ------ To apply the permission to all KMS keys in a particular trusted AWS account, you can use wildcard characters (\$1) in the Region and key ID positions. For example, the following policy statement allows the principal to call the specified operations on all KMS keys in two trusted example accounts. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:GenerateDataKey", "kms:GenerateDataKeyPair" ], "Resource": [ "arn:aws:kms:*:111122223333:key/*", "arn:aws:kms:*:444455556666:key/*" ] } } ``` ------ You can also use a wildcard character (`"*"`) alone in the `Resource` element. Because it allows access to all KMS keys the account has permission to use, it's recommended primarily for operations without a particular KMS key and for `Deny` statements. You can also use it in policy statements that allow only less sensitive read-only operations. To determine whether an AWS KMS operation involves a particular KMS key, look for the **KMS key** value in the **Resources** column of the table in [AWS KMS permissions](kms-api-permissions-reference.md). For example, the following policy statement uses a `Deny` effect to prohibit the principals from using the specified operations on any KMS key. It uses a wildcard character in the `Resource` element to represent all KMS keys. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Deny", "Action": [ "kms:CreateKey", "kms:PutKeyPolicy", "kms:CreateGrant", "kms:ScheduleKeyDeletion" ], "Resource": "*" } } ``` ------ The following policy statement uses a wildcard character alone to represent all KMS keys. But it allows only less sensitive read-only operations and operations that don't apply to any particular KMS key. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:CreateKey", "kms:ListKeys", "kms:ListAliases", "kms:ListResourceTags" ], "Resource": "*" } } ``` ------ # IAM policy examples In this section, you can find example IAM policies that allow permissions for various AWS KMS actions. **Important** Some of the permissions in the following policies are allowed only when the KMS key's key policy also allows them. For more information, see [Permissions reference](kms-api-permissions-reference.md). For help writing and formatting a JSON policy document, see the [IAM JSON Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the *IAM User Guide*. **Topics** + [ ## Allow a user to view KMS keys in the AWS KMS console ](#iam-policy-example-read-only-console) + [ ## Allow a user to create KMS keys ](#iam-policy-example-create-key) + [ ## Allow a user to encrypt and decrypt with any KMS key in a specific AWS account ](#iam-policy-example-encrypt-decrypt-one-account) + [ ## Allow a user to encrypt and decrypt with any KMS key in a specific AWS account and Region ](#iam-policy-example-encrypt-decrypt-one-account-one-region) + [ ## Allow a user to encrypt and decrypt with specific KMS keys ](#iam-policy-example-encrypt-decrypt-specific-cmks) + [ ## Prevent a user from disabling or deleting any KMS keys ](#iam-policy-example-deny-disable-delete) ## Allow a user to view KMS keys in the AWS KMS console The following IAM policy allows users read-only access to the AWS KMS console. Users with these permissions can view all KMS keys in their AWS account, but they cannot create or change any KMS keys. To view KMS keys on the **AWS managed keys** and **Customer managed keys** pages, principals require [kms:ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html), [kms:ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html), and [tag:GetResources](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html) permissions, even if the keys do not have tags or aliases. The remaining permissions, particularly [kms:DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), are required to view optional KMS key table columns and data on the KMS key detail pages. The [iam:ListUsers](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListUsers.html) and [iam:ListRoles](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListRoles.html) permissions are required to display the key policy in default view without error. To view data on the **Custom key stores** page and details about KMS keys in custom key stores, principals also need [kms:DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) permission. If you limit a user's console access to particular KMS keys, the console displays an error for each KMS key that is not visible. This policy includes of two policy statements. The `Resource` element in the first policy statement allows the specified permissions on all KMS keys in all Regions of the example AWS account. Console viewers don't need additional access because the AWS KMS console displays only KMS keys in the principal's account. This is true even if they have permission to view KMS keys in other AWS accounts. The remaining AWS KMS and IAM permissions require a `"Resource": "*"` element because they don't apply to any particular KMS key. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ReadOnlyAccessForAllKMSKeysInAccount", "Effect": "Allow", "Action": [ "kms:GetPublicKey", "kms:GetKeyRotationStatus", "kms:GetKeyPolicy", "kms:DescribeKey", "kms:ListKeyPolicies", "kms:ListResourceTags", "tag:GetResources" ], "Resource": "arn:aws:kms:*:111122223333:key/*" }, { "Sid": "ReadOnlyAccessForOperationsWithNoKMSKey", "Effect": "Allow", "Action": [ "kms:ListKeys", "kms:ListAliases", "iam:ListRoles", "iam:ListUsers" ], "Resource": "*" } ] } ``` ------ ## Allow a user to create KMS keys The following IAM policy allows a user to create all types of KMS keys. The value of the `Resource` element is `*` because the `CreateKey` operation does not use any particular AWS KMS resources (KMS keys or aliases). To restrict the user to particular types of KMS keys, use the [kms:KeySpec](conditions-kms.md#conditions-kms-key-spec), [kms:KeyUsage](conditions-kms.md#conditions-kms-key-usage), and [kms:KeyOrigin](conditions-kms.md#conditions-kms-key-origin) condition keys. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*" } } ``` ------ Principals who create keys might need some related permissions. + **kms:PutKeyPolicy** — Principals who have `kms:CreateKey` permission can set the initial key policy for the KMS key. However, the `CreateKey` caller must have [kms:PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) permission, which lets them change the KMS key policy, or they must specify the `BypassPolicyLockoutSafetyCheck` parameter of `CreateKey`, which is not recommended. The `CreateKey` caller can get `kms:PutKeyPolicy` permission for the KMS key from an IAM policy or they can include this permission in the key policy of the KMS key that they're creating. + **kms:TagResource** — To add tags to the KMS key during the `CreateKey` operation, the `CreateKey` caller must have [kms:TagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) permission in an IAM policy. Including this permission in the key policy of the new KMS key isn't sufficient. However, if the `CreateKey` caller includes `kms:TagResource` in the initial key policy, they can add tags in a separate call after the KMS key is created. + **kms:CreateAlias** — Principals who create a KMS key in the AWS KMS console must have [kms:CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) permission on the KMS key and on the alias. (The console makes two calls; one to `CreateKey` and one to `CreateAlias`). You must provide the alias permission in an IAM policy. You can provide the KMS key permission in a key policy or IAM policy. For details, see [Controlling access to aliases](alias-access.md). In addition to `kms:CreateKey`, the following IAM policy provides `kms:TagResource` permission on all KMS keys in the AWS account and `kms:CreateAlias` permission on all aliases that the account. It also includes some useful read-only permissions that can be provided only in an IAM policy. This IAM policy does not include `kms:PutKeyPolicy` permission or any other permissions that can be set in a key policy. It's a [best practice](iam-policies-best-practices.md) to set these permissions in the key policy where they apply exclusively to one KMS key. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "IAMPermissionsForParticularKMSKeys", "Effect": "Allow", "Action": "kms:TagResource", "Resource": "arn:aws:kms:*:111122223333:key/*" }, { "Sid": "IAMPermissionsForParticularAliases", "Effect": "Allow", "Action": "kms:CreateAlias", "Resource": "arn:aws:kms:*:111122223333:alias/*" }, { "Sid": "IAMPermissionsForAllKMSKeys", "Effect": "Allow", "Action": [ "kms:CreateKey", "kms:ListKeys", "kms:ListAliases" ], "Resource": "*" } ] } ``` ------ ## Allow a user to encrypt and decrypt with any KMS key in a specific AWS account The following IAM policy allows a user to encrypt and decrypt data with any KMS key in AWS account 111122223333. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": "arn:aws:kms:*:111122223333:key/*" } } ``` ------ ## Allow a user to encrypt and decrypt with any KMS key in a specific AWS account and Region The following IAM policy allows a user to encrypt and decrypt data with any KMS key in AWS account `111122223333` in the US West (Oregon) Region. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/*" ] } } ``` ------ ## Allow a user to encrypt and decrypt with specific KMS keys The following IAM policy allows a user to encrypt and decrypt data with the two KMS keys specified in the `Resource` element. When specifying a KMS key in an IAM policy statement, you must use the [key ARN](concepts.md#key-id-key-ARN) of the KMS key. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/01234abc-d12a-b34c-d56e-f1234567890a'" ] } } ``` ------ ## Prevent a user from disabling or deleting any KMS keys The following IAM policy prevents a user from disabling or deleting any KMS keys, even when another IAM policy or a key policy allows these permissions. A policy that explicitly denies permissions overrides all other policies, even those that explicitly allow the same permissions. For more information, see [Troubleshooting AWS KMS permissions](policy-evaluation.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Deny", "Action": [ "kms:DisableKey", "kms:ScheduleKeyDeletion" ], "Resource": "*" } } ``` ------ # Resource control policies in AWS KMS Resource control policies (RCPs) are a type of organization policy that you can use to enforce preventive controls on AWS resources in your organization. RCPs help you to centrally restrict external access to your AWS resources at scale. RCPs complement service control policies (SCPs). While, SCPs can be used to centrally set the maximum permissions on the IAM roles and users in your organization, RCPs can be used to centrally set the maximum permissions on AWS resources in your organization. You can use RCPs to manage permissions to the customer managed KMS keys in your organization. RCPs alone are not sufficient in granting permissions to your customer managed keys. No permissions are granted by an RCP. An RCP defines a permissions guardrail, or sets limits, on the actions that identities can take on resources in the affected accounts. The administrator must still attach identity-based policies to IAM roles or users, or key policies to actually grant permissions. **Note** Resource control policies in your organization do not apply to [AWS managed keys](concepts.md#aws-managed-key). AWS managed keys are created, managed, and used on your behalf by an AWS service, you cannot change or manage their permissions. **Learn more** + For more general information on RCPs, see [Resource control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*. + For details on how to define RCPs, including examples, see [RCP syntax](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps_syntax.html) in the *AWS Organizations User Guide*. The following example demonstrates how to use an RCP to prevent external principals from accessing customer managed keys in your organization. This policy is just a sample, and you should tailor it to meet your unique business and security needs. For example, you might want to customize your policy to allow access by your business partners. For more details, see the [data perimeter policy examples repository](https://github.com/aws-samples/data-perimeter-policy-examples/tree/main/resource_control_policies). **Note** The `kms:RetireGrant` permission is not effective in an RCP, even if the `Action` element specifies an asterisk (\$1) as a wildcard. For more information on how permission to `kms:RetireGrant` is determined, see [Retiring and revoking grants](grant-delete.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RCPEnforceIdentityPerimeter", "Effect": "Deny", "Principal": "*", "Action": "kms:*", "Resource": "*", "Condition": { "StringNotEqualsIfExists": { "aws:PrincipalOrgID": "my-org-id" }, "Bool": { "aws:PrincipalIsAWSService": "false" } } } ] } ``` ------ The following example RCP requires that AWS service principals can only access your customer managed KMS keys when the request originates from your organization. This policy applies the control only on requests that have `aws:SourceAccount` present. This ensures that service integrations that don't require the use of `aws:SourceAccount` aren't affected. If `aws:SourceAccount` is present in the request context, the `Null` condition evaluates to `true`, causing the `aws:SourceOrgID` key to be enforced. For more information about the confused deputy problem, see [The confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) in the *IAM User Guide*. ``` ``` ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "RCPEnforceConfusedDeputyProtection", "Effect": "Deny", "Principal": "*", "Action": "kms:*", "Resource": "*", "Condition": { "StringNotEqualsIfExists": { "aws:SourceOrgID": "my-org-id" }, "Bool": { "aws:PrincipalIsAWSService": "true" }, "Null": { "aws:SourceAccount": "false" } } } ] } ``` ------ # Grants in AWS KMS A *grant* is a policy instrument that allows [AWS principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) to use 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](key-policies.md) and [IAM policies](iam-policies.md). 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. Grants are commonly used by AWS services that integrate with AWS KMS to encrypt your data at rest. The service creates a grant on behalf of a user in the account, uses its permissions, and retires the grant as soon as its task is complete. For details about how AWS services, use grants, see the *Encryption at rest* topic in the service's user guide or developer guide. Grants are a very flexible and useful access control mechanism. When you create a grant for a KMS key, the grant allows the grantee principal to call the specified grant operations on the KMS key provided that all conditions specified in the grant are met. + Each grant allows access to exactly one KMS key. You can create a grant for a KMS key in a different AWS account. + A grant can allow access to a KMS key, but not deny access. + Each grant has one [grantee principal](#terms-grantee-principal). The grantee principal can represent one or more identities in the same AWS account as the KMS key or in a different account. + A grant can only allow [grant operations](#terms-grant-operations). The grant operations must be supported by the KMS key in the grant. If you specify an unsupported operation, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception. + The grantee principal can use the permissions that the grant gives them without specifying the grant, just as they would if the permissions came from a key policy or IAM policy. However, because the AWS KMS API follows an [eventual consistency](#terms-eventual-consistency) model, when you create, retire, or revoke a grant, there might be a brief delay, before the change is available throughout AWS KMS. To use the permissions in a grant immediately, [use a grant token](using-grant-token.md). + An authorized principal can delete the grant ([retire](#terms-retire-grant) or [revoke](#terms-revoke-grant) it). Deleting a grant eliminates all permissions that the grant allowed. You do not have to figure out which policies to add or remove to undo the grant. + AWS KMS limits the number of grants on each KMS key. For details, see [Grants per KMS key: 50,000](resource-limits.md#grants-per-key). Be cautious when creating grants and when giving others permission to create grants. Permission to create grants has security implications, much like allowing the [kms:PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) permission to set policies. + Users with permission to create grants for a KMS key (`kms:CreateGrant`) can use a grant to allow users and roles, including AWS services, to use the KMS key. The principals can be identities in your own AWS account or identities in a different account or organization. + Grants can allow only a subset of AWS KMS operations. You can use grants to allow principals to view the KMS key, use it in cryptographic operations, and create and retire grants. For details, see [Grant operations](#terms-grant-operations). You can also use [grant constraints](create-grant-overview.md#grant-constraints) to limit the permissions in a grant for a symmetric encryption key. + Principals can get permission to create grants from a key policy or IAM policy. Principals who get `kms:CreateGrant` permission from a policy can create grants for any [grant operation](#terms-grant-operations) on the KMS key. These principals are not required to have the permission that they are granting on the key. When you allow `kms:CreateGrant` permission in a policy, you can use [policy conditions](grant-authorization.md) to limit this permission. + Principals can also get permission to create grants from a grant. These principals can only delegate the permissions that they were granted, even if they have other permissions from a policy. For details, see [Granting CreateGrant permission](create-grant-overview.md#grant-creategrant). ## Grant concepts To use grants effectively, you'll need to understand the terms and concepts that AWS KMS uses. **Grant constraint** A condition that limits the permissions in the grant. Currently, AWS KMS supports grant constraints based on the [encryption context](encrypt_context.md) in the request for a cryptographic operation. For details, see [Using grant constraints](create-grant-overview.md#grant-constraints). **Grant ID** The unique identifier of a grant for a KMS key. You can use a grant ID, along with a [key identifier](concepts.md#key-id), to identify a grant in a [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) or [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) request. **Grant operations** The AWS KMS operations that you can allow in a grant. If you specify other operations, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception. These are also the operations that accept a [grant token](#grant_token). For detailed information about these permissions, see the [AWS KMS permissions](kms-api-permissions-reference.md). These grant operations actually represent permission to use the operation. Therefore, for the `ReEncrypt` operation, you can specify `ReEncryptFrom`, `ReEncryptTo`, or both `ReEncrypt*`. The grant operations are: + Cryptographic operations + [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) + [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) + [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) + [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) + [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) + [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) + [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) + [GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) + [ReEncryptFrom](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) + [ReEncryptTo](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) + [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) + [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) + [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) + Other operations + [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) + [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) + [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) + [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) The grant operations that you allow must be supported by the KMS key in the grant. If you specify an unsupported operation, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception. For example, grants for symmetric encryption KMS keys cannot allow the [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html), [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html), [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) or [https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) operations. Grants for asymmetric KMS keys cannot allow any operations that generate data keys or data key pairs. **Grant token** The AWS KMS API follows an [eventual consistency](#terms-eventual-consistency) model. When you create a grant, there might be a brief delay before the change is available throughout AWS KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. If you try to use a grant before it fully propagates through the system, you might get an access denied error. A grant token lets you refer to the grant and use the grant permissions immediately. A *grant token* is a unique, nonsecret, variable-length, base64-encoded string that represents a grant. You can use the grant token to identify the grant in any [grant operation](#terms-grant-operations). However, because the token value is a hash digest, it doesn't reveal any details about the grant. A grant token is designed to be used only until the grant has fully propagated throughout AWS KMS. After that, the [grantee principal](#terms-grantee-principal) can use the permission in the grant without providing a grant token or any other evidence of the grant. You can use a grant token at any time, but once the grant is eventually consistent, AWS KMS uses the grant to determine permissions, not the grant token. For example, the following command calls the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation. It uses a grant token to represent the grant that gives the caller (the grantee principal) permission to call `GenerateDataKey` on the specified KMS key. ``` $ aws kms generate-data-key \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --key-spec AES_256 \ --grant-token $token ``` You can also use a grant token to identify a grant in operations that manage grants. For example, the [retiring principal](#terms-retiring-principal) can use a grant token in a call to the [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) operation. ``` $ aws kms retire-grant \ --grant-token $token ``` `CreateGrant` is the only operation that returns a grant token. You cannot get a grant token from any other AWS KMS operation or from the [CloudTrail log event](ct-creategrant.md) for the CreateGrant operation. The [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) and [ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html) operations return the [grant ID](#terms-grant-id), but not a grant token. For details, see [Using a grant token](using-grant-token.md). **Grantee principal** The identities that get the permissions specified in the grant. Each grant has one grantee principal, but the grantee principal can represent multiple identities. The grantee principal can be any AWS principal, including an AWS account (root), an [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html), an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), a [federated role or user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html), or an assumed role user. The grantee principal can be in the same account as the KMS key or a different account. However, the grantee principal cannot be a [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), an [IAM group](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html), or an [AWS organization](https://docs.aws.amazon.com/organizations/latest/userguide/). IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. **Retire (a grant)** Terminates a grant. You retire a grant when you finish using the permissions. Revoking and retiring a grant both delete the grant. But retiring is done by a principal specified in the grant. Revoking is typically done by a key administrator. For details, see [Retiring and revoking grants](grant-delete.md). **Retiring principal** A principal who can [retire a grant](#terms-retire-grant). You can specify a retiring principal in a grant, but it is not required. The retiring principal can be any AWS principal, including AWS accounts, IAM users, IAM roles, federated users, and assumed role users. The retiring principal can be in the same account as the KMS key or a different account. IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. In addition to retiring principal specified in the grant, a grant can be retired by the AWS account in which the grant was created. If the grant allows the `RetireGrant` operation, the [grantee principal](#terms-grantee-principal) can retire the grant. Also, the AWS account or an AWS account that is the retiring principal can delegate the permission to retire a grant to an IAM principal in the same AWS account. For details, see [Retiring and revoking grants](grant-delete.md). **Revoke (a grant)** Terminates a grant. You revoke a grant to actively deny the permissions that the grant allows. Revoking and retiring a grant both delete the grant. But retiring is done by a principal specified in the grant. Revoking is typically done by a key administrator. For details, see [Retiring and revoking grants](grant-delete.md). **Eventual consistency (for grants)** The AWS KMS API follows an [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency) model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout AWS KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. You might become aware of this brief delay if you get unexpected errors. For example, If you try to manage a new grant or use the permissions in a new grant before the grant is known throughout AWS KMS, you might get an access denied error. If you retire or revoke a grant, the grantee principal might still be able to use its permissions for a brief period until the grant is fully deleted. The typical strategy is to retry the request, and some AWS SDKs include automatic backoff and retry logic. AWS KMS has features to mitigate this brief delay. + To use the permissions in a new grant immediately, use a [grant token](using-grant-token.md). You can use a grant token to refer to a grant in any [grant operation](#terms-grant-operations). For instructions, see [Using a grant token](using-grant-token.md). + The [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation has a `Name` parameter that prevents retry operations from creating duplicate grants. Grant tokens supersede the validity of the grant until all endpoints in the service have been updated with the new grant state. In most cases, eventual consistency will be achieved within five minutes. For more information, see [AWS KMS eventual consistency](accessing-kms.md#programming-eventual-consistency). # Best practices for AWS KMS grants AWS KMS recommends the following best practices when creating, using, and managing grants. + Limit the permissions in the grant to those that the grantee principal requires. Use the principle of [least privileged access](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). + Use a specific grantee principal, such as an IAM role, and give the grantee principal permission to use only the API operations that they require. + Use the encryption context [grant constraints](grants.md#terms-grant-constraint) to ensure that callers are using the KMS key for the intended purpose. For details about how to use the encryption context in a request to secure your data, see [How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext](https://aws.amazon.com/blogs/security/how-to-protect-the-integrity-of-your-encrypted-data-by-using-aws-key-management-service-and-encryptioncontext/) in the *AWS Security Blog*. **Tip** Use the [EncryptionContextEqual](create-grant-overview.md#grant-constraints) grant constraint whenever possible. The [EncryptionContextSubset](create-grant-overview.md#grant-constraints) grant constraint is more difficult to use correctly. If you need to use it, read the documentation carefully and test the grant constraint to make sure it works as intended. + Delete duplicate grants. Duplicate grants have the same key ARN, API actions, grantee principal, encryption context, and name. If you retire or revoke the original grant but leave the duplicates, the leftover duplicate grants constitute unintended escalations of privilege. To avoid duplicating grants when retrying a `CreateGrant` request, use the [`Name` parameter](create-grant-overview.md#grant-create). To detect duplicate grants, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation. If you accidentally create a duplicate grant, retire or revoke it as soon as possible. **Note** Grants for [AWS managed keys](concepts.md#aws-managed-key) might look like duplicates but have different grantee principals. The `GranteePrincipal` field in the `ListGrants` response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the `GranteePrincipal` field contains the [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), which might represent several different grantee principals. + Remember that grants do not automatically expire. [Retire or revoke the grant](grant-delete.md) as soon as the permission is no longer needed. Grants that are not deleted might create a security risk for encrypted resources. # Controlling access to grants You can control access to the operations that create and manage grants in key policies, IAM policies, and in grants. Principals who get `CreateGrant` permission from a grant have [more limited grant permissions](create-grant-overview.md#grant-creategrant). | API operation | Key policy or IAM policy | Grant | | --- | --- | --- | | CreateGrant | ✓ | ✓ | | ListGrants | ✓ | - | | ListRetirableGrants | ✓ | - | | Retire Grants | (Limited. See [Retiring and revoking grants](grant-delete.md)) | ✓ | | RevokeGrant | ✓ | - | When you use a key policy or IAM policy to control access to operations that create and manage grants, you can use one or more of the following policy conditions to limit the permission. AWS KMS supports all of the following grant-related condition keys. For detailed information and examples, see [AWS KMS condition keys](conditions-kms.md). [kms:GrantConstraintType](conditions-kms.md#conditions-kms-grant-constraint-type) Allows principals to create a grant only when the grant includes the specified [grant constraint](create-grant-overview.md#grant-constraints). [kms:GrantIsForAWSResource](conditions-kms.md#conditions-kms-grant-is-for-aws-resource) Allows principals to call `CreateGrant`, `ListGrants`, or `RevokeGrant` only when [an AWS service that is integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration) sends the request on the principal's behalf. [kms:GrantOperations](conditions-kms.md#conditions-kms-grant-operations) Allows principals to create a grant, but limits the grant to the specified operations. [kms:GranteePrincipal](conditions-kms.md#conditions-kms-grantee-principal) Allows principals to create a grant only for the specified [grantee principal](grants.md#terms-grantee-principal). [kms:RetiringPrincipal](conditions-kms.md#conditions-kms-retiring-principal) Allows principals to create a grant only when the grant specifies a particular [retiring principal](grants.md#terms-retiring-principal). # Creating grants Before creating a grant, learn about the options for customizing your grant. You can use *grant constraints* to limit the permissions in the grant. Also, learn about granting `CreateGrant` permission. Principals who get permission to create grants from a grant are limited in the grants that they can create. **Topics** + [ ## Creating a grant ](#grant-create) + [ ## Granting CreateGrant permission ](#grant-creategrant) ## Creating a grant To create a grant, call the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. Specify a KMS key, a [grantee principal](grants.md#terms-grantee-principal), and a list of allowed [grant operations](grants.md#terms-grant-operations). You can also designate an optional [retiring principal](grants.md#terms-retiring-principal). To customize the grant, use optional `Constraints` parameters to define [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html). When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, before the change is available throughout AWS KMS. For more information, see [Eventual consistency (for grants)](grants.md#terms-eventual-consistency). For example, the following `CreateGrant` command creates a grant that allows users who are authorized to assume the `keyUserRole` role to call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation on the specified [symmetric KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks). The grant uses the `RetiringPrincipal` parameter to designate a principal that can retire the grant. It also includes a grant constraint that allows the permission only when the [encryption context](encrypt_context.md) in the request includes `"Department": "IT"`. ``` $ aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --retiring-principal arn:aws:iam::111122223333:role/adminRole \ --constraints EncryptionContextSubset={Department=IT} ``` If your code retries the `CreateGrant` operation, or uses an [AWS SDK that automatically retries requests](https://docs.aws.amazon.com/general/latest/gr/api-retries.html), use the optional [Name](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-Name) parameter to prevent the creation of duplicate grants. If AWS KMS gets a `CreateGrant` request for a grant with the same properties as an existing grant, including the name, it recognizes the request as a retry, and does not create a new grant. You cannot use the `Name` value to identify the grant in any AWS KMS operations. **Important** Do not include confidential or sensitive information in the grant name. It may appear in plain text in CloudTrail logs and other output. ``` $ aws kms create-grant \ --name IT-1234abcd-keyUserRole-decrypt \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --retiring-principal arn:aws:iam::111122223333:role/adminRole \ --constraints EncryptionContextSubset={Department=IT} ``` For code examples that demonstrate how to create grants in several programming languages, see [Use `CreateGrant` with an AWS SDK or CLI](example_kms_CreateGrant_section.md). ### Using grant constraints [Grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) set conditions on the permissions that the grant gives to the grantee principal. Grant constraints take the place of [condition keys](policy-conditions.md) in a [key policy](key-policies.md) or [IAM policy](iam-policies.md). Each grant constraint value can include up to 8 encryption context pairs. The encryption context value in each grant constraint cannot exceed 384 characters. **Important** Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output. AWS KMS supports two grant constraints, `EncryptionContextEquals` and `EncryptionContextSubset`, both of which establish requirements for the [encryption context](encrypt_context.md) in a request for a cryptographic operation. The encryption context grant constraints are designed to be used with [grant operations](grants.md#terms-grant-operations) that have an encryption context parameter. + Encryption context constraints are valid only in a grant for a symmetric encryption KMS key. Cryptographic operations with other KMS keys don't support an encryption context. + The encryption context constraint is ignored for `DescribeKey` and `RetireGrant` operations. `DescribeKey` and `RetireGrant` don't have an encryption context parameter, but you can include these operations in a grant that has an encryption context constraint. + You can use an encryption context constraint in a grant for the `CreateGrant` operation. The encryption context constraint requires that any grants created with the `CreateGrant` permission have an equally strict or stricter encryption context constraint. AWS KMS supports the following encryption context grant constraints. **EncryptionContextEquals** Use `EncryptionContextEquals` to specify the exact encryption context for permitted requests. `EncryptionContextEquals` requires that the encryption context pairs in the request are an exact, case-sensitive match for the encryption context pairs in the grant constraint. The pairs can appear in any order, but the keys and values in each pair cannot vary. For example, if the `EncryptionContextEquals` grant constraint requires the `"Department": "IT"` encryption context pair, the grant allows requests of the specified type only when the encryption context in the request is exactly `"Department": "IT"`. **EncryptionContextSubset** Use `EncryptionContextSubset` to require that requests include particular encryption context pairs. `EncryptionContextSubset` requires that the request include all encryption context pairs in the grant constraint (an exact, case-sensitive match), but the request can also have additional encryption context pairs. The pairs can appear in any order, but the keys and values in each pair cannot vary. For example, if the `EncryptionContextSubset` grant constraint requires the `Department=IT` encryption context pair, the grant allows requests of the specified type when the encryption context in the request is `"Department": "IT"`, or includes `"Department": "IT"` along with other encryption context pairs, such as `"Department": "IT","Purpose": "Test"`. To specify an encryption context constraint in a grant for a symmetric encryption KMS key, use the `Constraints` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. The grant that this command creates gives users who are authorized to assume the `keyUserRole` role permission to call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. But that permission is effective only when the encryption context in the `Decrypt` request is a `"Department": "IT"` encryption context pair. ``` $ aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --retiring-principal arn:aws:iam::111122223333:role/adminRole \ --constraints EncryptionContextEquals={Department=IT} ``` The resulting grant looks like the following one. Notice that the permission granted to the `keyUserRole` role is effective only when the `Decrypt` request uses the same encryption context pair specified in the grant constraint. To find the grants on a KMS key, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation. ``` $ aws kms list-grants --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "Grants": [ { "Name": "", "IssuingAccount": "arn:aws:iam::111122223333:root", "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a", "Operations": [ "Decrypt" ], "GranteePrincipal": "arn:aws:iam::111122223333:role/keyUserRole", "Constraints": { "EncryptionContextEquals": { "Department": "IT" } }, "CreationDate": 1568565290.0, "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "RetiringPrincipal": "arn:aws:iam::111122223333:role/adminRole" } ] } ``` To satisfy the `EncryptionContextEquals` grant constraint, the encryption context in the request for the `Decrypt` operation must be a `"Department": "IT"` pair. A request like the following from the grantee principal would satisfy the `EncryptionContextEquals` grant constraint. ``` $ aws kms decrypt \ --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\ --ciphertext-blob fileb://encrypted_msg \ --encryption-context Department=IT ``` When the grant constraint is `EncryptionContextSubset`, the encryption context pairs in the request must include the encryption context pairs in the grant constraint, but the request can also include other encryption context pairs. The following grant constraint requires that one of encryption context pairs in the request is `"Deparment": "IT"`. ``` "Constraints": { "EncryptionContextSubset": { "Department": "IT" } } ``` The following request from the grantee principal would satisfy both of the `EncryptionContextEqual` and `EncryptionContextSubset` grant constraints in this example. ``` $ aws kms decrypt \ --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --ciphertext-blob fileb://encrypted_msg \ --encryption-context Department=IT ``` However, a request like the following from the grantee principal would satisfy the `EncryptionContextSubset` grant constraint, but it would fail the `EncryptionContextEquals` grant constraint. ``` $ aws kms decrypt \ --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --ciphertext-blob fileb://encrypted_msg \ --encryption-context Department=IT,Purpose=Test ``` AWS services often use encryption context constraints in the grants that give them permission to use KMS keys in your AWS account. For example, Amazon DynamoDB uses a grant like the following one to get permission to use the [AWS managed key](concepts.md#aws-managed-key) for DynamoDB in your account. The `EncryptionContextSubset` grant constraint in this grant makes the permissions in the grant effective only when the encryption context in the request includes `"subscriberID": "111122223333"` and `"tableName": "Services"` pairs. This grant constraint means that the grant allows DynamoDB to use the specified KMS key only for a particular table in your AWS account. To get this output, run the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation on the AWS managed key for DynamoDB in your account. ``` $ aws kms list-grants --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 { "Grants": [ { "Operations": [ "Decrypt", "Encrypt", "GenerateDataKey", "ReEncryptFrom", "ReEncryptTo", "RetireGrant", "DescribeKey" ], "IssuingAccount": "arn:aws:iam::111122223333:root", "Constraints": { "EncryptionContextSubset": { "aws:dynamodb:tableName": "Services", "aws:dynamodb:subscriberId": "111122223333" } }, "CreationDate": 1518567315.0, "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", "GranteePrincipal": "dynamodb.us-west-2.amazonaws.com", "RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com", "Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a", "GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59" } ] } ``` ## Granting CreateGrant permission A grant can include permission to call the `CreateGrant` operation. But when a [grantee principal](grants.md#terms-grantee-principal) gets permission to call `CreateGrant` from a grant, rather than from a policy, that permission is limited. + The grantee principal can only create grants that allow some or all of the operations in the parent grant. + The [grant constraints](#grant-constraints) in the grants they create must be at least as strict as those in the parent grant. These limitations don't apply to principals who get `CreateGrant` permission from a policy, although their permissions can be limited by [policy conditions](grant-authorization.md). For example, consider a grant that allows the grantee principal to call the `GenerateDataKey`, `Decrypt`, and `CreateGrant` operations. We call a grant that allow `CreateGrant` permission a *parent grant*. ``` # The original grant in a ListGrants response. { "Grants": [ { "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1572216195.0, "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a", "Operations": [ "GenerateDataKey", "Decrypt", "CreateGrant ] "RetiringPrincipal": "arn:aws:iam::111122223333:role/adminRole", "Name": "", "IssuingAccount": "arn:aws:iam::111122223333:root", "GranteePrincipal": "arn:aws:iam::111122223333:role/keyUserRole", "Constraints": { "EncryptionContextSubset": { "Department": "IT" } }, } ] } ``` The grantee principal, exampleUser, can use this permission to create a grant that includes any subset of the operations specified in the original grant, such as `CreateGrant` and `Decrypt`. The *child grant* cannot include other operations, such as `ScheduleKeyDeletion` or `ReEncrypt`. Also, the [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) in child grants must be as restrictive or more restrictive than those in the parent grant. For example, the child grant can add pairs to an `EncryptionContextSubset` constraint in the parent grant, but it cannot remove them. The child grant can change an `EncryptionContextSubset` constraint to an `EncryptionContextEquals` constraint, but not the reverse. IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. For example, the grantee principal can use the `CreateGrant` permission that it got from the parent grant to create the following child grant. The operations in the child grant are a subset of the operations in the parent grant and the grant constraints are more restrictive. ``` # The child grant in a ListGrants response. { "Grants": [ { "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1572249600.0, "GrantId": "fedcba9999c1e2e9876abcde6e9d6c9b6a1987650000abcee009abcdef40183f", "Operations": [ "CreateGrant" "Decrypt" ] "RetiringPrincipal": "arn:aws:iam::111122223333:user/exampleUser", "Name": "", "IssuingAccount": "arn:aws:iam::111122223333:root", "GranteePrincipal": "arn:aws:iam::111122223333:user/anotherUser", "Constraints": { "EncryptionContextEquals": { "Department": "IT" } }, } ] } ``` The grantee principal in the child grant, `anotherUser`, can use their `CreateGrant` permission to create grants. However, the grants that `anotherUser` creates must include the operations in its parent grant or a subset, and the grant constraints must be the same or stricter. # Viewing grants To view the grant, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation. You must specify the KMS key to which the grants apply. You can also filter the grant list by grant ID or grantee principal. For more examples, see [Use `ListGrants` with an AWS SDK or CLI](example_kms_ListGrants_section.md). To view all grants in the AWS account and Region with a particular [retiring principal](grants.md#terms-retiring-principal), use [ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html). The responses include details about each grant. **Note** The `GranteePrincipal` field in the `ListGrants` response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the `GranteePrincipal` field contains the [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), which might represent several different grantee principals. For example, the following command lists all of the grants for a KMS key. ``` $ aws kms list-grants --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "Grants": [ { "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1572216195.0, "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a", "Constraints": { "EncryptionContextSubset": { "Department": "IT" } }, "RetiringPrincipal": "arn:aws:iam::111122223333:role/adminRole", "Name": "", "IssuingAccount": "arn:aws:iam::111122223333:root", "GranteePrincipal": "arn:aws:iam::111122223333:user/exampleUser", "Operations": [ "Decrypt" ] } ] } ``` # Using a grant token The AWS KMS API follows an [eventual consistency](grants.md#terms-eventual-consistency) model. When you create a grant, the grant might not be effective immediately. There might be a brief delay before the change is available throughout AWS KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. Once the change has fully propagated throughout the system, the grantee principal can use the permissions in the grant without specifying the grant token or any evidence of the grant. However, if a grant that is so new that it is not yet known to all of AWS KMS, the request might fail with an `AccessDeniedException` error. To use the permissions in a new grant immediately, use the [grant token](grants.md#grant_token) for the grant. Save the grant token that the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation returns. Then submit the grant token in the request for the AWS KMS operation. You can submit a grant token to any AWS KMS [grant operation](grants.md#terms-grant-operations) and you can submit multiple grant tokens in the same request. The following example uses the `CreateGrant` operation to create a grant that allows the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) and [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operations. It saves the grant token that `CreateGrant` returns in the `token` variable. Then, in a call to the `GenerateDataKey` operation, it uses the grant token in the `token` variable. ``` # Create a grant; save the grant token $ token=$(aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:user/appUser \ --retiring-principal arn:aws:iam::111122223333:user/acctAdmin \ --operations GenerateDataKey Decrypt \ --query GrantToken \ --output text) # Use the grant token in a request $ aws kms generate-data-key \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ –-key-spec AES_256 \ --grant-tokens $token ``` Principals with permission can also use a grant token to retire a new grant even before the grant is available throughout AWS KMS. (The `RevokeGrant` operation doesn't accept a grant token.) For details, see [Retiring and revoking grants](grant-delete.md). ``` # Retire the grant $ aws kms retire-grant --grant-token $token ``` # Retiring and revoking grants To delete a grant, retire or revoke it. The [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) and [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) operations are very similar to each other. Both operations delete a grant, which eliminates the permissions the grant allows. The primary difference between these operations is how they are authorized. **RevokeGrant** Like most AWS KMS operations, access to the `RevokeGrant` operation is controlled through [key policies](key-policies.md) and [IAM policies](iam-policies.md). The [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) API can be called by any principal with `kms:RevokeGrant` permission. This permission is included in the standard permissions given to key administrators. Typically, administrators revoke a grant to deny permissions the grant allows. **RetireGrant** The grant determines who can retire it. This design allows you to control the lifecycle of a grant without changing key policies or IAM policies. Typically, you retire a grant when you are done using its permissions. A grant can be retired by an optional [retiring principal](grants.md#terms-retiring-principal) specified in the grant. The [grantee principal](grants.md#terms-grantee-principal) can also retire the grant, but only if they are also a retiring principal or the grant includes the `RetireGrant` operation. As a backup, the AWS account in which the grant was created can retire the grant. There is a `kms:RetireGrant` permission that can be used in IAM policies, but it has limited utility. Principals specified in the grant can retire a grant without the `kms:RetireGrant` permission. The `kms:RetireGrant` permission alone does not allow principals to retire a grant. The `kms:RetireGrant` permission is not effective in a [key policy](key-policies.md) or [resource control policy](resource-control-policies.md). + To deny permission to retire a grant, you can use a `Deny` action with the `kms:RetireGrant` permission in your IAM policies. + The AWS account that owns the KMS key can delegate the `kms:RetireGrant` permission to an IAM principal in the account. + If the retiring principal is a different AWS account, administrators in the other account can use `kms:RetireGrant` to delegate permission to retire the grant to an IAM principal in that account. The AWS KMS API follows an [eventual consistency](grants.md#terms-eventual-consistency) model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout AWS KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. If you need to delete a new grant immediately, before it is available throughout AWS KMS, [use a grant token](using-grant-token.md) to retire the grant. You cannot use a grant token to revoke a grant. # Condition keys for AWS KMS You can specify conditions in the [key policies](key-policies.md) and [IAM policies](iam-policies.md) that control access to AWS KMS resources. The policy statement is effective only when the conditions are true. For example, you might want a policy statement to take effect only after a specific date. Or, you might want a policy statement to control access only when a specific value appears in an API request. To specify conditions, you use *condition keys* in the [`Condition` element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy statement with [IAM condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html). Some condition keys apply generally to AWS; others are specific to AWS KMS. Condition key values must adhere to the character and encoding rules for AWS KMS key policies and IAM policies. For details about key policy document rules, see [Key policy format](key-policy-overview.md#key-policy-format). For details about IAM policy document rules, see [IAM name requirements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-names) in the *IAM User Guide*.. **Topics** + [ # AWS global condition keys ](conditions-aws.md) + [ # AWS KMS condition keys ](conditions-kms.md) + [ # AWS KMS condition keys for attested platforms ](conditions-attestation.md) # AWS global condition keys AWS defines [global condition keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#AvailableKeys), a set of policy conditions keys for all AWS services that use IAM for access control. AWS KMS supports all global condition keys. You can use them in AWS KMS key policies and IAM policies. For example, you can use the [aws:PrincipalArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalarn) global condition key to allow access to an AWS KMS key (KMS key) only when the principal in the request is represented by the Amazon Resource Name (ARN) in the condition key value. To support [attribute-based access control](abac.md) (ABAC) in AWS KMS, you can use the [aws:ResourceTag/*tag-key*](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag) global condition key in an IAM policy to allow access to KMS keys with a particular tag. To help prevent an AWS service from being used as a confused deputy in a policy where the principal is an [AWS service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), you can use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) or [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition keys. For details, see [Using `aws:SourceArn` or `aws:SourceAccount` condition keys](least-privilege.md#least-privilege-source-arn). For information about AWS global condition keys, including the types of requests in which they are available, see [AWS Global Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*. For examples of using global condition keys in IAM policies, see [Controlling Access to Requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-requests) and [Controlling Tag Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys) in the *IAM User Guide*. The following topics provide special guidance for using condition keys based on IP addresses and VPC endpoints. **Topics** + [ ## Using the IP address condition in policies with AWS KMS permissions ](#conditions-aws-ip-address) + [ ## Using VPC endpoint conditions in policies with AWS KMS permissions ](#conditions-aws-vpce) + [ ## Using IPv6 addresses in IAM and AWS KMS key policies ](#KMS-IPv6-policies) ## Using the IP address condition in policies with AWS KMS permissions You can use AWS KMS to protect your data in an [integrated AWS service](service-integration.md). But use caution when specifying the [IP address condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_IPAddress) or the `aws:SourceIp` condition key in the same policy statement that allows or denies access to AWS KMS. For example, the policy in [AWS: Denies Access to AWS Based on the Source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html) restricts AWS actions to requests from the specified IP range. Consider this scenario: 1. You attach a policy like the one shown at [AWS: Denies Access to AWS Based on the Source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html) to an IAM identity. You set the value of the `aws:SourceIp` condition key to the range of IP addresses for the user's company. This IAM identity has other policies attached that allow it to use Amazon EBS, Amazon EC2, and AWS KMS. 1. The identity attempts to attach an encrypted EBS volume to an EC2 instance. This action fails with an authorization error even though the user has permission to use all the relevant services. Step 2 fails because the request to AWS KMS to decrypt the volume's encrypted data key comes from an IP address that is associated with the Amazon EC2 infrastructure. To succeed, the request must come from the IP address of the originating user. Because the policy in step 1 explicitly denies all requests from IP addresses other than those specified, Amazon EC2 is denied permission to decrypt the EBS volume's encrypted data key. Also, the `aws:SourceIP` condition key is not effective when the request comes from an [Amazon VPC endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html). To restrict requests to a VPC endpoint, including an [AWS KMS VPC endpoint](kms-vpc-endpoint.md), use the `aws:SourceVpce` or `aws:SourceVpc` condition keys. For more information, see [VPC Endpoints - Controlling the Use of Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html#vpc-endpoints-iam-access) in the *Amazon VPC User Guide*. ## Using VPC endpoint conditions in policies with AWS KMS permissions [AWS KMS supports Amazon Virtual Private Cloud (Amazon VPC) endpoints](kms-vpc-endpoint.md) that are powered by [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html#what-is-privatelink). You can use the following [global condition keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#AvailableKeys) in key policies and IAM policies to control access to AWS KMS resources when the request comes from a VPC or uses a VPC endpoint. For details, see [Use VPC endpoints to control access to AWS KMS resources](vpce-policy-condition.md). + `aws:SourceVpc` limits access to requests from the specified VPC. + `aws:SourceVpce` limits access to requests from the specified VPC endpoint. If you use these condition keys to control access to KMS keys, you might inadvertently deny access to AWS services that use AWS KMS on your behalf. Take care to avoid a situation like the [IP address condition keys](#conditions-aws-ip-address) example. If you restrict requests for a KMS key to a VPC or VPC endpoint, calls to AWS KMS from an integrated service, such as Amazon S3 or Amazon EBS, might fail. This can happen even if the source request ultimately originates in the VPC or from the VPC endpoint. ## Using IPv6 addresses in IAM and AWS KMS key policies Before trying to access AWS KMS over IPv6, ensure any key and IAM policies containing IP address restrictions are updated to include IPv6 address ranges. IP based policies that are not updated to handle IPv6 addresses may result in clients incorrectly losing or gaining access when they start using IPv6. For general guidance on KMS access controls, see [KMS key access and permissions](control-access.md). To learn about KMS and dual stack support, see [Dual-stack endpoint support](ipv6-kms.md). **Important** These statements do not allow any actions. Use these statements in combination with other statements that allow specific actions. The following statement explicitly denies access to all KMS permissions for requests originating from the `192.0.2.*` range of IPv4 addresses. Any IP addresses outside of this range are not explicitly denied KMS permissions. Since all IPv6 addresses are outside of the denied range, this statement does not explicitly deny KMS permissions for any IPv6 addresses. ``` { "Sid": "DenyKMSPermissions", "Effect": "Deny", "Action": [ "kms:*" ], "Resource": "*", "Condition": { "NotIpAddress": { "aws:SourceIp": [ "192.0.2.0/24" ] } } } ``` You can modify the `Condition` element to deny both IPv4 (`192.0.2.0/24`) and IPv6 (`2001:db8:1234::/32`) address ranges as shown in the following example. ``` { "Sid": "DenyKMSPermissions", "Effect": "Deny", "Action": [ "kms:*" ], "Resource": "*", "Condition": { "NotIpAddress": { "aws:SourceIp": [ "192.0.2.0/24", "2001:db8:1234::/32" ] } } } ``` # AWS KMS condition keys AWS KMS provides a set of condition keys that you can use in key policies and IAM policies. These condition keys are specific to AWS KMS. For example, you can use the `kms:EncryptionContext:context-key` condition key to require a particular [encryption context](encrypt_context.md) when controlling access to a symmetric encryption KMS key. **Conditions for an API operation request** Many AWS KMS condition keys control access to a KMS key based on the value of a parameter in the request for an AWS KMS operation. For example, you can use the [kms:KeySpec](#conditions-kms-key-spec) condition key in an IAM policy to allow use of the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation only when the value of the `KeySpec` parameter in the `CreateKey` request is `RSA_4096`. This type of condition works even when the parameter doesn't appear in the request, such as when you use the parameter's default value. For example you can use the [kms:KeySpec](#conditions-kms-key-spec) condition key to allow users to use the `CreateKey` operation only when the value of the `KeySpec` parameter is `SYMMETRIC_DEFAULT`, which is the default value. This condition allows requests that have the `KeySpec` parameter with the `SYMMETRIC_DEFAULT` value and requests that have no `KeySpec` parameter. **Conditions for KMS keys used in API operations** Some AWS KMS condition keys can control access to operations based on a property of the KMS key that is used in the operation. For example, you can use the [kms:KeyOrigin](#conditions-kms-key-origin) condition to allow principals to call [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) on a KMS key only when the `Origin` of the KMS key is `AWS_KMS`. To find out if a condition key can be used in this way, see the description of the condition key. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. If you use this type of condition key with an operation that is not authorized for a particular KMS key resource, like [ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html), the permission is not effective because the condition can never be satisfied. There is no KMS key resource involved in authorizing the `ListKeys` operation and no `KeySpec` property. The following topics describe each AWS KMS condition key and include example policy statements that demonstrate policy syntax. **Using set operators with condition keys** When a policy condition compares two set of values, such as the set of tags in a request and the set of tags in a policy, you need tell AWS how to compare the sets. IAM defines two set operators, `ForAnyValue` and `ForAllValues`, for this purpose. Use set operators only with *multi-valued condition keys*, which require them. Do not use set operators with *single-valued condition keys*. As always, test your policy statements thoroughly before using them in a production environment. Condition keys are single-valued or multi-valued. To determine whether an AWS KMS condition key is single-valued or multi-valued, see the **Value type** column in the condition key description. + *Single-valued * condition keys have at most one value in the authorization context (the request or resource). For example, because each API call can originate from only one AWS account, [kms:CallerAccount](#conditions-kms-caller-account) is a single valued condition key. Do not use a set operator with a single-valued condition key. + *Multi-valued* condition keys have multiple values in the authorization context (the request or resource). For example, because each KMS key can have multiple aliases, [kms:ResourceAliases](#conditions-kms-resource-aliases) can have multiple values. Multi-valued condition keys require a set operator. Note that the difference between single-valued and multi-valued condition keys depends on the number of values in the authorization context; not the number of values in the policy condition. **Warning** Using a set operator with a single-valued condition key can create a policy statement that is overly permissive (or overly restrictive). Use set operators only with multi-valued condition keys. If you create or update a policy that includes a `ForAllValues` set operator with the kms:EncryptionContext:*context-key* or `aws:RequestTag/tag-key` condition keys, AWS KMS returns the following error message: `OverlyPermissiveCondition: Using the ForAllValues set operator with a single-valued condition key matches requests without the specified [encryption context or tag] or with an unspecified [encryption context or tag]. To fix, remove ForAllValues.` For detailed information about the `ForAnyValue` and `ForAllValues` set operators, see [Using multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the *IAM User Guide*. For information about the risk of using the `ForAllValues` set operator with a single-valued condition, see [Security Warning – ForAllValues with single valued key](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-reference-policy-checks.html#access-analyzer-reference-policy-checks-security-warning-forallvalues-with-single-valued-key) in the *IAM User Guide*. **Topics** + [ ## kms:BypassPolicyLockoutSafetyCheck ](#conditions-kms-bypass-policy-lockout-safety-check) + [ ## kms:CallerAccount ](#conditions-kms-caller-account) + [ ## kms:CustomerMasterKeySpec (deprecated) ](#conditions-kms-key-spec-replaced) + [ ## kms:CustomerMasterKeyUsage (deprecated) ](#conditions-kms-key-usage-replaced) + [ ## kms:DataKeyPairSpec ](#conditions-kms-data-key-spec) + [ ## kms:EncryptionAlgorithm ](#conditions-kms-encryption-algorithm) + [ ## kms:EncryptionContext:*context-key* ](#conditions-kms-encryption-context) + [ ## kms:EncryptionContextKeys ](#conditions-kms-encryption-context-keys) + [ ## kms:ExpirationModel ](#conditions-kms-expiration-model) + [ ## kms:GrantConstraintType ](#conditions-kms-grant-constraint-type) + [ ## kms:GrantIsForAWSResource ](#conditions-kms-grant-is-for-aws-resource) + [ ## kms:GrantOperations ](#conditions-kms-grant-operations) + [ ## kms:GranteePrincipal ](#conditions-kms-grantee-principal) + [ ## kms:KeyAgreementAlgorithm ](#conditions-kms-key-agreement-algorithm) + [ ## kms:KeyOrigin ](#conditions-kms-key-origin) + [ ## kms:KeySpec ](#conditions-kms-key-spec) + [ ## kms:KeyUsage ](#conditions-kms-key-usage) + [ ## kms:MacAlgorithm ](#conditions-kms-mac-algorithm) + [ ## kms:MessageType ](#conditions-kms-message-type) + [ ## kms:MultiRegion ](#conditions-kms-multiregion) + [ ## kms:MultiRegionKeyType ](#conditions-kms-multiregion-key-type) + [ ## kms:PrimaryRegion ](#conditions-kms-primary-region) + [ ## kms:ReEncryptOnSameKey ](#conditions-kms-reencrypt-on-same-key) + [ ## kms:RequestAlias ](#conditions-kms-request-alias) + [ ## kms:ResourceAliases ](#conditions-kms-resource-aliases) + [ ## kms:ReplicaRegion ](#conditions-kms-replica-region) + [ ## kms:RetiringPrincipal ](#conditions-kms-retiring-principal) + [ ## kms:RotationPeriodInDays ](#conditions-kms-rotation-period-in-days) + [ ## kms:ScheduleKeyDeletionPendingWindowInDays ](#conditions-kms-schedule-key-deletion-pending-window-in-days) + [ ## kms:SigningAlgorithm ](#conditions-kms-signing-algorithm) + [ ## kms:ValidTo ](#conditions-kms-valid-to) + [ ## kms:ViaService ](#conditions-kms-via-service) + [ ## kms:WrappingAlgorithm ](#conditions-kms-wrapping-algorithm) + [ ## kms:WrappingKeySpec ](#conditions-kms-wrapping-key-spec) ## kms:BypassPolicyLockoutSafetyCheck | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:BypassPolicyLockoutSafetyCheck` | Boolean | Single-valued | `CreateKey` `PutKeyPolicy` | IAM policies only Key policies and IAM policies | The `kms:BypassPolicyLockoutSafetyCheck` condition key controls access to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) and [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operations based on the value of the `BypassPolicyLockoutSafetyCheck` parameter in the request. The following example IAM policy statement prevents users from bypassing the policy lockout safety check by denying them permission to create KMS keys when the value of the `BypassPolicyLockoutSafetyCheck` parameter in the `CreateKey` request is `true.` ``` { "Effect": "Deny", "Action": [ "kms:CreateKey", "kms:PutKeyPolicy" ], "Resource": "*", "Condition": { "Bool": { "kms:BypassPolicyLockoutSafetyCheck": true } } } ``` You can also use the `kms:BypassPolicyLockoutSafetyCheck` condition key in an IAM policy or key policy to control access to the `PutKeyPolicy` operation. The following example policy statement from a key policy prevents users from bypassing the policy lockout safety check when changing the policy of a KMS key. Instead of using an explicit `Deny`, this policy statement uses `Allow` with the [Null condition operator](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_Null) to allow access only when the request does not include the `BypassPolicyLockoutSafetyCheck` parameter. When the parameter is not used, the default value is `false`. This slightly weaker policy statement can be overridden in the rare case that a bypass is necessary. ``` { "Effect": "Allow", "Action": "kms:PutKeyPolicy", "Resource": "*", "Condition": { "Null": { "kms:BypassPolicyLockoutSafetyCheck": true } } } ``` **See also** + [kms:KeySpec](#conditions-kms-key-spec) + [kms:KeyOrigin](#conditions-kms-key-origin) + [kms:KeyUsage](#conditions-kms-key-usage) ## kms:CallerAccount | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:CallerAccount` | String | Single-valued | KMS key resource operations Custom key store operations | Key policies and IAM policies | You can use this condition key to allow or deny access to all identities (users and roles) in an AWS account. In key policies, you use the `Principal` element to specify the identities to which the policy statement applies. The syntax for the `Principal` element does not provide a way to specify all identities in an AWS account. But you can achieve this effect by combining this condition key with a `Principal` element that specifies all AWS identities. You can use it to control access to any *KMS key resource operation*, that is, any AWS KMS operation that uses a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. It is also valid for operations that manage [custom key stores](key-store-overview.md#custom-key-store-overview). For example, the following key policy statement demonstrates how to use the `kms:CallerAccount` condition key. This policy statement is in the key policy for the AWS managed key for Amazon EBS. It combines a `Principal` element that specifies all AWS identities with the `kms:CallerAccount` condition key to effectively allow access to all identities in AWS account 111122223333. It contains an additional AWS KMS condition key (`kms:ViaService`) to further limit the permissions by only allowing requests that come through Amazon EBS. For more information, see [kms:ViaService](#conditions-kms-via-service). ``` { "Sid": "Allow access through EBS for all principals in the account that are authorized to use EBS", "Effect": "Allow", "Principal": {"AWS": "*"}, "Condition": { "StringEquals": { "kms:CallerAccount": "111122223333", "kms:ViaService": "ec2.us-west-2.amazonaws.com" } }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant", "kms:DescribeKey" ], "Resource": "*" } ``` ## kms:CustomerMasterKeySpec (deprecated) The `kms:CustomerMasterKeySpec` condition key is deprecated. Instead, use the [kms:KeySpec](#conditions-kms-key-spec) condition key. The `kms:CustomerMasterKeySpec` and `kms:KeySpec` condition keys work the same way. Only the names differ. We recommend that you use `kms:KeySpec`. However, to avoid breaking changes, AWS KMS supports both condition keys. ## kms:CustomerMasterKeyUsage (deprecated) The `kms:CustomerMasterKeyUsage` condition key is deprecated. Instead, use the [kms:KeyUsage](#conditions-kms-key-usage) condition key. The `kms:CustomerMasterKeyUsage` and `kms:KeyUsage` condition keys work the same way. Only the names differ. We recommend that you use `kms:KeyUsage`. However, to avoid breaking changes, AWS KMS supports both condition keys. ## kms:DataKeyPairSpec | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:DataKeyPairSpec` | String | Single-valued | `GenerateDataKeyPair` `GenerateDataKeyPairWithoutPlaintext` | Key policies and IAM policies | You can use this condition key to control access to the [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) and [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) operations based on the value of the `KeyPairSpec` parameter in the request. For example, you can allow users to generate only particular types of data key pairs. The following example key policy statement uses the `kms:DataKeyPairSpec` condition key to allow users to use the KMS key to generate only RSA data key pairs. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": [ "kms:GenerateDataKeyPair", "kms:GenerateDataKeyPairWithoutPlaintext" ], "Resource": "*", "Condition": { "StringLike": { "kms:DataKeyPairSpec": "RSA*" } } } ``` **See also** + [kms:KeySpec](#conditions-kms-key-spec) + [kms:EncryptionAlgorithm](#conditions-kms-encryption-algorithm) + [kms:EncryptionContext:*context-key*](#conditions-kms-encryption-context) + [kms:EncryptionContextKeys](#conditions-kms-encryption-context-keys) ## kms:EncryptionAlgorithm | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:EncryptionAlgorithm` | String | Single-valued | `Decrypt` `Encrypt` `GenerateDataKey` `GenerateDataKeyPair` `GenerateDataKeyPairWithoutPlaintext` `GenerateDataKeyWithoutPlaintext` `ReEncrypt` | Key policies and IAM policies | You can use the `kms:EncryptionAlgorithm` condition key to control access to cryptographic operations based on the encryption algorithm that is used in the operation. For the [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html), [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), and [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) operations, it controls access based on the value of the [EncryptionAlgorithm](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html#KMS-Decrypt-request-EncryptionAlgorithm) parameter in the request. For operations that generate data keys and data key pairs, it controls access based on the encryption algorithm that is used to encrypt the data key. This condition key has no effect on operations performed outside of AWS KMS, such as encrypting with the public key in an asymmetric KMS key pair outside of AWS KMS. **EncryptionAlgorithm parameter in a request** To allow users to use only a particular encryption algorithm with a KMS key, use a policy statement with a `Deny` effect and a `StringNotEquals` condition operator. For example, the following example key policy statement prohibits principals who can assume the `ExampleRole` role from using this KMS key in the specified cryptographic operations unless the encryption algorithm in the request is `RSAES_OAEP_SHA_256`, an asymmetric encryption algorithm used with RSA KMS keys. Unlike a policy statement that allows a user to use a particular encryption algorithm, a policy statement with a double-negative like this one prevents other policies and grants for this KMS key from allowing this role to use other encryption algorithms. The `Deny` in this key policy statement takes precedence over any key policy or IAM policy with an `Allow` effect, and it takes precedence over all grants for this KMS key and its principals. ``` { "Sid": "Allow only one encryption algorithm with this asymmetric KMS key", "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*" ], "Resource": "*", "Condition": { "StringNotEquals": { "kms:EncryptionAlgorithm": "RSAES_OAEP_SHA_256" } } } ``` **Encryption algorithm used for the operation** You can also use the `kms:EncryptionAlgorithm` condition key to control access to operations based on the encryption algorithm used in the operation, even when the algorithm isn't specified in the request. This allows you to require or forbid the `SYMMETRIC_DEFAULT` algorithm, which might not be specified in a request because it's the default value. This feature lets you use the `kms:EncryptionAlgorithm` condition key to control access to the operations that generate data keys and data key pairs. These operations use only symmetric encryption KMS keys and the `SYMMETRIC_DEFAULT` algorithm. For example, this IAM policy limits its principals to symmetric encryption. It denies access to any KMS key in the example account for cryptographic operations unless the encryption algorithm specified in the request or used in the operation is SYMMETRIC\$1DEFAULT. Including `GenerateDataKey*` adds [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), and [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) to the permissions. The condition has no effect on these operations because they always use a symmetric encryption algorithm. ``` { "Sid": "AllowOnlySymmetricAlgorithm", "Effect": "Deny", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/*", "Condition": { "StringNotEquals": { "kms:EncryptionAlgorithm": "SYMMETRIC_DEFAULT" } } } ``` **See also** + [kms:MacAlgorithm](#conditions-kms-mac-algorithm) + [kms:SigningAlgorithm](#conditions-kms-signing-algorithm) ## kms:EncryptionContext:*context-key* | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:EncryptionContext:context-key` | String | Single-valued | `CreateGrant` `Encrypt` `Decrypt` `GenerateDataKey` `GenerateDataKeyPair` `GenerateDataKeyPairWithoutPlaintext` `GenerateDataKeyWithoutPlaintext` `ReEncrypt` `RetireGrant` | Key policies and IAM policies | You can use the `kms:EncryptionContext:context-key` condition key to control access to a [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks) based on the [encryption context](encrypt_context.md) in a request for a [cryptographic operation](kms-cryptography.md#cryptographic-operations). Use this condition key to evaluate both the key and the value in the encryption context pair. To evaluate only the encryption context keys or require an encryption context regardless of keys or values, use the [kms:EncryptionContextKeys](#conditions-kms-encryption-context-keys) condition key. **Note** Condition key values must conform to the character rules for key policies and IAM policies. Some characters that are valid in an encryption context are not valid in policies. You might not be able to use this condition key to express all valid encryption context values. For details about key policy document rules, see [Key policy format](key-policy-overview.md#key-policy-format). For details about IAM policy document rules, see [IAM name requirements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-names) in the *IAM User Guide*. You cannot specify an encryption context in a cryptographic operation with an [asymmetric KMS key](symmetric-asymmetric.md) or an [HMAC KMS key](hmac.md). Asymmetric algorithms and MAC algorithms do not support an encryption context. To use the kms:EncryptionContext:*context-key* condition key, replace the *context-key* placeholder with the encryption context key. Replace the *context-value* placeholder with the encryption context value. ``` "kms:EncryptionContext:context-key": "context-value" ``` For example, the following condition key specifies an encryption context in which the key is `AppName` and the value is `ExampleApp` (`AppName = ExampleApp`). ``` "kms:EncryptionContext:AppName": "ExampleApp" ``` This is a [single-valued condition key](#set-operators). The key in the condition key specifies a particular encryption context key (*context-key*). Although you can include multiple encryption context pairs in each API request, the encryption context pair with the specified *context-key* can have only one value. For example, the `kms:EncryptionContext:Department` condition key applies only to encryption context pairs with a `Department` key, and any given encryption context pair with the `Department` key can have only one value. Do not use a set operator with the `kms:EncryptionContext:context-key` condition key. If you create a policy statement with an `Allow` action, the `kms:EncryptionContext:context-key` condition key, and the `ForAllValues` set operator, the condition allows requests with no encryption context and requests with encryption context pairs that are not specified in the policy condition. **Warning** Do not use a `ForAnyValue` or `ForAllValues` set operator with this single-valued condition key. These set operators can create a policy condition that does not require values you intend to require and allows values you intend to forbid. If you create or update a policy that includes a `ForAllValues` set operator with the kms:EncryptionContext:*context-key*, AWS KMS returns the following error message: `OverlyPermissiveCondition:EncryptionContext: Using the ForAllValues set operator with a single-valued condition key matches requests without the specified encryption context or with an unspecified encryption context. To fix, remove ForAllValues.` To require a particular encryption context pair, use the `kms:EncryptionContext:context-key` condition key with the `StringEquals` operator . The following example key policy statement allows principals who can assume the role to use the KMS key in a `GenerateDataKey` request only when the encryption context in the request includes the `AppName:ExampleApp` pair. Other encryption context pairs are permitted. The key name is not case sensitive. The case sensitivity of the value is determined by the condition operator, such as `StringEquals`. For details, see [Case sensitivity of the encryption context condition](#conditions-kms-encryption-context-case). ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:AppName": "ExampleApp" } } } ``` To require an encryption context pair and forbid all other encryption context pairs, use both kms:EncryptionContext:*context-key* and [`kms:EncryptionContextKeys`](#conditions-kms-encryption-context-keys) in the policy statement. The following key policy statement uses the `kms:EncryptionContext:AppName` condition to require the `AppName=ExampleApp` encryption context pair in the request. It also uses a `kms:EncryptionContextKeys` condition key with the `ForAllValues` set operator to allow only the `AppName` encryption context key. The `ForAllValues` set operator limits encryption context keys in the request to `AppName`. If the `kms:EncryptionContextKeys` condition with the `ForAllValues` set operator was used alone in a policy statement, this set operator would allow requests with no encryption context. However, if the request had no encryption context, the `kms:EncryptionContext:AppName` condition would fail. For details about the `ForAllValues` set operator, see [Using multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the *IAM User Guide*. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/KeyUsers" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:AppName": "ExampleApp" }, "ForAllValues:StringEquals": { "kms:EncryptionContextKeys": [ "AppName" ] } } } ``` You can also use this condition key to deny access to a KMS key for a particular operation. The following example key policy statement uses a `Deny` effect to forbid the principal from using the KMS key if the encryption context in the request includes a `Stage=Restricted` encryption context pair. This condition allows a request with other encryption context pairs, including encryption context pairs with the `Stage` key and other values, such as `Stage=Test`. ``` { "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Stage": "Restricted" } } } ``` ### Using multiple encryption context pairs You can require or forbid multiple encryption context pairs. You can also require one of several encryption context pairs. For details about the logic used to interpret these conditions, see [Creating a condition with multiple keys or values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html) in the IAM User Guide. **Note** Earlier versions of this topic displayed policy statements that used the `ForAnyValue` and `ForAllValues` set operators with the kms:EncryptionContext:*context-key* condition key. Using a set operator with a [single-valued condition key](#set-operators) can result in policies that allow requests with no encryption context and unspecified encryption context pairs. For example, a policy condition with the `Allow` effect, the `ForAllValues` set operator, and the `"kms:EncryptionContext:Department": "IT"` condition key does not limit the encryption context to the "Department=IT" pair. It allows requests with no encryption context and requests with unspecified encryption context pairs, such as `Stage=Restricted`. Please review your policies and eliminate the set operator from any condition with kms:EncryptionContext:*context-key*. Attempts to create or update a policy with this format fail with an `OverlyPermissiveCondition` exception. To resolve the error, delete the set operator. To require multiple encryption context pairs, list the pairs in the same condition. The following example key policy statement requires two encryption context pairs, `Department=IT` and `Project=Alpha`. Because the conditions have different keys (`kms:EncryptionContext:Department` and `kms:EncryptionContext:Project`), they are implicitly connected by an AND operator. Other encryption context pairs are permitted, but not required. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:Decrypt", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Department": "IT", "kms:EncryptionContext:Project": "Alpha" } } } ``` To require one encryption context pair OR another pair, place each condition key in a separate policy statement. The following example key policy requires `Department=IT` *or* `Project=Alpha` pairs, or both. Other encryption context pairs are permitted, but not required. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Department": "IT" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Project": "Alpha" } } } ``` To require particular encryption pairs and exclude all other encryption context pairs, use both kms:EncryptionContext:*context-key* and [`kms:EncryptionContextKeys`](#conditions-kms-encryption-context-keys) in the policy statement. The following key policy statement uses the kms:EncryptionContext:*context-key* condition to require an encryption context with both `Department=IT` *and* `Project=Alpha` pairs. It uses a `kms:EncryptionContextKeys` condition key with the `ForAllValues` set operator to allow only the `Department` and `Project` encryption context keys. The `ForAllValues` set operator limits encryption context keys in the request to `Department` and `Project`. If it were used alone in a condition, this set operator would allow requests with no encryption context, but in this configuration, the kms:EncryptionContext:*context-key* in this condition would fail. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Department": "IT", "kms:EncryptionContext:Project": "Alpha" }, "ForAllValues:StringEquals": { "kms:EncryptionContextKeys": [ "Department", "Project" ] } } } ``` You can also forbid multiple encryption context pairs. The following example key policy statement uses a `Deny` effect to forbid the principal from using the KMS keys if the encryption context in the request includes a `Stage=Restricted` or `Stage=Production`.pair. Multiple values (`Restricted` and `Production`) for the same key (`kms:EncryptionContext:Stage`) are implicitly connected by a OR. For details, see [Evaluation logic for conditions with multiple keys or values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multiple-conditions-eval) in the *IAM User Guide*. ``` { "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Stage": [ "Restricted", "Production" ] } } } ``` ### Case sensitivity of the encryption context condition The encryption context that is specified in a decryption operation must be an exact, case-sensitive match for the encryption context that is specified in the encryption operation. Only the order of pairs in an encryption context with multiple pair can vary. However, in policy conditions, the condition key is not case sensitive. The case sensitivity of the condition value is determined by the [policy condition operator](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) that you use, such as `StringEquals` or `StringEqualsIgnoreCase`. As such, the condition key, which consists of the `kms:EncryptionContext:` prefix and the *`context-key`* replacement, is not case sensitive. A policy that uses this condition does not check the case of either element of the condition key. The case sensitivity of the value, that is, the *`context-value`* replacement, is determined by the policy condition operator. For example, the following policy statement allows the operation when the encryption context includes an `Appname` key, regardless of its capitalization. The `StringEquals` condition requires that `ExampleApp` be capitalized as it is specified. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:Decrypt", "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:Appname": "ExampleApp" } } } ``` To require a case-sensitive encryption context key, use the [kms:EncryptionContextKeys](#conditions-kms-encryption-context-keys) policy condition with a case-sensitive condition operator, such as `StringEquals`. In this policy condition, because the encryption context key is the value in this policy condition, its case sensitivity is determined by the condition operator. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "AppName" } } } ``` To require a case-sensitive evaluation of both the encryption context key and value, use the `kms:EncryptionContextKeys` and kms:EncryptionContext:*context-key* policy conditions together in the same policy statement. The case-sensitive condition operator (such as `StringEquals`) always applies to the value of the condition. The encryption context key (such as `AppName`) is the value of the `kms:EncryptionContextKeys` condition. The encryption context value (such as `ExampleApp`) is the value of the kms:EncryptionContext:*context-key* condition. For example, in the following example key policy statement, because the `StringEquals` operator is case sensitive, both the encryption context key and the encryption context value are case sensitive. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "AppName" }, "StringEquals": { "kms:EncryptionContext:AppName": "ExampleApp" } } } ``` ### Using variables in an encryption context condition 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, AWS KMS interprets it as a literal string. ``` "encryptionContext": { "department": "10103.0" } ``` However, the value of the `kms:EncryptionContext:context-key` condition key can be an [IAM policy variable](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html). These policy variables are resolved at runtime based on values in the request. For example, `aws:CurrentTime `resolves to the time of the request and `aws:username` resolves to the friendly name of the caller. You can use these policy variables to create a policy statement with a condition that requires very specific information in an encryption context, such as the caller's user name. Because it contains a variable, you can use the same policy statement for all users who can assume the role. You don't have to write a separate policy statement for each user. Consider a situation where you want to all users who can assume a role to use the same KMS key to encrypt and decrypt their data. However, you want to allow them to decrypt only the data that they encrypted. Start by requiring that every request to AWS KMS include an encryption context where the key is `user` and the value is the caller's AWS user name, such as the following one. ``` "encryptionContext": { "user": "bob" } ``` Then, to enforce this requirement, you can use a policy statement like the one in the following example. This policy statement gives the `TestTeam` role permission to encrypt and decrypt data with the KMS key. However, the permission is valid only when the encryption context in the request includes a `"user": ""` pair. To represent the user name, the condition uses the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#policy-vars-infotouse](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#policy-vars-infotouse) policy variable. When the request is evaluated, the caller's user name replaces the variable in the condition. As such, the condition requires an encryption context of `"user": "bob"` for "bob" and `"user": "alice"` for "alice." ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/TestTeam" }, "Action": [ "kms:Decrypt", "kms:Encrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:user": "${aws:username}" } } } ``` You can use an IAM policy variable only in the value of the `kms:EncryptionContext:context-key` condition key. You cannot use a variable in the key. You can also use [provider-specific context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc_user-id.html) in variables. These context keys uniquely identify users who logged into AWS by using web identity federation. Like all variables, these variables can be used only in the `kms:EncryptionContext:context-key` policy condition, not in the actual encryption context. And they can be used only in the value of the condition, not in the key. For example, the following key policy statement is similar to the previous one. However, the condition requires an encryption context where the key is `sub` and the value uniquely identifies a user logged into an Amazon Cognito user pool. For details about identifying users and roles in Amazon Cognito, see [IAM Roles](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html) in the [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/). ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/TestTeam" }, "Action": [ "kms:Decrypt", "kms:Encrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContext:sub": "${cognito-identity.amazonaws.com:sub}" } } } ``` **See also** + [kms:EncryptionContextKeys](#conditions-kms-encryption-context-keys) + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) ## kms:EncryptionContextKeys | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:EncryptionContextKeys` | String (list) | Multi-valued | `CreateGrant` `Decrypt` `Encrypt` `GenerateDataKey` `GenerateDataKeyPair` `GenerateDataKeyPairWithoutPlaintext` `GenerateDataKeyWithoutPlaintext` `ReEncrypt` `RetireGrant` | Key policies and IAM policies | You can use the `kms:EncryptionContextKeys` condition key to control access to a [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks) based on the [encryption context](encrypt_context.md) in a request for a cryptographic operation. Use this condition key to evaluate only the key in each encryption context pair. To evaluate both the key and the value in the encryption context, use the `kms:EncryptionContext:context-key` condition key. You cannot specify an encryption context in a cryptographic operation with an [asymmetric KMS key](symmetric-asymmetric.md) or an [HMAC KMS key](hmac.md). Asymmetric algorithms and MAC algorithms do not support an encryption context. **Note** Condition key values, including an encryption context key, must conform to the character and encoding rules for AWS KMS key policies. You might not be able to use this condition key to express all valid encryption context keys. For details about key policy document rules, see [Key policy format](key-policy-overview.md#key-policy-format). For details about IAM policy document rules, see [IAM name requirements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-names) in the *IAM User Guide*. This is a [multi-valued condition key](#set-operators). You can specify multiple encryption context pairs in each API request. `kms:EncryptionContextKeys` compares the encryption context keys in the request to the set of encryption context keys in the policy. To determine how these sets are compared, you must provide a `ForAnyValue` or `ForAllValues` set operator in the policy condition. For details about the set operators, see [Using multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the IAM User Guide. + `ForAnyValue`: At least one encryption context key in the request must match an encryption context key in the policy condition. Other encryption context keys are permitted. If the request has no encryption context, the condition is not satisfied. + `ForAllValues`: Every encryption context key in the request must match an encryption context key in the policy condition. This set operator limits the encryption context keys to those in the policy condition. It doesn't require any encryption context keys, but it forbids unspecified encryption context keys. The following example key policy statement uses the `kms:EncryptionContextKeys` condition key with the `ForAnyValue` set operator. This policy statement allows use of a KMS key for the specified operations, but only when at least one of the encryption context pairs in the request includes the `AppName` key, regardless of its value. For example, this key policy statement allows a `GenerateDataKey` request with two encryption context pairs, `AppName=Helper` and `Project=Alpha`, because the first encryption context pair satisfies the condition. A request with only `Project=Alpha` or with no encryption context would fail. Because the [StringEquals](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html) condition operation is case sensitive, this policy statement requires the spelling and case of the encryption context key. But you can use a condition operator that ignores the case of the key, such as `StringEqualsIgnoreCase`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "AppName" } } } ``` You can also use the `kms:EncryptionContextKeys` condition key to require an encryption context (any encryption context) in cryptographic operations that use the KMS key;. The following example key policy statement uses the `kms:EncryptionContextKeys` condition key with the [Null condition operator](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_Null) to allow access to a KMS key only when encryption context in the API request is not null. This condition does not check the keys or values of the encryption context. It only verifies that the encryption context exists. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "Null": { "kms:EncryptionContextKeys": false } } } ``` **See also** + [kms:EncryptionContext:*context-key*](#conditions-kms-encryption-context) + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) ## kms:ExpirationModel | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ExpirationModel` | String | Single-valued | `ImportKeyMaterial` | Key policies and IAM policies | The `kms:ExpirationModel` condition key controls access to the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation based on the value of the [ExpirationModel](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html#KMS-ImportKeyMaterial-request-ExpirationModel) parameter in the request. `ExpirationModel` is an optional parameter that determines whether the imported key material expires. Valid values are `KEY_MATERIAL_EXPIRES` and `KEY_MATERIAL_DOES_NOT_EXPIRE`. `KEY_MATERIAL_EXPIRES` is the default value. The expiration date and time is determined by the value of the [ValidTo](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html#KMS-ImportKeyMaterial-request-ValidTo) parameter. The `ValidTo` parameter is required unless the value of the `ExpirationModel` parameter is `KEY_MATERIAL_DOES_NOT_EXPIRE`. You can also use the [kms:ValidTo](#conditions-kms-valid-to) condition key to require a particular expiration date as a condition for access. The following example policy statement uses the `kms:ExpirationModel` condition key to allow users to import key material into a KMS key only when the request includes the `ExpirationModel` parameter and its value is `KEY_MATERIAL_DOES_NOT_EXPIRE`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "StringEquals": { "kms:ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE" } } } ``` You can also use the `kms:ExpirationModel` condition key to allow users to import key material only when the key material expires. The following example key policy statement uses the `kms:ExpirationModel` condition key with the [Null condition operator](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_Null) to allow users to import key material only when the request does not have an `ExpirationModel` parameter. The default value for ExpirationModel is `KEY_MATERIAL_EXPIRES`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "Null": { "kms:ExpirationModel": true } } } ``` **See also** + [kms:ValidTo](#conditions-kms-valid-to) + [kms:WrappingAlgorithm](#conditions-kms-wrapping-algorithm) + [kms:WrappingKeySpec](#conditions-kms-wrapping-key-spec) ## kms:GrantConstraintType | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:GrantConstraintType` | String | Single-valued | `CreateGrant` `RetireGrant` | Key policies and IAM policies | You can use this condition key to control access to the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation based on the type of [grant constraint](create-grant-overview.md#grant-constraints) in the request. When you create a grant, you can optionally specify a grant constraint to allow the operations that the grant permit only when a particular [encryption context](encrypt_context.md) is present. The grant constraint can be one of two types: `EncryptionContextEquals` or `EncryptionContextSubset`. You can use this condition key to check that the request contains one type or the other. **Important** Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output. The following example key policy statement uses the `kms:GrantConstraintType` condition key to allow users to create grants only when the request includes an `EncryptionContextEquals` grant constraint. The example shows a policy statement in a key policy. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:GrantConstraintType": "EncryptionContextEquals" } } } ``` **See also** + [kms:EncryptionContext:*context-key*](#conditions-kms-encryption-context) + [kms:EncryptionContextKeys](#conditions-kms-encryption-context-keys) + [kms:GrantIsForAWSResource](#conditions-kms-grant-is-for-aws-resource) + [kms:GrantOperations](#conditions-kms-grant-operations) + [kms:GranteePrincipal](#conditions-kms-grantee-principal) + [kms:RetiringPrincipal](#conditions-kms-retiring-principal) ## kms:GrantIsForAWSResource | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:GrantIsForAWSResource` | Boolean | Single-valued | `CreateGrant` `ListGrants` `RevokeGrant` | Key policies and IAM policies | Allows or denies permission for the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html), [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html), or [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) operations only when an [AWS service integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration) calls the operation on the user's behalf. This policy condition doesn't allow the user to call these grant operations directly. The following example key policy statement uses the `kms:GrantIsForAWSResource` condition key. It allows AWS services that are integrated with AWS KMS, such as Amazon EBS, to create grants on this KMS key on behalf of the specified principal. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": true } } } ``` **See also** + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) + [kms:GrantOperations](#conditions-kms-grant-operations) + [kms:GranteePrincipal](#conditions-kms-grantee-principal) + [kms:RetiringPrincipal](#conditions-kms-retiring-principal) ## kms:GrantOperations | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:GrantOperations` | String | Multi-valued | `CreateGrant` | Key policies and IAM policies | You can use this condition key to control access to the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation based on the [grant operations](grants.md#terms-grant-operations) in the request. For example, you can allow users to create grants that delegate permission to encrypt but not decrypt. For more information about grants, see [Using grants](grants.md). This is a [multi-valued condition key](#set-operators). `kms:GrantOperations` compares the set of grant operations in the `CreateGrant` request to the set of grant operations in the policy. To determine how these sets are compared, you must provide a `ForAnyValue` or `ForAllValues` set operator in the policy condition. For details about the set operators, see [Using multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the IAM User Guide. + `ForAnyValue`: At least one grant operation in the request must match one of the grant operations in the policy condition. Other grant operations are permitted. + ForAllValues: Every grant operation in the request must match a grant operation in the policy condition. This set operator limits the grant operations to those specified in the policy condition. It doesn't require any grant operations, but it forbids unspecified grant operations. ForAllValues also returns true when there are no grant operations in the request, but `CreateGrant` doesn't permit it. If the `Operations` parameter is missing or has a null value, the `CreateGrant` request fails. The following example key policy statement uses the `kms:GrantOperations` condition key to to create grants only when the grant operations are `Encrypt`, `ReEncryptTo`, or both. If the grant includes any other operations, the `CreateGrant` request fails. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "kms:GrantOperations": [ "Encrypt", "ReEncryptTo" ] } } } ``` If you change the set operator in the policy condition to `ForAnyValue`, the policy statement would require that at least one of the grant operations in the grant is `Encrypt` or `ReEncryptTo`, but it would allow other grant operations, such as `Decrypt` or `ReEncryptFrom`. **See also** + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) + [kms:GrantIsForAWSResource](#conditions-kms-grant-is-for-aws-resource) + [kms:GranteePrincipal](#conditions-kms-grantee-principal) + [kms:RetiringPrincipal](#conditions-kms-retiring-principal) ## kms:GranteePrincipal | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:GranteePrincipal` | String | Single-valued | `CreateGrant` | IAM and key policies | You can use this condition key to control access to the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation based on the value of the [GranteePrincipal](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-GranteePrincipal) parameter in the request. For example, you can to create grants to use a KMS key only when the grantee principal in the `CreateGrant` request matches the principal specified in the condition statement. To specify the grantee principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid principals include AWS accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see [IAM ARNs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns) in the *IAM User Guide*. The following example key policy statement uses the `kms:GranteePrincipal` condition key to to create grants for a KMS key only when the grantee principal in the grant is the `LimitedAdminRole`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:GranteePrincipal": "arn:aws:iam::111122223333:role/LimitedAdminRole" } } } ``` **See also** + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) + [kms:GrantIsForAWSResource](#conditions-kms-grant-is-for-aws-resource) + [kms:GrantOperations](#conditions-kms-grant-operations) + [kms:RetiringPrincipal](#conditions-kms-retiring-principal) ## kms:KeyAgreementAlgorithm | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:KeyAgreementAlgorithm` | String | Single-valued | `DeriveSharedSecret` | Key policies and IAM policies | You can use the `kms:KeyAgreementAlgorithm` condition key to control access to the [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) operation based on the value of the `KeyAgreementAlgorithm` parameter in the request. The only valid value for `KeyAgreementAlgorithm` is `ECDH`. For example, the following key policy statement uses the `kms:KeyAgreementAlgorithm` condition key to deny all access to DeriveSharedSecret unless the `KeyAgreementAlgorithm` is `ECDH`. ``` { "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:DeriveSharedSecret", "Resource": "*", "Condition": { "StringNotEquals": { "kms:KeyAgreementAlgorithm": "ECDH" } } } ``` **See also** + [kms:KeyUsage](#conditions-kms-key-usage) ## kms:KeyOrigin | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:KeyOrigin` | String | Single-valued | `CreateKey` KMS key resource operations | IAM policies Key policies and IAM policies | The `kms:KeyOrigin` condition key controls access to operations based on the value of the `Origin` property of the KMS key that is created by or used in the operation. It works as a resource condition or a request condition. You can use this condition key to control access to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation based on the value of the [Origin](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html#KMS-CreateKey-request-Origin) parameter in the request. Valid values for `Origin` are `AWS_KMS`, `AWS_CLOUDHSM`, `EXTERNAL_KEY_STORE`, and `EXTERNAL`. For example, you can create a KMS key only when the key material is generated in AWS KMS (`AWS_KMS`), only when the key material is generated in an AWS CloudHSM cluster that is associated with a [CloudHSM custom key store](key-store-overview.md#custom-key-store-overview) (`AWS_CLOUDHSM`), only when the key material is generated in an [external key store](key-store-overview.md#custom-key-store-overview) (`EXTERNAL_KEY_STORE`), or only when the [key material is imported](importing-keys.md) from an external source (`EXTERNAL`). The following example key policy statement uses the `kms:KeyOrigin` condition key to create a KMS key only when AWS KMS creates the key material. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:KeyOrigin": "AWS_KMS" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:GenerateDataKeyPair", "kms:GenerateDataKeyPairWithoutPlaintext", "kms:ReEncrypt*" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/*", "Condition": { "StringEquals": { "kms:KeyOrigin": "AWS_CLOUDHSM" } } } ] } ``` ------ You can also use the `kms:KeyOrigin` condition key to control access to operations that use or manage a KMS key based on the `Origin` property of the KMS key used for the operation. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. For example, the following IAM policy allows principals to perform the specified KMS key resource operations, but only with KMS keys in the account that were created in a custom key store. ``` { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:GenerateDataKeyPair", "kms:GenerateDataKeyPairWithoutPlaintext", "kms:ReEncrypt*" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/*", "Condition": { "StringEquals": { "kms:KeyOrigin": "AWS_CLOUDHSM" } } } ``` **See also** + [kms:BypassPolicyLockoutSafetyCheck](#conditions-kms-bypass-policy-lockout-safety-check) + [kms:KeySpec](#conditions-kms-key-spec) + [kms:KeyUsage](#conditions-kms-key-usage) ## kms:KeySpec | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:KeySpec` | String | Single-valued | `CreateKey` KMS key resource operations | IAM policies Key policies and IAM policies | The `kms:KeySpec` condition key controls access to operations based on the value of the `KeySpec` property of the KMS key that is created by or used in the operation. You can use this condition key in an IAM policy to control access to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation based on the value of the [KeySpec](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html#KMS-CreateKey-request-KeySpec) parameter in a `CreateKey` request. For example, you can use this condition to allow users to create only symmetric encryption KMS keys or only HMAC KMS keys. The following example IAM policy statement uses the `kms:KeySpec` condition key to allow the principals to create only RSA asymmetric KMS keys. The permission is valid only when the `KeySpec` in the request begins with `RSA_`. ``` { "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringLike": { "kms:KeySpec": "RSA_*" } } } ``` You can also use the `kms:KeySpec` condition key to control access to operations that use or manage a KMS key based on the `KeySpec` property of the KMS key used for the operation. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. For example, the following IAM policy allows principals to perform the specified KMS key resource operations, but only with symmetric encryption KMS keys in the account. ``` { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/*", "Condition": { "StringEquals": { "kms:KeySpec": "SYMMETRIC_DEFAULT" } } } ``` **See also** + [kms:BypassPolicyLockoutSafetyCheck](#conditions-kms-bypass-policy-lockout-safety-check) + [kms:CustomerMasterKeySpec (deprecated)](#conditions-kms-key-spec-replaced) + [kms:DataKeyPairSpec](#conditions-kms-data-key-spec) + [kms:KeyOrigin](#conditions-kms-key-origin) + [kms:KeyUsage](#conditions-kms-key-usage) ## kms:KeyUsage | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:KeyUsage` | String | Single-valued | `CreateKey` KMS key resource operations | IAM policies Key policies and IAM policies | The `kms:KeyUsage` condition key controls access to operations based on the value of the `KeyUsage` property of the KMS key that is created by or used in the operation. You can use this condition key to control access to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation based on the value of the [KeyUsage](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html#KMS-CreateKey-request-KeyUsage) parameter in the request. Valid values for `KeyUsage` are `ENCRYPT_DECRYPT`, `SIGN_VERIFY`, `GENERATE_VERIFY_MAC`, and `KEY_AGREEMENT`. For example, you can to create a KMS key only when the `KeyUsage` is `ENCRYPT_DECRYPT` or deny a user permission when the `KeyUsage` is `SIGN_VERIFY`. The following example IAM policy statement uses the `kms:KeyUsage` condition key to to create a KMS key only when the `KeyUsage` is `ENCRYPT_DECRYPT`. ``` { "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:KeyUsage": "ENCRYPT_DECRYPT" } } } ``` You can also use the `kms:KeyUsage` condition key to control access to operations that use or manage a KMS key based on the `KeyUsage` property of the KMS key in the operation. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. For example, the following IAM policy allows principals to perform the specified KMS key resource operations, but only with KMS keys in the account that are used for signing and verification. ``` { "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:DescribeKey", "kms:GetPublicKey", "kms:ScheduleKeyDeletion" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/*", "Condition": { "StringEquals": { "kms:KeyUsage": "SIGN_VERIFY" } } } ``` **See also** + [kms:BypassPolicyLockoutSafetyCheck](#conditions-kms-bypass-policy-lockout-safety-check) + [kms:CustomerMasterKeyUsage (deprecated)](#conditions-kms-key-usage-replaced) + [kms:KeyOrigin](#conditions-kms-key-origin) + [kms:KeySpec](#conditions-kms-key-spec) ## kms:MacAlgorithm | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:MacAlgorithm` | String | Single-valued | `GenerateMac``VerifyMac` | Key policies and IAM policies | You can use the `kms:MacAlgorithm` condition key to control access to the [GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) and [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) operations based on the value of the `MacAlgorithm` parameter in the request. The following example key policy allows users who can assume the `testers` role to use the HMAC KMS key to generate and verify HMAC tags only when the MAC algorithm in the request is `HMAC_SHA_384` or `HMAC_SHA_512`. This policy uses two separate policy statements each with its own condition. If you specify more than one MAC algorithm in a single condition statement, the condition requires both algorithms, instead of one or the other. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/testers" }, "Action": [ "kms:GenerateMac", "kms:VerifyMac" ], "Resource": "*", "Condition": { "StringEquals": { "kms:MacAlgorithm": "HMAC_SHA_384" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/testers" }, "Action": [ "kms:GenerateMac", "kms:VerifyMac" ], "Resource": "*", "Condition": { "StringEquals": { "kms:MacAlgorithm": "HMAC_SHA_512" } } } ] } ``` ------ **See also** + [kms:EncryptionAlgorithm](#conditions-kms-encryption-algorithm) + [kms:SigningAlgorithm](#conditions-kms-signing-algorithm) ## kms:MessageType | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:MessageType` | String | Single-valued | `Sign` `Verify` | Key policies and IAM policies | The `kms:MessageType` condition key controls access to the [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) and [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) operations based on the value of the `MessageType` parameter in the request. Valid values for `MessageType` are `RAW`, `DIGEST` and `EXTERNAL_MU`. For example, the following key policy statement uses the `kms:MessageType` condition key to to use an asymmetric KMS key to sign a message, but not a message digest. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:Sign", "Resource": "*", "Condition": { "StringEquals": { "kms:MessageType": "RAW" } } } ``` **See also** + [kms:SigningAlgorithm](#conditions-kms-signing-algorithm) ## kms:MultiRegion | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:MultiRegion` | Boolean | Single-valued | `CreateKey` KMS key resource operations | Key policies and IAM policies | You can use this condition key to allow operations only on single-Region keys or only on [multi-Region keys](multi-region-keys-overview.md). The `kms:MultiRegion` condition key controls access to AWS KMS operations on KMS keys and to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation based on the value of the `MultiRegion` property of the KMS key. Valid values are `true` (multi-Region), and `false` (single-Region). All KMS keys have a `MultiRegion` property. For example, the following IAM policy statement uses the `kms:MultiRegion` condition key to allow principals to create only single-Region keys. ``` { "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*", "Condition": { "Bool": { "kms:MultiRegion": false } } } ``` ## kms:MultiRegionKeyType | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:MultiRegionKeyType` | String | Single-valued | `CreateKey` KMS key resource operations | Key policies and IAM policies | You can use this condition key to allow operations only on [multi-Region primary keys](multi-region-keys-overview.md#mrk-primary-key) or only on [multi-Region replica keys](multi-region-keys-overview.md#mrk-replica-key). The `kms:MultiRegionKeyType` condition key controls access to AWS KMS operations on KMS keys and the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation based on the `MultiRegionKeyType` property of the KMS key. The valid values are `PRIMARY` and `REPLICA`. Only multi-Region keys have a `MultiRegionKeyType` property. Typically, you use the `kms:MultiRegionKeyType` condition key in an IAM policy to control access to multiple KMS keys. However, because a given multi-Region key can change to primary or replica, you might want to use this condition in a key policy to allow an operation only when the particular multi-Region key is a primary or replica key. For example, the following IAM policy statement uses the `kms:MultiRegionKeyType` condition key to allow principals to schedule and cancel key deletion only on multi-Region replica keys in the specified AWS account. ``` { "Effect": "Allow", "Action": [ "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "arn:aws:kms:*:111122223333:key/*", "Condition": { "StringEquals": { "kms:MultiRegionKeyType": "REPLICA" } } } ``` To allow or deny access to all multi-Region keys, you can use both values or a null value with `kms:MultiRegionKeyType`. However, the [kms:MultiRegion](#conditions-kms-multiregion) condition key is recommended for that purpose. ## kms:PrimaryRegion | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:PrimaryRegion` | String (list) | Single-valued | `UpdatePrimaryRegion` | Key policies and IAM policies | You can use this condition key to limit the destination Regions in an [UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) operation. These are AWS Regions that can host your multi-Region primary keys. The `kms:PrimaryRegion` condition key controls access to the [UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) operation based on the value of the `PrimaryRegion` parameter. The `PrimaryRegion` parameter specifies the AWS Region of the [multi-Region replica key](multi-region-keys-overview.md#mrk-replica-key) that is being promoted to primary. The value of the condition is one or more AWS Region names, such as `us-east-1` or `ap-southeast-2`, or Region name patterns, such as `eu-*` For example, the following key policy statement uses the `kms:PrimaryRegion` condition key to allow principals to update the primary region of a multi-Region key to one of the four specified Regions. ``` { "Effect": "Allow", "Action": "kms:UpdatePrimaryRegion", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Developer" }, "Resource": "*", "Condition": { "StringEquals": { "kms:PrimaryRegion": [ "us-east-1", "us-west-2", "eu-west-3", "ap-southeast-2" ] } } } ``` ## kms:ReEncryptOnSameKey | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ReEncryptOnSameKey` | Boolean | Single-valued | `ReEncrypt` | Key policies and IAM policies | You can use this condition key to control access to the [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) operation based on whether the request specifies a destination KMS key that is the same one used for the original encryption. For example, the following key policy statement uses the `kms:ReEncryptOnSameKey` condition key to to reencrypt only when the destination KMS key is the same one used for the original encryption. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:ReEncrypt*", "Resource": "*", "Condition": { "Bool": { "kms:ReEncryptOnSameKey": true } } } ``` ## kms:RequestAlias | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:RequestAlias` | String (list) | Single-valued | [Cryptographic operations](kms-cryptography.md#cryptographic-operations) [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) | Key policies and IAM policies | You can use this condition key to allow an operation only when the request uses a particular alias to identify the KMS key. The `kms:RequestAlias` condition key controls access to a KMS key used in a cryptographic operation, `GetPublicKey`, or `DescribeKey` based on the [alias](kms-alias.md) that identifies that KMS key in the request. (This policy condition has no effect on the [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) operation because the operation doesn't use a KMS key or alias.) This condition supports [attribute-based access control](abac.md) (ABAC) in AWS KMS, which lets you control access to KMS keys based on the tags and aliases of a KMS key. You can use tags and aliases to allow or deny access to a KMS key without changing policies or grants. For details, see [ABAC for AWS KMS](abac.md). To specify the alias in this policy condition, use an [alias name](concepts.md#key-id-alias-name), such as `alias/project-alpha`, or an alias name pattern, such as `alias/*test*`. You cannot specify an [alias ARN](concepts.md#key-id-alias-ARN) in the value of this condition key. To satisfy this condition, the value of the `KeyId` parameter in the request must be a matching alias name or alias ARN. If the request uses a different [key identifier](concepts.md#key-id), it does not satisfy the condition, even if identifies the same KMS key. For example, the following key policy statement allows the principal to call the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation on the KMS key. However this is permitted only when the value of the `KeyId` parameter in the request is `alias/finance-key` or an alias ARN with that alias name, such as `arn:aws:kms:us-west-2:111122223333:alias/finance-key`. ``` { "Sid": "Key policy using a request alias condition", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/developer" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "StringEquals": { "kms:RequestAlias": "alias/finance-key" } } } ``` You cannot use this condition key to control access to alias operations, such as [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) or [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html). For information about controlling access to alias operations, see [Controlling access to aliases](alias-access.md). ## kms:ResourceAliases | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ResourceAliases` | String (list) | Multi-valued | KMS key resource operations | IAM policies only | Use this condition key to control access to a KMS key based on the [aliases](kms-alias.md) that are associated with the KMS key. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. This condition supports attribute-based access control (ABAC) in AWS KMS. With ABAC, you can control access to KMS keys based on the tags that are assigned to a KMS key and the aliases that are associated with a KMS key. You can use tags and aliases to allow or deny access to a KMS key without changing policies or grants. For details, see [ABAC for AWS KMS](abac.md). An alias must be unique in an AWS account and Region, but this condition lets you control access to multiple KMS keys in the same Region (using the `StringLike` comparison operator) or to multiple KMS keys in different AWS Regions of each account. **Note** The [kms:ResourceAliases](#conditions-kms-resource-aliases) condition is effective only when the KMS key conforms to the [aliases per KMS key](resource-limits.md#aliases-per-key) quota. If a KMS key exceeds this quota, principals who are authorized to use the KMS key by the `kms:ResourceAliases` condition are denied access to the KMS key. To specify the alias in this policy condition, use an [alias name](concepts.md#key-id-alias-name), such as `alias/project-alpha`, or an alias name pattern, such as `alias/*test*`. You cannot specify an [alias ARN](concepts.md#key-id-alias-ARN) in the value of this condition key. To satisfy the condition, the KMS key used in the operation must have the specified alias. It does not matter whether or how the KMS key is identified in the request for the operation. This is a multivalued condition key that compares the set of aliases associated with a KMS key to the set of aliases in the policy. To determine how these sets are compared, you must provide a `ForAnyValue` or `ForAllValues` set operator in the policy condition. For details about the set operators, see [Using multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the IAM User Guide. + ForAnyValue: At least one alias associated with the KMS key must match an alias in the policy condition. Other aliases are permitted. If the KMS key has no aliases, the condition is not satisfied. + ForAllValues: Every alias associated with the KMS key must match an alias in the policy. This set operator limits the aliases associated with the KMS key to those in the policy condition. It doesn't require any aliases, but it forbids unspecified aliases. For example, the following IAM policy statement allows the principal to call the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation on any KMS key in the specified AWS account that is associated with the `finance-key` alias. (The key policies of the affected KMS keys must also allow the principal's account to use them for this operation.) To indicate that the condition is satisfied when one of the many aliases that might be associated with the KMS key is `alias/finance-key`, the condition uses the `ForAnyValue` set operator. Because the `kms:ResourceAliases` condition is based on the resource, not the request, a call to `GenerateDataKey` succeeds for any KMS key associated with the `finance-key` alias, even if the request uses a [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN) to identify the KMS key. ``` { "Sid": "AliasBasedIAMPolicy", "Effect": "Allow", "Action": "kms:GenerateDataKey", "Resource": [ "arn:aws:kms:*:111122223333:key/*", "arn:aws:kms:*:444455556666:key/*" ], "Condition": { "ForAnyValue:StringEquals": { "kms:ResourceAliases": "alias/finance-key" } } } ``` The following example IAM policy statement allows the principal to enable and disable KMS keys but only when all aliases of the KMS keys include "`Test`." This policy statement uses two conditions. The condition with the `ForAllValues` set operator requires that all aliases associated with the KMS key include "Test". The condition with the `ForAnyValue` set operator requires that the KMS key have at least one alias with "Test." Without the `ForAnyValue` condition, this policy statement would have allowed the principal to use KMS keys that had no aliases. ``` { "Sid": "AliasBasedIAMPolicy", "Effect": "Allow", "Action": [ "kms:EnableKey", "kms:DisableKey" ], "Resource": "arn:aws:kms:*:111122223333:key/*", "Condition": { "ForAllValues:StringLike": { "kms:ResourceAliases": [ "alias/*Test*" ] }, "ForAnyValue:StringLike": { "kms:ResourceAliases": [ "alias/*Test*" ] } } } ``` ## kms:ReplicaRegion | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ReplicaRegion` | String (list) | Single-valued | `ReplicateKey` | Key policies and IAM policies | You can use this condition key to limit the AWS Regions in which a principal can replicate a [multi-Region key](multi-region-keys-overview.md). The `kms:ReplicaRegion` condition key controls access to the [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation based on the value of the [ReplicaRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-RetiringPrincipal) parameter in the request. This parameter specifies the AWS Region for the new [replica key](multi-region-keys-overview.md#mrk-replica-key). The value of the condition is one or more AWS Region names, such as `us-east-1` or `ap-southeast-2`, or name patterns, such as `eu-*`. For a list of the names of AWS Regions that AWS KMS supports, see [AWS Key Management Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/kms.html) in the AWS General Reference. For example, the following key policy statement uses the `kms:ReplicaRegion` condition key to allow principals to call the [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) operation only when the value of the `ReplicaRegion` parameter is one of the specified Regions. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Administrator" }, "Action": "kms:ReplicateKey" "Resource": "*", "Condition": { "StringEquals": { "kms:ReplicaRegion": [ "us-east-1", "eu-west-3", "ap-southeast-2" ] } } } ``` This condition key controls access only to the [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) operation. To control access to the [UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) operation, use the [kms:PrimaryRegion](#conditions-kms-primary-region) condition key. ## kms:RetiringPrincipal | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:RetiringPrincipal` | String (list) | Single-valued | `CreateGrant` | Key policies and IAM policies | You can use this condition key to control access to the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation based on the value of the [RetiringPrincipal](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-RetiringPrincipal) parameter in the request. For example, you can to create grants to use a KMS key only when the `RetiringPrincipal` in the `CreateGrant` request matches the `RetiringPrincipal` in the condition statement. To specify the retiring principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid principals include AWS accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see [IAM ARNs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns) in the *IAM User Guide*. The following example key policy statement allows a user to create grants for the KMS key. The `kms:RetiringPrincipal` condition key restricts the permission to `CreateGrant` requests where the retiring principal in the grant is the `LimitedAdminRole`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:RetiringPrincipal": "arn:aws:iam::111122223333:role/LimitedAdminRole" } } } ``` **See also** + [kms:GrantConstraintType](#conditions-kms-grant-constraint-type) + [kms:GrantIsForAWSResource](#conditions-kms-grant-is-for-aws-resource) + [kms:GrantOperations](#conditions-kms-grant-operations) + [kms:GranteePrincipal](#conditions-kms-grantee-principal) ## kms:RotationPeriodInDays | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:RotationPeriodInDays` | Numeric | Single-valued | `EnableKeyRotation` | Key policies and IAM policies | You can use this condition key to limit the values that principals can specify in the `RotationPeriodInDays` parameter of a [EnableKeyRotation](https://docs.aws.amazon.com/kms/latest/APIReference/API_EnableKeyRotation.html) request. The `RotationPeriodInDays` specifies the number of days between each automatic key rotation date. AWS KMS allows you to specify a rotation period between 90 and 2560 days, but you can use the `kms:RotationPeriodInDays` condition key to further constrain the rotation period, such as enforcing a minimum rotation period within the valid range. For example, the following key policy statement uses the `kms:RotationPeriodInDays` condition key to prevent principals from enabling key rotation if the rotation period is less than or equal to 180 days. ``` { "Effect": "Deny", "Action": "kms:EnableKeyRotation", "Principal": "*", "Resource": "*", "Condition" : { "NumericLessThanEquals" : { "kms:RotationPeriodInDays" : "180" } } } ``` ## kms:ScheduleKeyDeletionPendingWindowInDays | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ScheduleKeyDeletionPendingWindowInDays` | Numeric | Single-valued | `ScheduleKeyDeletion` | Key policies and IAM policies | You can use this condition key to limit the values that principals can specify in the `PendingWindowInDays` parameter of a [ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) request. The `PendingWindowInDays` specifies the number of days that AWS KMS will wait before deleting a key. AWS KMS allows you to specify a waiting period between 7 and 30 days, but you can use the `kms:ScheduleKeyDeletionPendingWindowInDays` condition key to further constrain the waiting period, such as enforcing a minimum waiting period within the valid range. For example, the following key policy statement uses the `kms:ScheduleKeyDeletionPendingWindowInDays` condition key to prevent principals from scheduling key deletion if the waiting period is less than or equal to 21 days. ``` { "Effect": "Deny", "Action": "kms:ScheduleKeyDeletion", "Principal": "*", "Resource": "*", "Condition" : { "NumericLessThanEquals" : { "kms:ScheduleKeyDeletionPendingWindowInDays" : "21" } } } ``` ## kms:SigningAlgorithm | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:SigningAlgorithm` | String | Single-valued | `Sign` `Verify` | Key policies and IAM policies | You can use the `kms:SigningAlgorithm` condition key to control access to the [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) and [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) operations based on the value of the [SigningAlgorithm](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html#KMS-Sign-request-SigningAlgorithm) parameter in the request. This condition key has no effect on operations performed outside of AWS KMS, such as verifying signatures with the public key in an asymmetric KMS key pair outside of AWS KMS. The following example key policy allows users who can assume the `testers` role to use the KMS key to sign messages only when the signing algorithm used for the request is an RSASSA\$1PSS algorithm, such as `RSASSA_PSS_SHA512`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/testers" }, "Action": "kms:Sign", "Resource": "*", "Condition": { "StringLike": { "kms:SigningAlgorithm": "RSASSA_PSS*" } } } ``` **See also** + [kms:EncryptionAlgorithm](#conditions-kms-encryption-algorithm) + [kms:MacAlgorithm](#conditions-kms-mac-algorithm) + [kms:MessageType](#conditions-kms-message-type) ## kms:ValidTo | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ValidTo` | Timestamp | Single-valued | `ImportKeyMaterial` | Key policies and IAM policies | The `kms:ValidTo` condition key controls access to the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation based on the value of the [ValidTo](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html#KMS-ImportKeyMaterial-request-ValidTo) parameter in the request, which determines when the imported key material expires. The value is expressed in [Unix time](https://en.wikipedia.org/wiki/Unix_time). By default, the `ValidTo` parameter is required in an `ImportKeyMaterial` request. However, if the value of the [ExpirationModel](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html#KMS-ImportKeyMaterial-request-ExpirationModel) parameter is `KEY_MATERIAL_DOES_NOT_EXPIRE`, the `ValidTo` parameter is invalid. You can also use the [kms:ExpirationModel](#conditions-kms-expiration-model) condition key to require the `ExpirationModel` parameter or a specific parameter value. The following example policy statement allows a user to import key material into a KMS key. The `kms:ValidTo` condition key limits the permission to `ImportKeyMaterial` requests where the `ValidTo` value is less than or equal to `1546257599.0` (December 31, 2018 11:59:59 PM). ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "NumericLessThanEquals": { "kms:ValidTo": "1546257599.0" } } } ``` **See also** + [kms:ExpirationModel](#conditions-kms-expiration-model) + [kms:WrappingAlgorithm](#conditions-kms-wrapping-algorithm) + [kms:WrappingKeySpec](#conditions-kms-wrapping-key-spec) ## kms:ViaService | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:ViaService` | String | Single-valued | KMS key resource operations | Key policies and IAM policies | The `kms:ViaService` condition key limits use of an KMS key to requests from specified AWS services. This condition key only applies for [Forward access sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html). You can specify one or more services in each `kms:ViaService` condition key. The operation must be a *KMS key resource operation*, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the [Actions and Resources Table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of `KMS key` in the `Resources` column for the operation. For example, the following key policy statement uses the `kms:ViaService` condition key to allow a [customer managed key](concepts.md#customer-mgn-key) to be used for the specified actions only when the request comes from Amazon EC2 or Amazon RDS in the US West (Oregon) region on behalf of `ExampleRole`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant", "kms:ListGrants", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "ec2.us-west-2.amazonaws.com", "rds.us-west-2.amazonaws.com" ] } } } ``` You can also use a `kms:ViaService` condition key to deny permission to use a KMS key when the request comes from particular services. For example, the following policy statement from a key policy uses a `kms:ViaService` condition key to prevent a customer managed key from being used for `Encrypt` operations when the request comes from AWS Lambda on behalf of `ExampleRole`. ``` { "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": [ "kms:Encrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "lambda.us-west-2.amazonaws.com" ] } } } ``` **Important** When you use the `kms:ViaService` condition key, the service makes the request on behalf of a principal in the AWS account. These principals must have the following permissions: Permission to use the KMS key. The principal needs to grant these permissions to the integrated service so the service can use the customer managed key on behalf of the principal. For more information, see [Using AWS KMS encryption with AWS services](service-integration.md). Permission to use the integrated service. For details about giving users access to an AWS service that integrates with AWS KMS, consult the documentation for the integrated service. All [AWS managed keys](concepts.md#aws-managed-key) use a `kms:ViaService` condition key in their key policy document. This condition allows the KMS key to be used only for requests that come from the service that created the KMS key. To see the key policy for an AWS managed key, use the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation. The `kms:ViaService` condition key is valid in IAM and key policy statements. The services that you specify must be [integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration) and support the `kms:ViaService` condition key. ### Services that support the `kms:ViaService` condition key The following table lists AWS services that are integrated with AWS KMS and support the use of the `kms:ViaService` condition key in customer managed keys The services in this table might not be available in all regions. Use the `.amazonaws.com` suffix of the AWS KMS ViaService name in all AWS partitions. **Note** You might need to scroll horizontally or vertically to see all of the data in this table. | Service name | AWS KMS ViaService name | | --- | --- | | Amazon AI Operations | aiops.AWS\$1region.amazonaws.com | | AWS App Runner | apprunner.AWS\$1region.amazonaws.com | | AWS AppFabric | appfabric.AWS\$1region.amazonaws.com | | Amazon AppFlow | appflow.AWS\$1region.amazonaws.com | | AWS Application Migration Service | mgn.AWS\$1region.amazonaws.com | | Amazon Athena | athena.AWS\$1region.amazonaws.com | | AWS Audit Manager | auditmanager.AWS\$1region.amazonaws.com | | Amazon Aurora | rds.AWS\$1region.amazonaws.com | | AWS Backup | backup.AWS\$1region.amazonaws.com | | AWS Backup Gateway | backup-gateway.AWS\$1region.amazonaws.com | | Amazon Bedrock Model Copy | bedrock.AWS\$1region.amazonaws.com | | Amazon Chime SDK | chimevoiceconnector.AWS\$1region.amazonaws.com | | AWS Clean Rooms ML | cleanrooms-ml.AWS\$1region.amazonaws.com | | AWS CodeArtifact | codeartifact.AWS\$1region.amazonaws.com | | Amazon CodeGuru Reviewer | codeguru-reviewer.AWS\$1region.amazonaws.com | | Amazon Comprehend | comprehend.AWS\$1region.amazonaws.com | | Amazon Connect | connect.AWS\$1region.amazonaws.com | | Amazon Connect Customer Profiles | profile.AWS\$1region.amazonaws.com | | Amazon Q in Connect | wisdom.AWS\$1region.amazonaws.com | | AWS Database Migration Service (AWS DMS) | dms.AWS\$1region.amazonaws.com | | AWS DeepRacer | deepracer.AWS\$1region.amazonaws.com | | AWS Directory Service | directoryservice.AWS\$1region.amazonaws.com | | Amazon DocumentDB | docdb-elastic.AWS\$1region.amazonaws.com | | Amazon DynamoDB | dynamodb.AWS\$1region.amazonaws.com | | Amazon EC2 Systems Manager (SSM) | ssm.AWS\$1region.amazonaws.com | | Amazon Elastic Block Store (Amazon EBS) | ec2.AWS\$1region.amazonaws.com (EBS only) | | Amazon Elastic Container Registry (Amazon ECR) | ecr.AWS\$1region.amazonaws.com | | Amazon Elastic File System (Amazon EFS) | elasticfilesystem.AWS\$1region.amazonaws.com | | Amazon ElastiCache | Include both ViaService names in the condition key value: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/conditions-kms.html) | | AWS Elemental MediaTailor | mediatailor.AWS\$1region.amazonaws.com | | AWS Entity Resolution | entityresolution.AWS\$1region.amazonaws.com | | Amazon EventBridge | events.AWS\$1region.amazonaws.com | | Amazon FinSpace | finspace.AWS\$1region.amazonaws.com | | Amazon Forecast | forecast.AWS\$1region.amazonaws.com | | Amazon FSx | fsx.AWS\$1region.amazonaws.com | | AWS Glue | glue.AWS\$1region.amazonaws.com | | AWS Ground Station | groundstation.AWS\$1region.amazonaws.com | | Amazon GuardDuty | malware-protection.AWS\$1region.amazonaws.com | | AWS HealthLake | healthlake.AWS\$1region.amazonaws.com | | AWS IoT SiteWise | iotsitewise.AWS\$1region.amazonaws.com | | Amazon Kendra | kendra.AWS\$1region.amazonaws.com | | Amazon Keyspaces (for Apache Cassandra) | cassandra.AWS\$1region.amazonaws.com | | Amazon Kinesis | kinesis.AWS\$1region.amazonaws.com | | Amazon Data Firehose | firehose.AWS\$1region.amazonaws.com | | Amazon Kinesis Video Streams | kinesisvideo.AWS\$1region.amazonaws.com | | AWS Lambda | lambda.AWS\$1region.amazonaws.com | | Amazon Lex | lex.AWS\$1region.amazonaws.com | | AWS License Manager | license-manager.AWS\$1region.amazonaws.com | | Amazon Location Service | geo.AWS\$1region.amazonaws.com | | Amazon Lookout for Equipment | lookoutequipment.AWS\$1region.amazonaws.com | | Amazon Lookout for Metrics | lookoutmetrics.AWS\$1region.amazonaws.com | | Amazon Lookout for Vision | lookoutvision.AWS\$1region.amazonaws.com | | Amazon Macie | macie.AWS\$1region.amazonaws.com | | AWS Mainframe Modernization | m2.AWS\$1region.amazonaws.com | | AWS Mainframe Modernization Application Testing | apptest.AWS\$1region.amazonaws.com | | Amazon Managed Blockchain | managedblockchain.AWS\$1region.amazonaws.com | | Amazon Managed Streaming for Apache Kafka (Amazon MSK) | kafka.AWS\$1region.amazonaws.com | | Amazon Managed Workflows for Apache Airflow (MWAA) | airflow.AWS\$1region.amazonaws.com | | Amazon MemoryDB | memorydb.AWS\$1region.amazonaws.com | | Amazon Monitron | monitron.AWS\$1region.amazonaws.com | | Amazon MQ | mq.AWS\$1region.amazonaws.com | | Amazon Neptune | rds.AWS\$1region.amazonaws.com | | Amazon Nimble Studio | nimble.AWS\$1region.amazonaws.com | | AWS HealthOmics | omics.AWS\$1region.amazonaws.com | | Amazon OpenSearch Service | es.AWS\$1region.amazonaws.com, aoss.AWS\$1region.amazonaws.com | | Amazon OpenSearch Custom Packages | custom-packages.AWS\$1region.amazonaws.com | | AWS Proton | proton.AWS\$1region.amazonaws.com | | Amazon Quantum Ledger Database (Amazon QLDB) | qldb.AWS\$1region.amazonaws.com | | Amazon RDS Performance Insights | rds.AWS\$1region.amazonaws.com | | Amazon Redshift | redshift.AWS\$1region.amazonaws.com | | Amazon Redshift query editor V2 | sqlworkbench.AWS\$1region.amazonaws.com | | Amazon Redshift Serverless | redshift-serverless.AWS\$1region.amazonaws.com | | Amazon Rekognition | rekognition.AWS\$1region.amazonaws.com | | Amazon Relational Database Service (Amazon RDS) | rds.AWS\$1region.amazonaws.com | | Amazon Replicated Data Store | ards.AWS\$1region.amazonaws.com | | Amazon SageMaker AI | sagemaker.AWS\$1region.amazonaws.com | | AWS Secrets Manager | secretsmanager.AWS\$1region.amazonaws.com | | Amazon Security Lake | securitylake.AWS\$1region.amazonaws.com | | Amazon Simple Email Service (Amazon SES) | ses.AWS\$1region.amazonaws.com | | Amazon Simple Notification Service (Amazon SNS) | sns.AWS\$1region.amazonaws.com | | Amazon Simple Queue Service (Amazon SQS) | sqs.AWS\$1region.amazonaws.com | | Amazon Simple Storage Service (Amazon S3) | s3.AWS\$1region.amazonaws.com | | Amazon S3 Tables | s3tables.AWS\$1region.amazonaws.com | | AWS Snowball Edge | importexport.AWS\$1region.amazonaws.com | | AWS Step Functions | states.AWS\$1region.amazonaws.com | | AWS Storage Gateway | storagegateway.AWS\$1region.amazonaws.com | | AWS Systems Manager Incident Manager | ssm-incidents.AWS\$1region.amazonaws.com | | AWS Systems Manager Incident Manager Contacts | ssm-contacts.AWS\$1region.amazonaws.com | | Amazon Timestream | timestream.AWS\$1region.amazonaws.com | | Amazon Translate | translate.AWS\$1region.amazonaws.com | | AWS Verified Access | verified-access.AWS\$1region.amazonaws.com | | Amazon WorkMail | workmail.AWS\$1region.amazonaws.com | | Amazon WorkSpaces | workspaces.AWS\$1region.amazonaws.com | | Amazon WorkSpaces Thin Client | thinclient.AWS\$1region.amazonaws.com | | Amazon WorkSpaces Web | workspaces-web.AWS\$1region.amazonaws.com | | AWS X-Ray | xray.AWS\$1region.amazonaws.com | ## kms:WrappingAlgorithm | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:WrappingAlgorithm` | String | Single-valued | `GetParametersForImport` | Key policies and IAM policies | This condition key controls access to the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) operation based on the value of the [WrappingAlgorithm](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html#KMS-GetParametersForImport-request-WrappingAlgorithm) parameter in the request. You can use this condition to require principals to use a particular algorithm to encrypt key material during the import process. Requests for the required public key and import token fail when they specify a different wrapping algorithm. The following example key policy statement uses the `kms:WrappingAlgorithm` condition key to give the example user permission to call the `GetParametersForImport` operation, but prevents them from using the `RSAES_OAEP_SHA_1` wrapping algorithm. When the `WrappingAlgorithm` in the `GetParametersForImport` request is `RSAES_OAEP_SHA_1`, the operation fails. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:GetParametersForImport", "Resource": "*", "Condition": { "StringNotEquals": { "kms:WrappingAlgorithm": "RSAES_OAEP_SHA_1" } } } ``` **See also** + [kms:ExpirationModel](#conditions-kms-expiration-model) + [kms:ValidTo](#conditions-kms-valid-to) + [kms:WrappingKeySpec](#conditions-kms-wrapping-key-spec) ## kms:WrappingKeySpec | AWS KMS condition keys | Condition type | Value type | API operations | Policy type | | --- | --- | --- | --- | --- | | `kms:WrappingKeySpec` | String | Single-valued | `GetParametersForImport` | Key policies and IAM policies | This condition key controls access to the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) operation based on the value of the [WrappingKeySpec](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html#KMS-GetParametersForImport-request-WrappingKeySpec) parameter in the request. You can use this condition to require principals to use a particular type of public key during the import process. If the request specifies a different key type, it fails. Because the only valid value for the `WrappingKeySpec` parameter value is `RSA_2048`, preventing users from using this value effectively prevents them from using the `GetParametersForImport` operation. The following example policy statement uses the `kms:WrappingAlgorithm` condition key to require that the `WrappingKeySpec` in the request is `RSA_4096`. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleRole" }, "Action": "kms:GetParametersForImport", "Resource": "*", "Condition": { "StringEquals": { "kms:WrappingKeySpec": "RSA_4096" } } } ``` **See also** + [kms:ExpirationModel](#conditions-kms-expiration-model) + [kms:ValidTo](#conditions-kms-valid-to) + [kms:WrappingAlgorithm](#conditions-kms-wrapping-algorithm) # AWS KMS condition keys for attested platforms AWS KMS provides condition keys to support cryptographic attestation for [AWS Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/) and NitroTPM. AWS Nitro Enclaves is an Amazon EC2 capability that lets you create isolated compute environments called [enclaves](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-concepts.html#term-enclave) to protect and process highly sensitive data. NitroTPM extends similar attestation functionality to EC2 instances. When you call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), or [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) API operations with a signed attestation document, these APIs encrypt the plaintext in the response under the public key from the attestation document, and return ciphertext instead of plaintext. This ciphertext can be decrypted only by using the private key in the enclave. For more information, see [Cryptographic attestation support in AWS KMS](cryptographic-attestation.md). **Note** If you don't provide a key policy when you create an AWS KMS key, AWS creates one for you. This [default key policy](key-policy-default.md) grants the AWS accounts that own the KMS key full access to the key and allows the account to use IAM policies to allow access to the key. This policy allows all actions like [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). AWS recommends applying principal of [Least-privilege permissions](least-privilege.md) to your KMS key policies. You can also restrict access by [modifying the KMS key policy](key-policy-modifying.md) action for `kms:*` to `[NotAction:](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notaction.html)kms:Decrypt`. The following condition keys let you limit the permissions for these operations based on the contents of the signed attestation document. Before allowing an operation, AWS KMS compares the attestation document to the values in these AWS KMS condition keys. # Condition keys for Nitro Enclaves The following condition keys are specific to Nitro Enclaves attestation: ## kms:RecipientAttestation:ImageSha384 | AWS KMS Condition Keys | Condition Type | Value type | API Operations | Policy Type | | --- | --- | --- | --- | --- | | `kms:RecipientAttestation:ImageSha384` | String | Single-valued | `Decrypt` `DeriveSharedSecret` `GenerateDataKey` `GenerateDataKeyPair` `GenerateRandom` | Key policies and IAM policies | The `kms:RecipientAttestation:ImageSha384` condition key controls access to `Decrypt`, `DeriveSharedSecret`, `GenerateDataKey`, `GenerateDataKeyPair`, and `GenerateRandom` with a KMS key when the image digest from the signed attestation document in the request matches the value in the condition key. The `ImageSha384` value corresponds to PCR0 in the attestation document. This condition key is effective only when the `Recipient` parameter in the request specifies a signed attestation document for an AWS Nitro enclave. This value is also included in [CloudTrail events](ct-nitro-enclave.md) for requests to AWS KMS for Nitro enclaves. For example, the following key policy statement allows the `data-processing` role to use the KMS key for [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), and [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) operations. The `kms:RecipientAttestation:ImageSha384` condition key allows the operations only when the image digest value (PCR0) of the attestation document in the request matches the image digest value in the condition. This condition key is effective only when the `Recipient` parameter in the request specifies a signed attestation document for an AWS Nitro enclave. If the request does not include a valid attestation document from an AWS Nitro enclave, permission is denied because this condition is not satisfied. ``` { "Sid" : "Enable enclave data processing", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:role/data-processing" }, "Action": [ "kms:Decrypt", "kms:DeriveSharedSecret", "kms:GenerateDataKey", "kms:GenerateDataKeyPair", "kms:GenerateRandom" ], "Resource" : "*", "Condition": { "StringEqualsIgnoreCase": { "kms:RecipientAttestation:ImageSha384": "9fedcba8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef1abcdef0abcdef1abcdef2abcdef3abcdef4abcdef5abcdef6abcdef7abcdef99" } } } ``` ## kms:RecipientAttestation:PCR | AWS KMS Condition Keys | Condition Type | Value type | API Operations | Policy Type | | --- | --- | --- | --- | --- | | `kms:RecipientAttestation:PCR` | String | Single-valued | `Decrypt` `DeriveSharedSecret` `GenerateDataKey` `GenerateDataKeyPair` `GenerateRandom` | Key policies and IAM policies | The `kms:RecipientAttestation:PCR` condition key controls access to `Decrypt`, `DeriveSharedSecret`, `GenerateDataKey`, `GenerateDataKeyPair`, and `GenerateRandom` with a KMS key only when the platform configuration registers (PCRs) from the signed attestation document in the request match the PCRs in the condition key. This condition key is effective only when the `Recipient` parameter in the request specifies a signed attestation document from an AWS Nitro enclave. This value is also included in [CloudTrail events](ct-nitro-enclave.md) that represent requests to AWS KMS for Nitro enclaves. To specify a PCR value, use the following format. Concatenate the PCR ID to the condition key name. You can specify a PCR ID that identifies one of the [six enclave measurements](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html#where) or a custom PCR ID that you defined for a specific use case. The PCR value must be a lower-case hexadecimal string of up to 96 bytes. ``` "kms:RecipientAttestation:PCRPCR_ID": "PCR_value" ``` For example, the following condition key specifies a particular value for PCR1, which corresponds to the hash of the kernel used for the enclave and the bootstrap process. ``` kms:RecipientAttestation:PCR1: "abc1abcdef2abcdef3abcdef4abcdef5abcdef6abcdef7abcdef8abcdef9abcdef8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef0abcde" ``` The following example key policy statement allows the `data-processing` role to use the KMS key for the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. The `kms:RecipientAttestation:PCR` condition key in this statement allows the operation only when the PCR1 value in the signed attestation document in the request matches `kms:RecipientAttestation:PCR1` value in the condition. Use the `StringEqualsIgnoreCase` policy operator to require a case-insensitive comparison of the PCR values. If the request does not include an attestation document, permission is denied because this condition is not satisfied. ``` { "Sid" : "Enable enclave data processing", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:role/data-processing" }, "Action": "kms:Decrypt", "Resource" : "*", "Condition": { "StringEqualsIgnoreCase": { "kms:RecipientAttestation:PCR1": "abc1de4f2dcf774f6e3b679f62e5f120065b2e408dcea327bd1c9dddaea6664e7af7935581474844767453082c6f1586116376cede396a30a39a611b9aad7966c87" } } } ``` # Condition keys for NitroTPM The following condition keys are specific to NitroTPM attestation: ## kms:RecipientAttestation:NitroTPMPCR | AWS KMS Condition Keys | Condition Type | Value type | API Operations | Policy Type | | --- | --- | --- | --- | --- | | `kms:RecipientAttestation:NitroTPMPCR` | String | Single-valued | `Decrypt` `DeriveSharedSecret` `GenerateDataKey` `GenerateDataKeyPair` `GenerateRandom` | Key policies and IAM policies | The `kms:RecipientAttestation:NitroTPMPCR` condition key controls access to `Decrypt`, `DeriveSharedSecret`, `GenerateDataKey`, `GenerateDataKeyPair`, and `GenerateRandom` with a KMS key only when the platform configuration registers (PCRs) from the signed attestation document in the request match the PCRs in the condition key. This condition key is effective only when the `Recipient` parameter in the request specifies a signed attestation document from NitroTPM. This value is also included in [CloudTrail events](ct-nitro-tpm.md) that represent requests to AWS KMS for NitroTPM. To specify a PCR value, use the following format. Concatenate the PCR ID to the condition key name. The PCR value must be a lower-case hexadecimal string of up to 96 bytes. ``` "kms:RecipientAttestation:NitroTPMPCRPCR_ID": "PCR_value" ``` For example, the following condition key specifies a particular value for PCR4: ``` kms:RecipientAttestation:NitroTPMPCR4: "abc1abcdef2abcdef3abcdef4abcdef5abcdef6abcdef7abcdef8abcdef9abcdef8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef0abcde" ``` The following example key policy statement allows the `data-processing` role to use the KMS key for the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. The `kms:RecipientAttestation:NitroTPMPCR` condition key in this statement allows the operation only when the PCR4 value in the signed attestation document in the request matches `kms:RecipientAttestation:NitroTPMPCR4` value in the condition. Use the `StringEqualsIgnoreCase` policy operator to require a case-insensitive comparison of the PCR values. If the request does not include an attestation document, permission is denied because this condition is not satisfied. ``` { "Sid" : "Enable NitroTPM data processing", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:role/data-processing" }, "Action": "kms:Decrypt", "Resource" : "*", "Condition": { "StringEqualsIgnoreCase": { "kms:RecipientAttestation:NitroTPMPCR4": "abc1de4f2dcf774f6e3b679f62e5f120065b2e408dcea327bd1c9dddaea6664e7af7935581474844767453082c6f1586116376cede396a30a39a611b9aad7966c87" } } } ``` # Least-privilege permissions Since your KMS keys protect sensitive information, we recommend following the principle of least-privileged access. Delegate the minimum permissions required to perform a task when you define your key policies. Only allow all actions (`kms:*`) on a KMS key policy if you plan to further restrict permissions with additional IAM policies. If you plan to manage permissions with IAM policies, limit who has the ability to create and attach IAM policies to IAM principals and [monitor for policy changes](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudwatch-alarms-for-cloudtrail.html#cloudwatch-alarms-for-cloudtrail-iam-policy-changes). If you allow all actions (`kms:*`) in both the key policy and the IAM policy, the principal has both administrative and usage permissions to the KMS key. As a security best practice, we recommend only delegating these permissions to specific principals. You can do this by explicitly naming the principal in the key policy or by limiting which principals the IAM policy is attached to. You can also use [condition keys](policy-conditions.md) to restrict permissions. For example, you can use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principaltag](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principaltag) to allow all actions if the principal making the API call has the tag specified in the condition rule. For help understanding how policy statements are evaluated in AWS, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. We recommend reviewing this topic before writing policies to reduce the chance that your policy has unintended effects, such as providing access to principals that should not have access. **Tip** When testing an application in a non-production envrionment, use [IAM Access Analyzer](https://aws.amazon.com/iam/features/analyze-access/) to help you apply least-privileges to your IAM policies. If you use IAM users instead of IAM roles, we strongly recommend enabling AWS [multi-factor authentication](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) (MFA) to mitigate the vulnerability of long-term credentials. You can use MFA to do the following: + Require that users validate their credentials with MFA before performing privileged actions, such as scheduling key deletion. + Split ownership of an administrator account password and MFA device between individuals to implement split authorization. **Learn more** + [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) + [Techniques for writing least privilege IAM policies](https://aws.amazon.com//blogs/security/techniques-for-writing-least-privilege-iam-policies/) ## Implementing least privileged permissions When you give an AWS service permission to use a KMS key, ensure that the permission is valid only for the resources that the service must access on your behalf. This least privilege strategy helps to prevent unauthorized use of a KMS key when requests are passed between AWS services. To implement a least privilege strategy, use we recommend using AWS KMS encryption context condition keys and the global source ARN or source account condition keys. ### Using encryption context condition keys The most effective way to implement least privileged permissions when using AWS KMS resources is to include the [kms:EncryptionContext:*context-key*](conditions-kms.md#conditions-kms-encryption-context) or [kms:EncryptionContextKeys](conditions-kms.md#conditions-kms-encryption-context-keys) condition keys in the policy that allows principals to call AWS KMS cryptographic operations. These condition keys are particularly effective because they associate the permission with the [encryption context](encrypt_context.md) that is bound to the ciphertext when the resource is encrypted. Use encryption context conditions keys only when the action in the policy statement is [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) or an AWS KMS symmetric cryptographic operation that takes an `EncryptionContext` parameter, such as the operations like [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) or [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). (For a list of supported operations, see [kms:EncryptionContext:*context-key*](conditions-kms.md#conditions-kms-encryption-context) or [kms:EncryptionContextKeys](conditions-kms.md#conditions-kms-encryption-context-keys).) If you use these condition keys to allow other operations, such as [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), permission will be denied. Set the value to the encryption context that the service uses when it encrypts the resource. This information is typically available in the Security chapter of the service documentation. For example, the [encryption context for AWS Proton](https://docs.aws.amazon.com/proton/latest/adminguide/data-protection.html#encryption-context) identifies the AWS Proton resource and its associated template. The [AWS Secrets Manager encryption context](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html#security-encryption-encryption-context) identifies the secret and its version. The [encryption context for Amazon Location](https://docs.aws.amazon.com/location/latest/developerguide/encryption-at-rest.html#location-encryption-context) identifies the tracker or collection. The following example key policy statement allows Amazon Location Service to create grants on behalf of authorized users. This policy statement limits the permission by using the [kms:ViaService](conditions-kms.md#conditions-kms-via-service), [kms:CallerAccount](conditions-kms.md#conditions-kms-caller-account), and `kms:EncryptionContext:context-key` condition keys to tie the permission to a particular tracker resource. ``` { "Sid": "Allow Amazon Location to create grants on behalf of authorized users", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/LocationTeam" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": "geo.us-west-2.amazonaws.com", "kms:CallerAccount": "111122223333", "kms:EncryptionContext:aws:geo:arn": "arn:aws:geo:us-west-2:111122223333:tracker/SAMPLE-Tracker" } } } ``` ### Using `aws:SourceArn` or `aws:SourceAccount` condition keys When the principal in a key policy statement is an [AWS service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), we strongly recommend that you use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) or [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition keys, in addition to the `kms:EncryptionContext:context-key` condition key. The ARN and account values are included in the authorization context only when a request comes to AWS KMS from another AWS service. This combination of conditions implements least privileged permissions and avoids a potential [confused deputy scenario](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). Service principals are not typically used as principals in a key policy, but some AWS services, such as AWS CloudTrail, require it. To use the `aws:SourceArn` or `aws:SourceAccount` global condition keys, set the value to the Amazon Resource Name (ARN) or account of the resource that is being encrypted. For example, in a key policy statement that gives AWS CloudTrail permission to encrypt a trail, set the value of `aws:SourceArn` to the ARN of the trail. Whenever possible, use `aws:SourceArn`, which is more specific. Set the value to the ARN or an ARN pattern with wildcard characters. If you don't know the ARN of the resource, use `aws:SourceAccount` instead. **Note** If a resource ARN includes characters that are not permitted in an AWS KMS key policy, you cannot use that resource ARN in the value of the `aws:SourceArn` condition key. Instead, use the `aws:SourceAccount` condition key. For details about key policy document rules, see [Key policy format](key-policy-overview.md#key-policy-format). In the following example key policy, the principal who gets the permissions is the AWS CloudTrail service principal, `cloudtrail.amazonaws.com`. To implement least privilege, this policy uses the `aws:SourceArn` and `kms:EncryptionContext:context-key` condition keys. The policy statement allows CloudTrail to use the KMS key to [generate the data key](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) that it uses to encrypt a trail. The `aws:SourceArn` and `kms:EncryptionContext:context-key` conditions are evaluated independently. Any request to use the KMS key for the specified operation must satisfy both conditions. To restrict the service's permission to the `finance` trail in the example account (111122223333) and `us-west-2` Region, this policy statement sets the `aws:SourceArn` condition key to the ARN of a particular trail. The condition statement uses the [ArnEquals](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_ARN) operator to ensure that every element in the ARN is evaluated independently when matching. The example also uses the `kms:EncryptionContext:context-key` condition key to limit the permission to trails in a particular account and Region. Before using this key policy, replace the example account ID, Region, and trail name with valid values from your account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudTrailToEncryptLogs", "Effect": "Allow", "Principal": { "Service": "cloudtrail.amazonaws.com" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ArnEquals": { "aws:SourceArn": [ "arn:aws:cloudtrail:us-west-2:111122223333:trail/finance" ] }, "StringLike": { "kms:EncryptionContext:aws:cloudtrail:arn": [ "arn:aws:cloudtrail:*:111122223333:trail/*" ] } } } ] } ``` ------ # ABAC for AWS KMS Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes. AWS KMS supports ABAC by allowing you to control access to your customer managed keys based on the tags and aliases associated with the KMS keys. The tag and alias condition keys that enable ABAC in AWS KMS provide a powerful and flexible way to authorize principals to use KMS keys without editing policies or managing grants. But you should use these feature with care so principals aren't inadvertently allowed or denied access. If you use ABAC, be aware that permission to manage tags and aliases is now an access control permission. Be sure that you know the existing tags and aliases on all KMS keys before you deploy a policy that depends on tags or aliases. Take reasonable precautions when adding, deleting, and updating aliases, and when tagging and untagging keys. Give permissions to manage tags and aliases only to principals who need them, and limit the tags and aliases they can manage. **Notes** When using ABAC for AWS KMS, be cautious about giving principals permission to manage tags and aliases. Changing a tag or alias might allow or deny permission to a KMS key. Key administrators who don't have permission to change key policies or create grants can control access to KMS keys if they have permission to manage tags or aliases. It might take up to five minutes for tag and alias changes to affect KMS key authorization. Recent changes might be visible in API operations before they affect authorization. To control access to a KMS key based on its alias, you must use a condition key. You cannot use an alias to represent a KMS key in the `Resource` element of a policy statement. When an alias appears in the `Resource` element, the policy statement applies to the alias, not to the associated KMS key. **Learn more** + For details about AWS KMS support for ABAC, including examples, see [Use aliases to control access to KMS keys](alias-authorization.md) and [Use tags to control access to KMS keys](tag-authorization.md). + For more general information about using tags to control access to AWS resources, see [What is ABAC for AWS?](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) and [Controlling Access to AWS Resources Using Resource Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*. ## ABAC condition keys for AWS KMS To authorize access to KMS keys based on their tags and aliases, use the following condition keys in a key policy or IAM policy. | ABAC condition key | Description | Policy type | AWS KMS operations | | --- | --- | --- | --- | | [aws:ResourceTag](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag) | Tag (key and value) on the KMS key matches the tag (key and value) or tag pattern in the policy | IAM policy only | KMS key resource operations 2 | | [aws:RequestTag/*tag-key*](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-requesttag) | Tag (key and value) in the request matches the tag (key and value) or tag pattern in the policy | Key policy and IAM policies1 | [TagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html), [UntagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_UntagResource.html) | | [aws:TagKeys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-tagkeys) | Tag keys in the request match the tag keys in the policy | Key policy and IAM policies1 | [TagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html), [UntagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_UntagResource.html) | | [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) | Aliases associated with the KMS key match the aliases or alias patterns in the policy | IAM policy only | KMS key resource operations 2 | | [kms:RequestAlias](conditions-kms.md#conditions-kms-request-alias) | Alias that represents the KMS key in the request matches the alias or alias patterns in the policy. | Key policy and IAM policies1 | [Cryptographic operations](kms-cryptography.md#cryptographic-operations), [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) | 1Any condition key that can be used in a key policy can also be used in an IAM policy, but only if [the key policy allows it](key-policy-default.md#key-policy-default-allow-root-enable-iam). 2A *KMS key resource operation* is an operation authorized for a particular KMS key. To identify the KMS key resource operations, in the [AWS KMS permissions table](kms-api-permissions-reference.md#kms-api-permissions-reference-table), look for a value of KMS key in the `Resources` column for the operation. For example, you can use these condition keys to create the following policies. + An IAM policy with `kms:ResourceAliases` that allows permission to use KMS keys with a particular alias or alias pattern. This is a bit different from policies that rely on tags: Although you can use alias patterns in a policy, each alias must be unique in an AWS account and Region. This allows you to apply a policy to a select set of KMS keys without listing the key ARNs of the KMS keys in the policy statement. To add or remove KMS keys from the set, change the alias of the KMS key. + A key policy with `kms:RequestAlias` that allows principals to use a KMS key in a `Encrypt` operation, but only when the `Encrypt` request uses that alias to identify the KMS key. + An IAM policy with `aws:ResourceTag/tag-key` that denies permission to use KMS keys with a particular tag key and tag value. This lets you apply a policy to a select set of KMS keys without listing the key ARNs of the KMS keys in the policy statement. To add or remove KMS keys from the set, tag or untag the KMS key. + An IAM policy with `aws:RequestTag/tag-key` that allows principals to delete only `"Purpose"="Test"` KMS key tags. + An IAM policy with `aws:TagKeys` that denies permission to tag or untag a KMS key with a `Restricted` tag key. ABAC makes access management flexible and scalable. For example, you can use the `aws:ResourceTag/tag-key` condition key to create an IAM policy that allows principals to use a KMS key for specified operations only when the KMS key has a `Purpose=Test` tag. The policy applies to all KMS keys in all Regions of the AWS account. When attached to a user or role, the following IAM policy allows principals to use all existing KMS keys with a `Purpose=Test` tag for the specified operations. To provide this access to new or existing KMS keys, you don't need to change the policy. Just attach the `Purpose=Test` tag to the KMS keys. Similarly, to remove this access from KMS keys with a `Purpose=Test` tag, edit or delete the tag. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AliasBasedIAMPolicy", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "arn:aws:kms:*:111122223333:key/*", "Condition": { "StringEquals": { "aws:ResourceTag/Purpose": "Test" } } } ] } ``` ------ However, if you use this feature, be careful when managing tags and aliases. Adding, changing, or deleting a tag or alias can inadvertently allow or deny access to a KMS key. Key administrators who don't have permission to change key policies or create grants can control access to KMS keys if they have permission to manage tags and aliases. To mitigate this risk, consider [limiting permissions to manage tags](tag-permissions.md#tag-permissions-conditions) and [aliases](alias-access.md#alias-access-limiting). For example, you might want to allow only select principals to manage `Purpose=Test` tags. For details, see [Use aliases to control access to KMS keys](alias-authorization.md) and [Use tags to control access to KMS keys](tag-authorization.md). ## Tags or aliases? AWS KMS supports ABAC with tags and aliases. Both options provide a flexible, scalable access control strategy, but they're slightly different from each other. You might decide to use tags or use aliases based on your particular AWS use patterns. For example, if you have already given tagging permissions to most administrators, it might be easier to control an authorization strategy based on aliases. Or, if you are close to the quota for [aliases per KMS key](resource-limits.md#aliases-per-key), you might prefer an authorization strategy based on tags. The following benefits are of general interest. ** Benefits of tag-based access control** + Same authorization mechanism for different types of AWS resources. You can use the same tag or tag key to control access to multiple resource types, such as an Amazon Relational Database Service (Amazon RDS) cluster, an Amazon Elastic Block Store (Amazon EBS) volume, and a KMS key. This feature enables several different authorization models that are more flexible than traditional role-based access control. + Authorize access to a group of KMS keys. You can use tags to manage access to a group of KMS keys in the same AWS account and Region. Assign the same tag or tag key to the KMS keys that you choose. Then create a simple, easy-to-maintain policy statement that is based on the tag or tag key. To add or remove a KMS key from your authorization group, add or remove the tag; you don't need to edit the policy. **Benefits of alias-based access control** + Authorize access to cryptographic operations based on aliases. Most request-based policy conditions for attributes, including [aws:RequestTag/*tag-key*](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-requesttag), affect only operations that add, edit, or delete the attribute. But the [kms:RequestAlias](conditions-kms.md#conditions-kms-request-alias) condition key controls access to cryptographic operations based on the alias used to identify the KMS key in the request. For example, you can give a principal permission to use a KMS key in a `Encrypt` operation but only when the value of the `KeyId` parameter is `alias/restricted-key-1`. To satisfy this condition requires all of the following: + The KMS key must be associated with that alias. + The request must use the alias to identify the KMS key. + The principal must have permission to use the KMS key subject to the `kms:RequestAlias` condition. This is particularly useful if your applications commonly use alias names or alias ARNs to refer to KMS keys. + Provide very limited permissions. An alias must be unique in an AWS account and Region. As a result, giving principals access to a KMS key based on an alias can be much more restrictive than giving them access based on a tag. Unlike aliases, tags can be assigned to multiple KMS keys in the same account and Region. If you choose, you can use an alias pattern, such as `alias/test*`, to give principals access to a group of KMS keys in the same account and Region. However, allowing or denying access to a particular alias allows very strict control on KMS keys. # Troubleshooting ABAC for AWS KMS Controlling access to KMS keys based on their tags and aliases is convenient and powerful. However, it's prone to a few predictable errors that you'll want to prevent. ## Access changed due to tag change If a tag is deleted or its value is changed, principals who have access to a KMS key based only on that tag will be denied access to the KMS key. This can also happen when a tag that is included in a deny policy statement is added to a KMS key. Adding a policy-related tag to a KMS key can allow access to principals who should be denied access to a KMS key. For example, suppose that a principal has access to a KMS key based on the `Project=Alpha` tag, such as the permission provided by the following example IAM policy statement. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "IAMPolicyWithResourceTag", "Effect": "Allow", "Action": [ "kms:GenerateDataKeyWithoutPlaintext", "kms:Decrypt" ], "Resource": "arn:aws:kms:ap-southeast-1:111122223333:key/*", "Condition": { "StringEquals": { "aws:ResourceTag/Project": "Alpha" } } } ] } ``` ------ If the tag is deleted from that KMS key or the tag value is changed, the principal no longer has permission to use the KMS key for the specified operations. This might become evident when the principal tries to read or write data in an AWS service that uses a customer managed key To trace the tag change, review your CloudTrail logs for [TagResource](ct-tagresource.md) or [UntagResource entries](ct-untagresource.md). To restore access without updating the policy, change the tags on the KMS key. This action has minimal impact other than a brief period while it is taking effect throughout AWS KMS. To prevent an error like this one, give tagging and untagging permissions only to principals who need it and [limit their tagging permissions](tag-permissions.md#tag-permissions-conditions) to tags they need to manage. Before changing a tag, search policies to detect access that depends on the tag, and get KMS keys in all Regions that have the tag. You might consider creating an Amazon CloudWatch alarm when particular tags are changed. ## Access change due to alias change If an alias is deleted or associated with a different KMS key, principals who have access to the KMS key based only on that alias will be denied access to the KMS key. This can also happen when an alias that is associated with a KMS key is included in a deny policy statement. Adding a policy-related alias to a KMS key can also allow access to principals who should be denied access to a KMS key. For example, the following IAM policy statement uses the [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition key to allow access to KMS keys in different Regions of the account with any of the specified aliases. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AliasBasedIAMPolicy", "Effect": "Allow", "Action": [ "kms:List*", "kms:Describe*", "kms:Decrypt" ], "Resource": "arn:aws:kms:*:111122223333:key/*", "Condition": { "ForAnyValue:StringEquals": { "kms:ResourceAliases": [ "alias/ProjectAlpha", "alias/ProjectAlpha_Test", "alias/ProjectAlpha_Dev" ] } } } ] } ``` ------ To trace the alias change, review your CloudTrail logs for [CreateAlias](ct-createalias.md), [UpdateAlias](ct-updatealias.md), and [DeleteAlias](ct-deletealias.md) entries. To restore access without updating the policy, change the alias associated with the KMS key. Because each alias can be associated with only one KMS key in an account and Region, managing aliases is a bit more difficult than managing tags. Restoring access to some principals on one KMS key can deny the same or other principals access to a different KMS key. To prevent this error, give alias management permissions only to principals who need it and [limit their alias-management permissions](alias-access.md#alias-access-limiting) to aliases they need to manage. Before updating or deleting an alias, search policies to detect access that depends on the alias, and find KMS keys in all Regions that are associated with the alias. ## Access denied due to alias quota Users who are authorized to use a KMS key by an [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition will get an `AccessDenied` exception if the KMS key exceeds the default [aliases per KMS key](resource-limits.md#aliases-per-key) quota for that account and Region. To restore access, delete aliases that are associated with the KMS key so it complies with the quota. Or use an alternate mechanism to give users access to the KMS key. ## Delayed authorization change Changes that you make to tags and aliases might take up to five minutes to affect the authorization of KMS keys. As a result, a tag or alias change might be reflected in the responses from API operations before they affect authorization. This delay is likely to be longer than the brief eventual consistency delay that affects most AWS KMS operations. For example, you might have an IAM policy that allows certain principals to use any KMS key with a `"Purpose"="Test"` tag. Then you add the `"Purpose"="Test"` tag to a KMS key. Although the [TagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) operation completes and [ListResourceTags](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListResourceTags.html) response confirms that the tag is assigned to the KMS key, the principals might not have access to the KMS key for up to five minutes. To prevent errors, build this expected delay into your code. ## Failed requests due to alias updates When you update an alias, you associate an existing alias with a different KMS key. [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) and [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) requests that specify the [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) might fail because the alias is now associated with a KMS key that didn't encrypt the ciphertext. This situation typically returns an `IncorrectKeyException` or `NotFoundException`. Or if the request has no `KeyId` or `DestinationKeyId` parameter, the operation might fail with `AccessDenied` exception because the caller no longer has access to the KMS key that encrypted the ciphertext. You can trace the change by looking at CloudTrail logs for [CreateAlias](ct-createalias.md), [UpdateAlias](ct-updatealias.md), and [DeleteAlias](ct-deletealias.md) log entries. You can also use the value of the `LastUpdatedDate` field in the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) response to detect a change. For example, the following [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) example response shows that the `ProjectAlpha_Test` alias in the `kms:ResourceAliases` condition was updated. As a result, the principals who have access based on the alias lose access to the previously associated KMS key. Instead, they have access to the newly associated KMS key. ``` $ aws kms list-aliases --query 'Aliases[?starts_with(AliasName, `alias/ProjectAlpha`)]' { "Aliases": [ { "AliasName": "alias/ProjectAlpha_Test", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ProjectAlpha_Test", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "CreationDate": 1566518783.394, "LastUpdatedDate": 1605308931.903 }, { "AliasName": "alias/ProjectAlpha_Restricted", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ProjectAlpha_Restricted", "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1553410800.010, "LastUpdatedDate": 1553410800.010 } ] } ``` The remedy for this change isn't simple. You can update the alias again to associate it with the original KMS key. However, before you act, you need to consider the effect of that change on the currently associated KMS key. If principals used the latter KMS key in cryptographic operations, they might need continued access to it. In this case, you might want to update the policy to ensure that principals have permission to use both of the KMS keys. You can prevent an error like this one: Before updating an alias, search policies to detect access that depends on the alias. Then get KMS keys in all Regions that are associated with the alias. Give alias management permissions only to principals who need it and [limit their alias-management permissions](alias-access.md#alias-access-limiting) to aliases they need to manage. # RBAC for AWS KMS Role-based access control (RBAC) is an authorization strategy that only provides users with the permissions required to perform their job duties, and nothing more. AWS KMS supports RBAC by allowing you to control access to your keys by specifying granular permissions on key usage within [key policies](key-policies.md). Key policies specify a resource, action, effect, principal, and optional conditions to grant access to keys. To implement RBAC in AWS KMS, we recommend separating the permissions for key users and key administrators. ------ #### [ Key users ] The following key policy example allows the `ExampleUserRole` IAM role to use the KMS key. ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleUserRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" } ``` Your key users might need fewer permissions than the user in this example. Only assign the permissions that the user needs. Use the following questions to help you further refine permissions. + Which IAM principals (roles or users) need access to the key? + Which actions does each principal need to perform with the key? For example, does the principal only need Encrypt and Sign permissions? + Is the user a human or an AWS service? If it's an AWS service, you can use the [condition key](conditions-kms.md#conditions-kms-via-service) to restrict key usage to a specific AWS service. ------ #### [ Key administrators ] The following key policy example allows the `ExampleAdminRole` IAM role to administer the KMS key. ``` { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleAdminRole" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" } ``` Your key administrators might need fewer permissions than the administrator in this example. Only assign the permissions that your key administrators need. ------ Only give users the permissions they need to fulfill their roles. A user's permissions might vary depending on whether the key is used in test or production environments. If you use less restrictive permissions in certain non-production environments, implement a process to test the policies before they're released to production. **Learn more** + [IAM identities (users, user groups, and roles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) + [Types of access control](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-api-access-authorization/access-control-types.html) # Allowing users in other accounts to use a KMS key You can allow users or roles in a different AWS account to use a KMS key in your account. Cross-account access requires permission in the key policy of the KMS key and in an IAM policy in the external user's account. Cross-account permission is effective only for the following operations: + [Cryptographic operations](kms-cryptography.md#cryptographic-operations) + [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) + [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) + [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) + [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) + [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) + [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) + [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) If you give a user in a different account permission for other operations, those permissions have no effect. For example, if you give a principal in a different account [kms:ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) permission in an IAM policy, or [kms:ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) permission on a KMS key in a key policy, the user's attempts to call those operations on your resources still fail. For details about using KMS keys in different accounts for AWS KMS operations, see the **Cross-account use** column in the [AWS KMS permissions](kms-api-permissions-reference.md) and [Using KMS keys in other accounts](#cross-account-use). There is also a **Cross-account use** section in each API description in the [AWS Key Management Service API Reference](https://docs.aws.amazon.com/kms/latest/APIReference/). **Warning** Be cautious about giving principals permissions to use your KMS keys. Whenever possible, follow the *least privilege* principle. Give users access only to the KMS keys they need for only the operations they require. Also, be cautious about using any unfamiliar KMS key, especially a KMS key in a different account. Malicious users might give you permissions to use their KMS key to get information about you or your account. For information about using policies to protect the resources in your account, see [Best practices for IAM policies](iam-policies-best-practices.md). To give permission to use a KMS key to users and roles in another account, you must use two different types of policies: + The **key policy** for the KMS key must give the external account (or users and roles in the external account) permission to use the KMS key. The key policy is in the account that owns the KMS key. + **IAM policies** in the external account must delegate the key policy permissions to its users and roles. These policies are set in the external account and give permissions to users and roles in that account. The key policy determines who *can* have access to the KMS key. The IAM policy determines who *does* have access to the KMS key. Neither the key policy nor the IAM policy alone is sufficient—you must change both. To edit the key policy, you can use the [Policy View](key-policy-modifying.md#key-policy-modifying-how-to-console-policy-view) in the AWS Management Console or use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) or [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operations. For help with editing IAM policies, see [Using IAM policies with AWS KMS](iam-policies.md). For an example that shows how the key policy and IAM policies work together to allow use of a KMS key in a different account, see [Example 2: User assumes role with permission to use a KMS key in a different AWS account](policy-evaluation.md#example-cross-acct). You can view the resulting cross-account AWS KMS operations on the KMS key in your [AWS CloudTrail logs](logging-using-cloudtrail.md). Operations that use KMS keys in other accounts are logged in both the caller's account and the KMS key owner account. **Topics** + [ ## Step 1: Add a key policy statement in the local account ](#cross-account-key-policy) + [ ## Step 2: Add IAM policies in the external account ](#cross-account-iam-policy) + [ ## Allowing use of external KMS keys with AWS services ](#cross-account-service) + [ ## Using KMS keys in other accounts ](#cross-account-use) **Note** The examples in this topic show how to use a key policy and IAM policy together to provide and limit access to a KMS key. These generic examples are not intended to represent the permissions that any particular AWS service requires on a KMS key. For information about the permissions that an AWS service requires, see the encryption topic in the service documentation. ## Step 1: Add a key policy statement in the local account The key policy for a KMS key is the primary determinant of who can access the KMS key and which operations they can perform. The key policy is always in the account that owns the KMS key. Unlike IAM policies, key policies do not specify a resource. The resource is the KMS key that is associated with the key policy. When providing cross-account permission, the key policy for the KMS key must give the external account (or users and roles in the external account) permission to use the KMS key. To give an external account permission to use the KMS key, add a statement to the key policy that specifies the external account. In the `Principal` element of the key policy, enter the Amazon Resource Name (ARN) of the external account. When you specify an external account in a key policy, IAM administrators in the external account can use IAM policies to delegate those permissions to any users and roles in the external account. They can also decide which of the actions specified in the key policy the users and roles can perform. Permissions given to the external account and its principals are effective only if the external account is enabled in the Region that hosts the KMS key and its key policy. For information about Regions that are not enabled by default ("opt-in Regions"), see [Managing AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the *AWS General Reference*. For example, suppose you want to allow account `444455556666` to use a symmetric encryption KMS key in account `111122223333`. To do that, add a policy statement like the one in the following example to the key policy for the KMS key in account `111122223333`. This policy statement gives the external account, `444455556666`, permission to use the KMS key in cryptographic operations for symmetric encryption KMS keys. **Note** The following example represents a sample key policy for sharing a KMS key with another account. Replace the example `Sid`, `Principal`, and `Action` values with valid values for the intended use of your KMS key. ``` { "Sid": "Allow an external account to use this KMS key", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::444455556666:root" ] }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" } ``` Instead of giving permission to the external account, you can specify particular external users and roles in the key policy . However, those users and roles cannot use the KMS key until IAM administrators in the external account attach the proper IAM policies to their identities. The IAM policies can give permission to all or a subset of the external users and roles that are specified in the key policy. And they can allow all or a subset of the actions specified in the key policy. Specifying identities in a key policy restricts the permissions that IAM administrators in the external account can provide. However, it makes policy management with two accounts more complex. For example, assume that you need to add a user or role. You must add that identity to the key policy in the account that owns the KMS key and create IAM policies in the identity's account. To specify particular external users or roles in a key policy, in the `Principal` element, enter the Amazon Resource Name (ARN) of a user or role in the external account. For example, the following example key policy statement allows `ExampleRole` in account `444455556666` to use a KMS key in account `111122223333`. This key policy statement gives the external account, `444455556666`, permission to use the KMS key in cryptographic operations for symmetric encryption KMS keys. **Note** The following example represents a sample key policy for sharing a KMS key with another account. Replace the example `Sid`, `Principal`, and `Action` values with valid values for the intended use of your KMS key. ``` { "Sid": "Allow an external account to use this KMS key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/ExampleRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" } ``` **Note** Do not set the Principal to an asterisk (\$1) in any key policy statement that allows permissions unless you use [conditions](policy-conditions.md) to limit the key policy. An asterisk gives every identity in every AWS account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other AWS accounts can use your KMS key whenever they have corresponding permissions in their own account. You also need to decide which permissions you want to give to the external account. For example, you might want to give users permission to decrypt but not encrypt, or permission to view the KMS key but not use it. For a list of permissions on KMS keys, see [AWS KMS permissions](kms-api-permissions-reference.md). **Setting the key policy when you create a KMS key** When you use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create a KMS key, you can use its `Policy` parameter to specify a key policy that gives an external account, or external users and roles, permission to use the KMS key. When you create a KMS key in the AWS Management Console, you also create its key policy. When you select identities in the **Key Administrators** and **Key Users** sections, AWS KMS adds policy statements for those identities to the KMS key's key policy. The **Key Users** section also lets you add external accounts as key users. When you enter the account ID of an external account, AWS KMS adds two statements to the key policy. This action only affects the key policy. Users and roles in the external account cannot use the KMS key until you attach IAM policies to give them some or all of these permissions. The first key policy statement gives the external account permission to use the KMS key in cryptographic operations. The second key policy statement allows the external account to create, view, and revoke grants on the KMS key, but only when the request comes from an [AWS service that is integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration). These permissions allow other AWS services that encrypt user data to use the KMS key. These permissions are designed for KMS keys that encrypt user data in AWS services ## Step 2: Add IAM policies in the external account The key policy in the account that owns the KMS key sets the valid range for permissions. But, users and roles in the external account cannot use the KMS key until you attach IAM policies that delegate those permissions, or use grants to manage access to the KMS key. The IAM policies are set in the external account. If the key policy gives permission to the external account, you can attach IAM policies to any user or role in the account. But if the key policy gives permission to specified users or roles, the IAM policy can only give those permissions to all or a subset of the specified users and roles. If an IAM policy gives KMS key access to other external users or roles, it has no effect. The key policy also limits the actions in the IAM policy. The IAM policy can delegate all or a subset of the actions specified in the key policy. If the IAM policy lists actions that are not specified in the key policy, those permissions are not effective. The following example IAM policy allows the principal to use the KMS key in account `111122223333` for cryptographic operations. To give this permission to users and roles in account `444455556666`, [attach the policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) to the users or roles in account `444455556666`. **Note** The following example represents a sample IAM policy for sharing a KMS key with another account. Replace the example `Sid`, `Resource`, and `Action` values with valid values for the intended use of your KMS key. ``` { "Sid": "AllowUseOfKeyInAccount111122223333", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ``` Note the following details about this policy: + Unlike key policies, IAM policy statements do not contain the `Principal` element. In IAM policies, the principal is the identity to which the policy is attached. + The `Resource` element in the IAM policy identifies the KMS key that the principal can use. To specify a KMS key, add its [key ARN](concepts.md#key-id-alias-ARN) to the `Resource` element. + You can specify more than one KMS key in the `Resource` element. But if you don't specify particular KMS keys in the `Resource` element, you might inadvertently give access to more KMS keys than you intend. + To allow the external user to use the KMS key with [AWS services that integrate with AWS KMS,](https://aws.amazon.com/kms/features/#AWS_Service_Integration) you might need to add permissions to the key policy or the IAM policy. For details, see [Allowing use of external KMS keys with AWS services](#cross-account-service). For more information about working with IAM policies, see [IAM policies](iam-policies.md). ## Allowing use of external KMS keys with AWS services You can give a user in a different account permission to use your KMS key with a service that is integrated with AWS KMS. For example, a user in an external account can use your KMS key to encrypt the objects in an Amazon S3 bucket or to encrypt the secrets they store in AWS Secrets Manager. The key policy must give the external user or the external user's account permission to use the KMS key. In addition, you need to attach IAM policies to the identity that gives the user permission to use the AWS service. The service might also require that users have additional permissions in the key policy or IAM policy. For a list of permissions that the AWS service requires on a customer managed key, see the Data Protection topic in the Security chapter of the user guide or developer guide for the service. ## Using KMS keys in other accounts If you have permission to use a KMS key in a different AWS account, you can use the KMS key in the AWS Management Console, AWS SDKs, AWS CLI, and AWS Tools for PowerShell. To identify a KMS key in a different account in a shell command or API request, use the following [key identifiers](concepts.md#key-id). + For [cryptographic operations](kms-cryptography.md#cryptographic-operations), [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), and [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html), use the [key ARN](concepts.md#key-id-key-ARN) or [alias ARN](concepts.md#key-id-alias-ARN) of the KMS key. + For [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html), [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html), [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/ListGrants.html), and [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/RevokeGrant.html), use the key ARN of the KMS key. If you enter only a key ID or alias name, AWS assumes the KMS key is in your account. The AWS KMS console does not display KMS keys in other accounts, even if you have permission to use them. Also, the lists of KMS keys displayed in the consoles of other AWS services do not include KMS keys in other accounts. To specify a KMS key in a different account in the console of an AWS service, you must enter the key ARN or alias ARN of the KMS key. The required key identifier varies with the service, and might differ between the service console and its API operations. For details, see the service documentation. # Control access to multi-Region keys You can use multi-Region keys in compliance, disaster recovery, and backup scenarios that would be more complex with single-Region keys. However, because the security properties of multi-Region keys are significantly different from those of single-Region keys, we recommend using caution when authorizing the creation, management, and use of multi-Region keys. **Note** Existing IAM policy statements with wildcard characters in the `Resource` field now apply to both single-Region and multi-Region keys. To restrict them to single-Region KMS keys or multi-Region keys, use the [kms:MultiRegion](conditions-kms.md#conditions-kms-multiregion) condition key. Use your authorization tools to prevent creation and use of multi-Region keys in any scenario where a single-Region will suffice. Allow principals to replicate a multi-Region key only into AWS Regions that require them. Give permission for multi-Region keys only to principals who need them and only for tasks that require them. You can use key policies, IAM policies, and grants to allow IAM principals to manage and use multi-Region keys in your AWS account. Each multi-Region key is an independent resource with a unique key ARN and key policy. You need to establish and maintain a key policy for each key and make sure that new and existing IAM policies implement your authorization strategy. To support multi-Region keys, AWS KMS uses an IAM service linked role. This role gives AWS KMS the permissions it needs to synchronize [shared properties](multi-region-keys-overview.md#mrk-sync-properties). For more information, see [Authorizing AWS KMS to synchronize multi-Region keys](multi-region-auth-slr.md). **Topics** + [ ## Authorization basics for multi-Region keys ](#multi-region-auth-about) + [ ## Authorizing multi-Region key administrators and users ](#multi-region-auth-users) ## Authorization basics for multi-Region keys When designing key policies and IAM policies for multi-Region keys, consider the following principles. + **Key policy** — Each multi-Region key is an independent KMS key resource with its own [key policy](key-policies.md). You can apply the same or a different key policy to each key in the set of related multi-Region keys. Key policies are *not* [shared properties](multi-region-keys-overview.md#mrk-sync-properties) of multi-Region keys. AWS KMS does not copy or synchronize key policies among related multi-Region keys. When you create a replica key in the AWS KMS console, the console displays the current key policy of the primary key as a convenience. You can use this key policy, edit it, or delete and replace it. But even if you accept the primary key policy unchanged, AWS KMS doesn't synchronize the policies. For example, if you change the key policy of the primary key, the key policy of the replica key remains the same. + **Default key policy** — When you create multi-Region keys by using the [CreateKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateKey.html) and `ReplicateKey` operations, the [default key policy](key-policy-default.md) is applied unless you specify a key policy in the request. This is the same default key policy that is applied to single-Region keys. + **IAM policies** — As with all KMS keys, you can use IAM policies to control access to multi-Region keys only when the [key policy allows it](key-policy-default.md#key-policy-default-allow-root-enable-iam). [IAM policies](iam-policies.md) apply to all AWS Regions by default. However, you can use condition keys, such as [aws:RequestedRegion](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-requestedregion), to limit permissions to a particular Region. To create primary and replica keys, principals must have `kms:CreateKey` permission in an IAM policy that applies to the Region where the key is created. + **Grants** — AWS KMS [grants](grants.md) are Regional. Each grant allows permissions to one KMS key. You can use grants to allow permissions to a multi-Region primary key or replica key. But you cannot use a single grant to allow permissions to multiple KMS keys, even if they are related multi-Region keys. + **Key ARN** — Each multi-Region key has a [unique key ARN](mrk-how-it-works.md). The key ARNs of related multi-Region keys have the same partition, account, and key ID, but different Regions. To apply an IAM policy statement to a particular multi-Region key, use its key ARN or a key ARN pattern that includes the Region. To apply an IAM policy statement to all related multi-Region keys, use a wildcard character (\$1) in the Region element of the ARN, as shown in the following example. ``` { "Effect": "Allow", "Action": [ "kms:Describe*", "kms:List*" ], "Resource": { "arn:aws:kms:*::111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" } } ``` To apply a policy statement to all multi-Region keys in your AWS account, you can use the [kms:MultiRegion](conditions-kms.md#conditions-kms-multiregion) policy condition or a key ID pattern that includes the distinctive `mrk-` prefix. + **Service-linked role** — Principals who create multi-Region primary keys must have [iam:CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) permission. To synchronize the shared properties of related multi-Region keys, AWS KMS assumes an IAM [service-linked role](multi-region-auth-slr.md). AWS KMS creates the service-linked role in the AWS account whenever you create a multi-Region primary key. (If the role exists, AWS KMS recreates it, which has no harmful effect.) The role is valid in all Regions. To allow AWS KMS to create (or recreate) the service-linked role, principals who create multi-Region primary keys must have [iam:CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) permission. ## Authorizing multi-Region key administrators and users Principals who create and manage multi-Region keys need the following permissions in the primary and replica Regions: + `kms:CreateKey` + `kms:ReplicateKey` + `kms:UpdatePrimaryRegion` + `iam:CreateServiceLinkedRole` ### Creating a primary key To [create a multi-Region primary key](create-primary-keys.md), the principal needs [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) and [iam:CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) permissions in an IAM policy that is effective in the primary key's Region. Principals who have these permissions can create single-Region and multi-Region keys unless you restrict their permissions. The `iam:CreateServiceLinkedRole` permission allows AWS KMS to create the [**AWSServiceRoleForKeyManagementServiceMultiRegionKeys** role](multi-region-auth-slr.md) to synchronize the [shared properties](multi-region-keys-overview.md#mrk-sync-properties) of related multi-Region keys. For example, this IAM policy allows a principal to create multi-Region keys, attach policies for those keys, and service linked roles for multi-Region keys. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":{ "Action": [ "kms:CreateKey", "iam:CreateServiceLinkedRole" ], "Effect":"Allow", "Resource":"*" } } ``` ------ To allow or deny permission to create multi-Region primary keys, use the [kms:MultiRegion](conditions-kms.md#conditions-kms-multiregion) condition key. Valid values are `true` (multi-Region key) or `false` (single-Region key). For example, the following IAM policy statement uses a `Deny` action with the `kms:MultiRegion` condition key to prevent principals from creating multi-Region keys. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":{ "Action":"kms:CreateKey", "Effect":"Deny", "Resource":"*", "Condition": { "Bool": { "kms:MultiRegion": true } } } } ``` ------ ### Replicating keys To [create a multi-Region replica key](#mrk-auth-replicate), the principal needs the following permissions: + [kms:ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) permission in the key policy of the primary key. + [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) permission in an IAM policy that is effective in the replica key Region. Use caution when allowing these permissions. They allow principals to create KMS keys and the key policies that authorize their use. The `kms:ReplicateKey` permission also authorizes the transfer of key material across Region boundaries within AWS KMS. To restrict the AWS Regions in which a multi-Region key can be replicated, use the [kms:ReplicaRegion](conditions-kms.md#conditions-kms-replica-region) condition key. It limits only the `kms:ReplicateKey` permission. Otherwise, it has no effect. For example, the following key policy allows the principal to replicate this primary key, but only in the specified Regions. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Administrator" }, "Action": "kms:ReplicateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:ReplicaRegion": [ "us-east-1", "eu-west-3", "ap-southeast-2" ] } } } ``` ### Updating the primary Region Authorized principals can convert a replica key to a primary key, which changes the former primary key into a replica. This action is known as [updating the primary Region](multi-region-update.md). To update the primary Region, the principal needs [kms:UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) permission in both Regions. You can provide these permissions in a key policy or IAM policy. + `kms:UpdatePrimaryRegion` on the primary key. This permission must be effective in the primary key Region. + `kms:UpdatePrimaryRegion` on the replica key. This permission must be effective in the replica key Region. For example, the following key policy gives users who can assume the Administrator role permission to update the primary Region of the KMS key. This KMS key can be the primary key or a replica key in this operation. ``` { "Effect": "Allow", "Resource": "*", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Administrator" }, "Action": "kms:UpdatePrimaryRegion" } ``` To restrict the AWS Regions that can host a primary key, use the [kms:PrimaryRegion](conditions-kms.md#conditions-kms-primary-region) condition key. For example, the following IAM policy statement allows the principals to update the primary Region of the multi-Region keys in the AWS account, but only when the new primary Region is one of the specified Regions. ``` { "Effect": "Allow", "Action": "kms:UpdatePrimaryRegion", "Resource": { "arn:aws:kms:*:111122223333:key/*" }, "Condition": { "StringEquals": { "kms:PrimaryRegion": [ "us-west-2", "sa-east-1", "ap-southeast-1" ] } } } ``` ### Using and managing multi-Region keys By default, principals who have permission to use and manage KMS keys in an AWS account and Region also have permission to use and manage multi-Region keys. However, you can use the [kms:MultiRegion](conditions-kms.md#conditions-kms-multiregion) condition key to allow only single-Region keys or only multi-Region keys. Or use the [kms:MultiRegionKeyType](conditions-kms.md#conditions-kms-multiregion-key-type) condition key to allow only multi-Region primary keys or only replica keys. Both condition keys controls access to the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation and to any operation that uses an existing KMS key, such as [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) or [EnableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_EnableKey.html). The following example IAM policy statement uses the `kms:MultiRegion` condition key to prevent the principals from using or managing any multi-Region key. ``` { "Effect": "Deny", "Action": "kms:*", "Resource": "*", "Condition": { "Bool": "kms:MultiRegion": true } } ``` This example IAM policy statement uses the `kms:MultiRegionKeyType` condition to allow principals to schedule and cancel key deletion, but only on multi-Region replica keys. ``` { "Effect": "Allow", "Action": [ "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringEquals": "kms:MultiRegionKeyType": "REPLICA" } } ``` # Determining access to AWS KMS keys To determine the full extent of who or what currently has access to an AWS KMS key, you must examine the key policy of the KMS key, all [grants](grants.md) that apply to the KMS key, and potentially all AWS Identity and Access Management (IAM) policies. You might do this to determine the scope of potential usage of a KMS key, or to help you meet compliance or auditing requirements. The following topics can help you generate a complete list of the AWS principals (identities) that currently have access to a KMS key. **Topics** + [ # Examining the key policy ](determining-access-key-policy.md) + [ # Examining IAM policies ](determining-access-iam-policies.md) + [ # Examining grants ](determining-access-grants.md) # Examining the key policy [Key policies](key-policies.md) are the primary way to control access to KMS keys. Every KMS key has exactly one key policy. When a key policy consists of or includes the [default key policy](key-policy-default.md#key-policy-default-allow-root-enable-iam), the key policy allows IAM administrators in the account to use IAM policies to control access to the KMS key. Also, if the key policy gives [another AWS account](key-policy-modifying-external-accounts.md) permission to use the KMS key, the IAM administrators in the external account can use IAM policies to delegate those permissions. To determine the complete list of principals that can access the KMS key, [examine the IAM policies](determining-access-iam-policies.md). To view the key policy of an AWS KMS [ customer managed key](concepts.md#customer-mgn-key) or [AWS managed key](concepts.md#aws-managed-key) in your account, use the AWS Management Console or the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation in the AWS KMS API. To view the key policy, you must have `kms:GetKeyPolicy` permissions for the KMS key. For instructions for viewing the key policy for a KMS key, see [View a key policies](key-policy-viewing.md). Examine the key policy document and take note of all principals specified in each policy statement's `Principal` element. In a policy statement with an `Allow` effect, the IAM users, IAM roles, and AWS accounts in the `Principal` element have access to this KMS key. **Note** Do not set the Principal to an asterisk (\$1) in any key policy statement that allows permissions unless you use [conditions](policy-conditions.md) to limit the key policy. An asterisk gives every identity in every AWS account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other AWS accounts can use your KMS key whenever they have corresponding permissions in their own account. The following examples use the policy statements found in the [default key policy](key-policy-default.md) to demonstrate how to do this. **Example Policy statement 1** ``` { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:root"}, "Action": "kms:*", "Resource": "*" } ``` In policy statement 1, `arn:aws:iam::111122223333:root` is an [AWS account principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts) that refers to the AWS account 111122223333. (It is not the account root user.) By default, a policy statement like this one is included in the key policy document when you create a new KMS key with the AWS Management Console, or create a new KMS key programmatically but do not provide a key policy. A key policy document with a statement that allows access to the AWS account enables [IAM policies in the account to allow access to the KMS key](key-policy-default.md#key-policy-default-allow-root-enable-iam). This means that users and roles in the account might have access to the KMS key even if they are not explicitly listed as principals in the key policy document. Take care to [examine all IAM policies](determining-access-iam-policies.md) in all AWS accounts listed as principals to determine whether they allow access to this KMS key. **Example Policy statement 2** ``` { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/KMSKeyAdmins"}, "Action": [ "kms:Describe*", "kms:Put*", "kms:Create*", "kms:Update*", "kms:Enable*", "kms:Revoke*", "kms:List*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" } ``` In policy statement 2, `arn:aws:iam::111122223333:role/KMSKeyAdmins` refers to the IAM role named KMSKeyAdmins in AWS account 111122223333. Users who are authorized to assume this role are allowed to perform the actions listed in the policy statement, which are the administrative actions for managing a KMS key. **Example Policy statement 3** ``` { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/EncryptionApp"}, "Action": [ "kms:DescribeKey", "kms:GenerateDataKey*", "kms:Encrypt", "kms:ReEncrypt*", "kms:Decrypt" ], "Resource": "*" } ``` In policy statement 3, `arn:aws:iam::111122223333:role/EncryptionApp` refers to the IAM role named EncryptionApp in AWS account 111122223333. Principals who are authorized to assume this role are allowed to perform the actions listed in the policy statement, which include the [cryptographic operations](kms-cryptography.md#cryptographic-operations) for a symmetric encryption KMS key. **Example Policy statement 4** ``` { "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/EncryptionApp"}, "Action": [ "kms:ListGrants", "kms:CreateGrant", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} } ``` In policy statement 4, `arn:aws:iam::111122223333:role/EncryptionApp` refers to the IAM role named EncryptionApp in AWS account 111122223333. Principals who are authorized assume this role are allowed to perform the actions listed in the policy statement. These actions, when combined with the actions allowed in **Example policy statement 3**, are those necessary to delegate use of the KMS key to most [AWS services that integrate with AWS KMS](service-integration.md), specifically the services that use [grants](grants.md). The [kms:GrantIsForAWSResource](conditions-kms.md#conditions-kms-grant-is-for-aws-resource) value in the `Condition` element ensures that the delegation is allowed only when the delegate is an AWS service that integrates with AWS KMS and uses grants for authorization. To learn all the different ways you can specify a principal in a key policy document, see [Specifying a Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#Principal_specifying) in the *IAM User Guide*. To learn more about AWS KMS key policies, see [Key policies in AWS KMS](key-policies.md). # Examining IAM policies In addition to the key policy and grants, you can also use [IAM policies](iam-policies.md) to allow access to a KMS key. For more information about how IAM policies and key policies work together, see [Troubleshooting AWS KMS permissions](policy-evaluation.md). To determine which principals currently have access to a KMS key through IAM policies, you can use the browser-based [IAM Policy Simulator](https://policysim.aws.amazon.com/) tool, or you can make requests to the IAM API. **Contents** + [ ## Examining IAM policies with the IAM policy simulator ](#determining-access-iam-policy-simulator) + [ ## Examining IAM policies with the IAM API ](#determining-access-iam-api) ## Examining IAM policies with the IAM policy simulator The IAM Policy Simulator can help you learn which principals have access to a KMS key through an IAM policy. **To use the IAM policy simulator to determine access to a KMS key** 1. Sign in to the AWS Management Console and then open the IAM Policy Simulator at [https://policysim.aws.amazon.com/](https://policysim.aws.amazon.com/). 1. In the **Users, Groups, and Roles** pane, choose the user, group, or role whose policies you want to simulate. 1. (Optional) Clear the check box next to any policies that you want to omit from the simulation. To simulate all policies, leave all policies selected. 1. In the **Policy Simulator** pane, do the following: 1. For **Select service**, choose **Key Management Service**. 1. To simulate specific AWS KMS actions, for **Select actions**, choose the actions to simulate. To simulate all AWS KMS actions, choose **Select All**. 1. (Optional) The Policy Simulator simulates access to all KMS keys by default. To simulate access to a specific KMS key, choose **Simulation Settings**and then type the Amazon Resource Name (ARN) of the KMS key to simulate. 1. Choose **Run Simulation**. You can view the results of the simulation in the **Results** section. Repeat steps 2 through 6 for every user, group, and role in the AWS account. ## Examining IAM policies with the IAM API You can use the IAM API to examine IAM policies programmatically. The following steps provide a general overview of how to do this: 1. For each AWS account listed as a principal in the key policy (that is, each [AWS account principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts) specified in this format: `"Principal": {"AWS": "arn:aws:iam::111122223333:root"}`), use the [ListUsers](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListUsers.html) and [ListRoles](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListRoles.html) operations in the IAM API to get all users and roles in the account. 1. For each user and role in the list, use the [SimulatePrincipalPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html) operation in the IAM API, passing in the following parameters: + For `PolicySourceArn`, specify the Amazon Resource Name (ARN) of a user or role from your list. You can specify only one `PolicySourceArn` for each `SimulatePrincipalPolicy` request, so you must call this operation multiple times, once for each user and role in your list. + For the `ActionNames` list, specify every AWS KMS API action to simulate. To simulate all AWS KMS API actions, use `kms:*`. To test individual AWS KMS API actions, precede each API action with "`kms:`", for example "`kms:ListKeys`". For a complete list of AWS KMS API actions, see [Actions](https://docs.aws.amazon.com/kms/latest/APIReference/API_Operations.html) in the *AWS Key Management Service API Reference*. + (Optional) To determine whether the users or roles have access to specific KMS keys, use the `ResourceArns` parameter to specify a list of the Amazon Resource Names (ARNs) of the KMS keys. To determine whether the users or roles have access to any KMS key, omit the `ResourceArns` parameter. IAM responds to each `SimulatePrincipalPolicy` request with an evaluation decision: `allowed`, `explicitDeny`, or `implicitDeny`. For each response that contains an evaluation decision of `allowed`, the response includes the name of the specific AWS KMS API operation that is allowed. It also includes the ARN of the KMS key that was used in the evaluation, if any. # Examining grants Grants are advanced mechanisms for specifying permissions that you or an AWS service integrated with AWS KMS can use to specify how and when a KMS key can be used. Grants are attached to a KMS key, and each grant contains the principal who receives permission to use the KMS key and a list of operations that are allowed. Grants are an alternative to the key policy, and are useful for specific use cases. For more information, see [Grants in AWS KMS](grants.md). To get a list of grants for a KMS key, use the AWS KMS [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation. You can examine the grants for a KMS key to determine who or what currently has access to use the KMS key via those grants. For example, the following is a JSON representation of a grant that was obtained from the [list-grants](https://docs.aws.amazon.com/cli/latest/reference/kms/list-grants.html) command in the AWS CLI. ``` {"Grants": [{ "Operations": ["Decrypt"], "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Name": "0d8aa621-43ef-4657-b29c-3752c41dc132", "RetiringPrincipal": "arn:aws:iam::123456789012:root", "GranteePrincipal": "arn:aws:sts::111122223333:assumed-role/aws:ec2-infrastructure/i-5d476fab", "GrantId": "dc716f53c93acacf291b1540de3e5a232b76256c83b2ecb22cdefa26576a2d3e", "IssuingAccount": "arn:aws:iam::111122223333:root", "CreationDate": 1.444151834E9, "Constraints": {"EncryptionContextSubset": {"aws:ebs:id": "vol-5cccfb4e"}} }]} ``` To find out who or what has access to use the KMS key, look for the `"GranteePrincipal"` element. In the preceding example, the grantee principal is an assumed role user that is associated with the EC2 instance i-5d476fab. The EC2 infrastructure uses this role to attach the encrypted EBS volume vol-5cccfb4e to the instance. In this case, the EC2 infrastructure role has permission to use the KMS key because you previously created an encrypted EBS volume that is protected by this KMS key. You then attached the volume to an EC2 instance. The following is another example of a JSON representation of a grant that was obtained from the [list-grants](https://docs.aws.amazon.com/cli/latest/reference/kms/list-grants.html) command in the AWS CLI. In the following example, the grantee principal is another AWS account. ``` {"Grants": [{ "Operations": ["Encrypt"], "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Name": "", "GranteePrincipal": "arn:aws:iam::444455556666:root", "GrantId": "f271e8328717f8bde5d03f4981f06a6b3fc18bcae2da12ac38bd9186e7925d11", "IssuingAccount": "arn:aws:iam::111122223333:root", "CreationDate": 1.444151269E9 }]} ``` # Encryption context **Note** You cannot specify an encryption context in a cryptographic operation with an [asymmetric KMS key](symmetric-asymmetric.md) or an [HMAC KMS key](hmac.md). Asymmetric algorithms and MAC algorithms do not support an encryption context. All AWS KMS [cryptographic operations](kms-cryptography.md#cryptographic-operations) with [symmetric encryption KMS keys](symm-asymm-choose-key-spec.md#symmetric-cmks) accept an *encryption context*, an optional set of non-secret key–value pairs that can contain additional contextual information about the data. You can insert encryption context in `Encrypt` operations in AWS KMS to enhance the authorization and auditability of your AWS KMS API decryption calls. AWS KMS uses the encryption context as additional authenticated data (AAD) to support authenticated encryption. The encryption context is cryptographically bound to the ciphertext so that the same encryption context is required to decrypt the data. The encryption context is not secret and not encrypted. It appears in plaintext in [AWS CloudTrail Logs](logging-using-cloudtrail.md) 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html) (Amazon EBS) [CreateSnapshot](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateSnapshot.html) 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](grants.md) and as a *[condition in policy statements](policy-conditions.md)*. Encryption context keys and their values can be arbitrary strings with `aws`. These values contrasts [AWS generated tags](https://docs.aws.amazon.com/tag-editor/latest/userguide/best-practices-and-strats.html#tag-conventions) like [aws:cloudformation:stack-name](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-resource-tags.html). For more information, see [kms:EncryptionContext:*context-key*](conditions-kms.md#conditions-kms-encryption-context) 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](https://aws.amazon.com/blogs/security/how-to-protect-the-integrity-of-your-encrypted-data-by-using-aws-key-management-service-and-encryptioncontext/) on the AWS Security Blog. ## Encryption context rules AWS 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, AWS 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`](conditions-kms.md#conditions-kms-encryption-context) and [`kms:EncryptionContextKeys`](conditions-kms.md#conditions-kms-encryption-context-keys). For details about key policy document rules, see [Key policy format](key-policy-overview.md#key-policy-format). For details about IAM policy document rules, see [IAM name requirements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-names) in the *IAM User Guide*. ## Encryption context in policies 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 AWS KMS keys in key policies and IAM policies. The [kms:EncryptionContext:](conditions-kms.md#conditions-kms-encryption-context) and [kms:EncryptionContextKeys](conditions-kms.md#conditions-kms-encryption-context) 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 [Condition keys for AWS KMS](policy-conditions.md). ## Encryption context in grants When you [create a grant](grants.md), you can include [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) that establish conditions for the grant permissions. AWS KMS supports two grant constraints, `EncryptionContextEquals` and `EncryptionContextSubset`, both of which involve the [encryption context](#encrypt_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](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 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](create-grant-overview.md#grant-constraints). For detailed information about grants, see [Grants in AWS KMS](grants.md). ## Logging encryption context AWS KMS uses AWS 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. ## Storing encryption context To simplify use of any encryption context when you call the [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) or [https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) 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. # Testing your permissions To use AWS KMS, you must have credentials that AWS can use to authenticate your API requests. The credentials must include the permission to access KMS keys and aliases. The permissions are determined by key policies, IAM policies, grants, and cross-account access controls. In addition to controlling access to KMS keys, you can control access to your CloudHSM, and to your custom key stores. You can specify the `DryRun` API parameter to verify that you have the necessary permissions to use AWS KMS keys. You can also use `DryRun` to verify that the request parameters in a AWS KMS API call are correctly specified. **Topics** + [ ## What is the DryRun parameter? ](#what-is-dryrun) + [ ## Specifying DryRun with the API ](#dryrun-api) ## What is the DryRun parameter? `DryRun` is an optional API parameter that you specify to verify that AWS KMS API calls will succeed. Use `DryRun` to test your API call, before actually making the call to AWS KMS. You can verify the following. + That you have the necessary permissions to use AWS KMS keys. + That you have specified the parameters in the call correctly. AWS KMS supports using the `DryRun` parameter in certain API actions: + [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) + [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) + [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) + [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) + [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) + [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) + [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) + [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) + [GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) + [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) + [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) + [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) + [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) + [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) + [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) Using the `DryRun` parameter will incur charges and will be billed as a standard API request. For more information about AWS KMS pricing, see [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/). All API requests using the `DryRun` parameter apply to the request quota of the API and can result in a throttling exception if you exceed an API request quota. For example, calling [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) with `DryRun` or without `DryRun` counts against the same cryptographic operations quota. See [Throttling AWS KMS requests](throttling.md) to learn more. Every call to an AWS KMS API operation is captured as an event and recorded in an AWS CloudTrail log. The output of any operations that specify the `DryRun` parameter appear in your CloudTrail log. For more information, see [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md). ## Specifying DryRun with the API To use `DryRun`, specify the `—dry-run` parameter in AWS CLI commands and AWS KMS API calls that support the parameter. When you do, AWS KMS will verify whether your call will succeed. AWS KMS calls that use `DryRun` will always fail and return a message with information about reason why the call failed. The message can include the following exceptions: + `DryRunOperationException` ‐ The request would succeed if `DryRun` wasn’t specified. + `ValidationException` ‐ The request failed from specifying an incorrect API parameter. + `AccessDeniedException` ‐ You do not have permissions to perform the specified API action on the KMS resource. For example, the following command uses the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation and creates a grant that allows users who are authorized to assume the `keyUserRole` role to call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation on a specified [symmetric KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks). The `DryRun` parameter is specified. ``` $ aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --dry-run ``` # Troubleshooting AWS KMS permissions When authorizing access to a KMS key, AWS KMS evaluates the following: + The [key policy](determining-access-key-policy.md) that is attached to the KMS key. The key policy is always defined in the AWS account and Region that owns the KMS key. + All [IAM policies](determining-access-iam-policies.md) that are attached to the user or role making the request. IAM policies that govern a principal's use of a KMS key are always defined in the principal's AWS account. + All [grants](determining-access-grants.md) that apply to the KMS key. + Other types of policies that might apply to the request to use the KMS key, such as [AWS Organizations service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_type-auth.html#orgs_manage_policies_scp) and [VPC endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#edit-vpc-endpoint-policy). These policies are optional and allow all actions by default, but you can use them to restrict permissions otherwise given to principals. AWS KMS evaluates these policy mechanisms together to determine whether access to the KMS key is allowed or denied. To do this, AWS KMS uses a process similar to the one depicted in the following flowchart. The following flowchart provides a visual representation of the policy evaluation process. ![\[Flowchart that describes the policy evaluation process\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/updated-kms-authz-diagram.png) This flowchart is divided into two parts. The parts appear to be sequential, but they are typically evaluated at the same time. + *Use authorization* determines whether you are permitted to use a KMS key based on its key policy, IAM policies, grants, and other applicable policies. + *Key trust* determines whether you should trust a KMS key that you are permitted to use. In general, you trust the resources in your AWS account. But, you can also feel confident about using KMS keys in a different AWS account if a grant or IAM policy in your account allows you to use the KMS key. You can use this flowchart to discover why a caller was allowed or denied permission to use a KMS key. You can also use it to evaluate your policies and grants. For example, the flowchart shows that a caller can be denied access by an explicit `DENY` statement, or by the absence of an explicit `ALLOW` statement, in the key policy, IAM policy, or grant. The flowchart can explain some common permission scenarios. **Topics** + [ ## Example 1: User is denied access to a KMS key in their AWS account ](#example-no-iam) + [ ## Example 2: User assumes role with permission to use a KMS key in a different AWS account ](#example-cross-acct) ## Example 1: User is denied access to a KMS key in their AWS account Alice is an IAM user in the 111122223333 AWS account. She was denied access to a KMS key in same AWS account. Why can't Alice use the KMS key? In this case, Alice is denied access to the KMS key because there is no key policy, IAM policy, or grant that gives her the required permissions. The key policy of the KMS key allows the AWS account to use IAM policies to control access to the KMS key, but no IAM policy gives Alice permission to use the KMS key. ![\[Flowchart that describes the policy evaluation process\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/kms-auth-flow-Alice.png) Consider the relevant policies for this example. + The KMS key that Alice wants to use has the [default key policy](key-policy-default.md). This policy [allows the AWS account](key-policy-default.md#key-policy-default-allow-root-enable-iam) that owns the KMS key to use IAM policies to control access to the KMS key. This key policy satisfies the *Does the key policy ALLOW the callers account to use IAM policies to control access to the key?* condition in the flowchart. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id" : "key-test-1", "Statement" : [ { "Sid" : "DelegateToIAMPolicies", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] } ``` ------ + However, no key policy, IAM policy, or grant gives Alice permission to use the KMS key. Therefore, Alice is denied permission to use the KMS key. ## Example 2: User assumes role with permission to use a KMS key in a different AWS account Bob is a user in account 1 (111122223333). He is allowed to use a KMS key in account 2 (444455556666) in [cryptographic operations](kms-cryptography.md#cryptographic-operations). How is this possible? **Tip** When evaluating cross-account permissions, remember that the key policy is specified in the KMS key's account. The IAM policy is specified in the caller's account, even when the caller is in a different account. For details about providing cross-account access to KMS keys, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md). + The key policy for the KMS key in account 2 allows account 2 to use IAM policies to control access to the KMS key. + The key policy for the KMS key in account 2 allows account 1 to use the KMS key in cryptographic operations. However, account 1 must use IAM policies to give its principals access to the KMS key. + An IAM policy in account 1 allows the `Engineering` role to use the KMS key in account 2 for cryptographic operations. + Bob, a user in account 1, has permission to assume the `Engineering` role. + Bob can trust this KMS key, because even though it is not in his account, an IAM policy in his account gives him explicit permission to use this KMS key. ![\[Flowchart that describes the policy evaluation process\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/kms-auth-flow-Bob.png) Consider the policies that let Bob, a user in account 1, use the KMS key in account 2. + The key policy for the KMS key allows account 2 (444455556666, the account that owns the KMS key) to use IAM policies to control access to the KMS key. This key policy also allows account 1 (111122223333) to use the KMS key in cryptographic operations (specified in the `Action` element of the policy statement). However, no one in account 1 can use the KMS key in account 2 until account 1 defines IAM policies that give the principals access to the KMS key. In the flowchart, this key policy in account 2 satisfies the *Does the key policy ALLOW the caller's account to use IAM policies to control access to the key?* condition. ------ #### [ JSON ] **** ``` { "Id": "key-policy-acct-2", "Version":"2012-10-17", "Statement": [ { "Sid": "PermissionUseIAMpolicies", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "AllowAccount1UseThisKMSKeys", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncryptFrom", "kms:ReEncryptTo", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:DescribeKey" ], "Resource": "*" } ] } ``` ------ + An IAM policy in the caller's AWS account (account 1, 111122223333) gives the principal permission to perform cryptographic operations using the KMS key in account 2 (444455556666). The `Action` element delegates to the principal the same permissions that the key policy in account 2 gave to account 1. To give these permission to the `Engineering` role in account 1, [this inline policy is embedded](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePolicy.html) in the `Engineering` role. Cross-account IAM policies like this one are effective only when the key policy for the KMS key in account 2 gives account 1 permission to use the KMS key. Also, account 1 can only give its principals permission to perform the actions that the key policy gave to the account. In the flowchart, this satisfies the *Does an IAM policy allow the caller to perform this action?* condition. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncryptFrom", "kms:ReEncryptTo", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:DescribeKey" ], "Resource": [ "arn:aws:kms:us-west-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab" ] } ] } ``` ------ + The last required element is the definition of the `Engineering` role in account 1. The `AssumeRolePolicyDocument` in the role allows Bob to assume the `Engineering` role. ``` { "Role": { "Arn": "arn:aws:iam::111122223333:role/Engineering", "CreateDate": "2019-05-16T00:09:25Z", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": { "Principal": { "AWS": "arn:aws:iam::111122223333:user/bob" }, "Effect": "Allow", "Action": "sts:AssumeRole" } }, "Path": "/", "RoleName": "Engineering", "RoleId": "AROA4KJY2TU23Y7NK62MV" } } ``` # AWS KMS access control glossary The following topic describes important terms and concepts in AWS KMS access control. ## Authentication *Authentication* is the process of verifying your identity. To send a request to AWS KMS, you must sign into AWS using your AWS credentials. ## Authorization *Authorization* provides the permission to send requests to create, manage, or use AWS KMS resources. For example, you must be authorized to use a KMS key in a cryptographic operation. To control access to your AWS KMS resources, use [key policies](key-policies.md), [IAM policies](iam-policies.md), and [grants](grants.md). Every KMS key must have a key policy. If the key policy allows it, you can also use IAM policies and grants to give principals access to the KMS key. To refine your authorization, you can use [condition keys](policy-conditions.md) that allow or deny access only when a request or resource meets the conditions you specify. You can also allow access to principals you trust in [other AWS accounts](key-policy-modifying-external-accounts.md). ## Authenticating with identities Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role. You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*. For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*. ### AWS account root user When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*. ### Federated identity As a best practice, require human users to use federation with an identity provider to access AWS services using temporary credentials. A *federated identity* is a user from your enterprise directory, web identity provider, or Directory Service that accesses AWS services using credentials from an identity source. Federated identities assume roles that provide temporary credentials. For centralized access management, we recommend AWS IAM Identity Center. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*. ### IAM users and groups An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*. An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*. ### IAM roles An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*. IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*. ## Managing access using policies You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*. Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**. By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation. ### Identity-based policies Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*. Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*. ### Resource-based policies An AWS KMS [key policy](key-policies.md) is a resource-based policy that controls access to a KMS key. Every KMS key must have a key policy. You can use other authorization mechanism to allow access to the KMS key, but only if the key policy allows it. (You can use an IAM policy to *deny* access to a KMS key even if the key policy doesn't explicitly permit it.) Resource-based policies are JSON policy documents that you attach to a resource, such as a KMS key, to control access to the specific resource. The resource-based policy defines the actions that a specified principal can perform on that resource and under what conditions. You don't specify the resource in a resource-based policy, but you must specify a principal, such as accounts, users, roles, federated users, or AWS services. Resource-based policies are inline policies that are located in that service that manages the resource. You can't use AWS managed policies from IAM, such as the [`AWSKeyManagementServicePowerUser` managed policy](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSKeyManagementServicePowerUser), in a resource-based policy. ### Other policy types AWS supports additional policy types that can set the maximum permissions granted by more common policy types: + **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*. + **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*. + **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*. + **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*. ### Multiple policy types When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. ## AWS KMS resources In AWS KMS, the primary resource is an AWS KMS key. AWS KMS also supports an [alias](kms-alias.md), an independent resource that provides a friendly name for a KMS key. Some AWS KMS operations allow you to use an alias to identify a KMS key. Each instance of a KMS key or alias has a unique [Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) (ARN) with a standard format. In AWS KMS resources, the AWS service name is `kms`. + **AWS KMS key** ARN format: `arn:AWS partition name:AWS service name:AWS Region:AWS account ID:key/key ID` Example ARN: `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` + **Alias** ARN format: `arn:AWS partition name:AWS service name:AWS Region:AWS account ID:alias/alias name` Example ARN: `arn:aws:kms:us-west-2:111122223333:alias/example-alias` AWS KMS provides a set of API operations to work with your AWS KMS resources. For more information about identifying KMS keys in the AWS Management Console and AWS KMS API operations, see [Key identifiers (KeyId)](concepts.md#key-id). For a list of AWS KMS operations, see the [AWS Key Management Service API Reference](https://docs.aws.amazon.com/kms/latest/APIReference/).