# Key policies in Amazon KMS A key policy is a resource policy for an Amazon 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 Amazon 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 Amazon Web Services 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 Amazon services](key-policy-services.md) # Creating a key policy You can create and manage key policies in the Amazon KMS console or by using Amazon KMS API operations, such as [CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html), [ReplicateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_ReplicateKey.html), and [PutKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_PutKeyPolicy.html). When you create a KMS key in the Amazon 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-cn: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.amazonaws.cn/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 Amazon Web Services accounts, IAM users, IAM roles, and some Amazon 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 Amazon 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 Amazon Web Services account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other Amazon Web Services 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.amazonaws.cn/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts](https://docs.amazonaws.cn/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 Amazon Web Services 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 [Amazon 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 Amazon Web Services 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 Amazon Web Services Regions](https://docs.amazonaws.cn/general/latest/gr/rande-manage.html) in the *Amazon Web Services General Reference*. To allow a different Amazon Web Services 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 Amazon KMS [Encrypt](https://docs.amazonaws.cn/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 Amazon KMS console correctly reports an error, but the [CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html) and [PutKeyPolicy](https://docs.amazonaws.cn/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 Amazon KMS console correctly reports an error, but the [CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html) and [PutKeyPolicy](https://docs.amazonaws.cn/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, Amazon 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*. Amazon KMS supports [Amazon global condition keys](conditions-aws.md) and [Amazon KMS condition keys](conditions-kms.md). To support attribute-based access control (ABAC), Amazon KMS provides condition keys that control access to a KMS key based on tags and aliases. For details, see [ABAC for Amazon 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 Amazon policy syntax, see [Amazon IAM Policy Reference](https://docs.amazonaws.cn/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 Amazon Web Services 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-cn:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "AllowKeyAdministratorsAccess", "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn: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-cn:iam::111122223333:role/ExampleUserRole" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, { "Sid": "AllowAttachmentPersistentResources", "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn: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, Amazon KMS creates one for you. The default key policy that Amazon KMS uses differs depending on whether you create the key in the Amazon KMS console or you use the Amazon KMS API. **Default key policy when you create a KMS key programmatically** When you create a KMS key programmatically with the [Amazon KMS API](https://docs.amazonaws.cn/kms/latest/APIReference/) (including by using the [Amazon SDKs](http://www.amazonaws.cn/tools/#sdk), [Amazon Command Line Interface](https://docs.amazonaws.cn/cli/latest/userguide/) or [Amazon Tools for PowerShell](https://docs.amazonaws.cn/powershell/latest/userguide/)), and you don't specify a key policy, Amazon KMS applies a very simple default key policy. This default key policy has one policy statement that gives the Amazon Web Services account that owns the KMS key permission to use IAM policies to allow access to all Amazon KMS operations on the KMS key. For more information about this policy statement, see [Allows access to the Amazon Web Services account and enables IAM policies](#key-policy-default-allow-root-enable-iam). **Default key policy when you create a KMS key with the Amazon Web Services Management Console** When you [create a KMS key with the Amazon Web Services Management Console](create-keys.md), the key policy begins with the policy statement that [allows access to the Amazon Web Services 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 Amazon services](#key-policy-service-integration). You can use the features of the Amazon KMS console to specify the IAM users, IAM roles, and Amazon Web Services accounts who are key administrators and those who are key users (or both). **Permissions** + [Allows access to the Amazon Web Services 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 Amazon services](#key-policy-service-integration) ## Allows access to the Amazon Web Services account and enables IAM policies The following default key policy statement is critical. + It gives the Amazon Web Services account that owns the KMS key full access to the KMS key. Unlike other Amazon resource policies, an Amazon 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 Amazon 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 Amazon Web Services 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.amazonaws.cn/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 Amazon 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 Amazon resource policies, an Amazon 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.amazonaws.cn/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 Amazon Support](https://console.amazonaws.cn/support/home#/case/create) to regain access to the KMS key. The key policy statement shown above gives the [account principal](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-accounts) permission to control the key. The account principal represents the Amazon Web Services account and its administrators, including the [account root user](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_root-user.html). The account root user is the only principal that cannot be deleted unless you delete the Amazon Web Services 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 Amazon 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 Amazon 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 Amazon KMS console. ![\[Key administrators in the console's default key policy, default view\]](http://docs.amazonaws.cn/en_us/kms/latest/developerguide/images/console-key-policy-administrators-60.png) The following is an example key administrators statement in the policy view of the Amazon KMS console. This key administrators statement is for a single-Region symmetric encryption KMS key. **Note** The Amazon 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 [Amazon KMS permissions](kms-api-permissions-reference.md). When you use the Amazon 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 Amazon 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 Amazon Web Services 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.amazonaws.cn/kms/latest/APIReference/API_ListKeyPolicies.html](https://docs.amazonaws.cn/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 Amazon Web Services Management Console, are valid only in IAM policies.) **`kms:Put*`** Allows [https://docs.amazonaws.cn/kms/latest/APIReference/API_PutKeyPolicy.html](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_UpdateKeyDescription.html](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_GetParametersForImport.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetParametersForImport.html). For asymmetric KMS keys, it allows [https://docs.amazonaws.cn/kms/latest/APIReference/API_GetPublicKey.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetPublicKey.html). The `kms:GetKeyPolicy` permission is required to view the key policy of a KMS key in the Amazon Web Services 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 Amazon 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 Amazon KMS](abac.md). **`kms:ScheduleKeyDeletion`** Allows [https://docs.amazonaws.cn/kms/latest/APIReference/API_ScheduleKeyDeletion.html](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_CancelKeyDeletion.html](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_RotateKeyOnDemand.html](https://docs.amazonaws.cn/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).   Amazon KMS adds the following permissions to the default key administrators statement when you create special-purpose keys. **`kms:ImportKeyMaterial`** The [https://docs.amazonaws.cn/kms/latest/APIReference/API_ImportKeyMaterial.html](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_ReplicateKey.html](https://docs.amazonaws.cn/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 Amazon 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.amazonaws.cn/kms/latest/APIReference/API_UpdatePrimaryRegion.html](https://docs.amazonaws.cn/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 Amazon Web Services 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 Amazon services](#key-policy-service-integration) — The second policy statement gives key users permission to allow Amazon services that are integrated with Amazon 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 Amazon Web Services 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 Amazon Web Services 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.amazonaws.cn/en_us/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 [Amazon KMS permissions](kms-api-permissions-reference.md). When you use the Amazon 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 Amazon 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.amazonaws.cn/kms/latest/APIReference/API_DescribeKey.html)operation to get detailed information about the KMS key in the Amazon KMS console or by using the Amazon KMS API operations. By default, the Amazon 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.amazonaws.cn/kms/latest/APIReference/API_Encrypt.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_Encrypt.html) Allows key users to encrypt data with this KMS key. [https://docs.amazonaws.cn/kms/latest/APIReference/API_Decrypt.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_Decrypt.html) Allows key users to decrypt data with this KMS key. [https://docs.amazonaws.cn/kms/latest/APIReference/API_DeriveSharedSecret.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_DeriveSharedSecret.html) Allows key users to derive shared secrets with this KMS key. [https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeKey.html](https://docs.amazonaws.cn/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 Amazon 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.amazonaws.cn/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.amazonaws.cn/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), [GenerateDataKeyPair](https://docs.amazonaws.cn/kms/latest/APIReference/API_GenerateDataKeyPair.html), and [GenerateDataKeyPairWithoutPlaintext](https://docs.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_GenerateMac.html) Allows key users to use an HMAC KMS key to generate an HMAC tag. [kms:GetPublicKey](https://docs.amazonaws.cn/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 Amazon KMS. However, those ciphertexts can be decrypted only by calling the [Decrypt](https://docs.amazonaws.cn/kms/latest/APIReference/API_Decrypt.html) operation in Amazon KMS. [kms:ReEncrypt](https://docs.amazonaws.cn/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.amazonaws.cn/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.amazonaws.cn/kms/latest/APIReference/API_Sign.html) Allows key users to sign messages with this KMS key. [kms:Verify](https://docs.amazonaws.cn/kms/latest/APIReference/API_Verify.html) Allows key users to verify signatures with this KMS key. [kms:VerifyMac](https://docs.amazonaws.cn/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 Amazon services The default key policy in the console also gives key users the grant permissions they need to protect their data in Amazon services that use grants. Amazon 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 [Amazon service integrated with Amazon KMS](http://www.amazonaws.cn/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 Amazon 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 Amazon service that integrates with Amazon 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 Amazon 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 Amazon KMS](services-redshift.md). + Use this KMS key with other [Amazon services integrated with Amazon 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 Amazon 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 Amazon KMS [customer managed key](concepts.md#customer-mgn-key) or an [Amazon managed key](concepts.md#aws-managed-key) in your account by using the Amazon KMS console or the [GetKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetKeyPolicy.html) operation in the Amazon KMS API. You cannot use these techniques to view the key policy of a KMS key in a different Amazon Web Services account. To learn more about Amazon KMS key policies, see [Key policies in Amazon KMS](key-policies.md). To learn how to determine which users and roles have access to a KMS key, see [Determining access to Amazon KMS keys](determining-access.md). ## Using the Amazon KMS console Authorized users can view the key policy for an [Amazon managed key](concepts.md#aws-managed-key) or a [customer managed key](concepts.md#customer-mgn-key) on the **Key policy** tab of the Amazon Web Services Management Console. To view the key policy for a KMS key in the Amazon Web Services Management Console, you must have [kms:ListAliases](https://docs.amazonaws.cn/kms/latest/APIReference/API_ListAliases.html), [kms:DescribeKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeKey.html), and [kms:GetKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetKeyPolicy.html) permissions. 1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at [https://console.amazonaws.cn/kms](https://console.amazonaws.cn/kms). 1. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page. 1. To view the keys in your account that Amazon creates and manages for you, in the navigation pane, choose **Amazon 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 Amazon KMS console\]](http://docs.amazonaws.cn/en_us/kms/latest/developerguide/images/console-key-policy-view.png) Or, if you created the KMS key in the Amazon Web Services 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 Amazon KMS console\]](http://docs.amazonaws.cn/en_us/kms/latest/developerguide/images/console-key-policy-full-vsm.png) ## Using the Amazon KMS API To get the key policy for a KMS key in your Amazon Web Services account, use the [GetKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetKeyPolicy.html) operation in the Amazon 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.amazonaws.cn/cli/latest/reference/kms/get-key-policy.html) command in the Amazon Command Line Interface (Amazon CLI), but you can use any Amazon 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-cn:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] } ``` ------ # Change a key policy You can change the key policy for a KMS key in your Amazon Web Services account by using the Amazon Web Services Management Console or the [PutKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_PutKeyPolicy.html) operation. You cannot use these techniques to change the key policy of a KMS key in a different Amazon Web Services account. When changing a key policy, keep in mind the following rules: + You can view the key policy for an [Amazon 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 Amazon managed keys are created and managed by the Amazon service that created the KMS key in your account. You cannot view or change the key policy for an [Amazon owned key](concepts.md#aws-owned-key). + You can add or remove IAM users, IAM roles, and Amazon Web Services 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 Amazon Web Services 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 Amazon Web Services Management Console default view ](#key-policy-modifying-how-to-console-default-view) + [ ### Using the Amazon Web Services Management Console policy view ](#key-policy-modifying-how-to-console-policy-view) + [ ### Using the Amazon KMS API ](#key-policy-modifying-how-to-api) ### Using the Amazon Web Services 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 Amazon Web Services Management Console policy view](#key-policy-modifying-how-to-console-policy-view) or [Using the Amazon KMS API](#key-policy-modifying-how-to-api). 1. View the key policy for a customer managed key as described in [Using the Amazon KMS console](key-policy-viewing.md#key-policy-viewing-console). (You cannot change the key policies of Amazon 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 Amazon Web Services 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 Amazon Web Services 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 Amazon KMS console](key-policy-viewing.md#key-policy-viewing-console). (You cannot change the key policies of Amazon 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 Amazon KMS API You can use the [PutKeyPolicy](https://docs.amazonaws.cn/kms/latest/APIReference/API_PutKeyPolicy.html) operation to change the key policy of a KMS key in your Amazon Web Services account. You cannot use this API on a KMS key in a different Amazon Web Services account. 1. Use the [GetKeyPolicy](https://docs.amazonaws.cn/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 Amazon 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.amazonaws.cn/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 Amazon 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.amazonaws.cn/cli/latest/reference/kms/get-key-policy.html#examples) in the Amazon CLI Command Reference. # Permissions for Amazon services in key policies Many Amazon services use Amazon KMS keys to protect the resources they manage. When a service uses [Amazon owned keys](concepts.md#aws-owned-key) or [Amazon 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 Amazon 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 [Amazon global condition keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) and [Amazon 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: + **Amazon CloudTrail** permissions - [Configure Amazon KMS key policies for CloudTrail](https://docs.amazonaws.cn/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.amazonaws.cn/AWSEC2/latest/UserGuide/EBSEncryption.html#ebs-encryption-permissions) and [Amazon EC2 User Guide](https://docs.amazonaws.cn/AWSEC2/latest/WindowsGuide/EBSEncryption.html#ebs-encryption-permissions) + **Amazon Lambda** permissions - [Data encryption at rest for Lambda](https://docs.amazonaws.cn/lambda/latest/dg/security-encryption-at-rest.html) + **Amazon Q** permissions - [Data encryption for Amazon Q](https://docs.amazonaws.cn/amazonq/latest/qbusiness-ug/data-encryption.html) + **Amazon Relational Database Service** permissions - [Amazon KMS key management](https://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/Overview.Encryption.Keys.html) + **Amazon Secrets Manager** permissions - [Authorizing use of the KMS key](https://docs.amazonaws.cn/secretsmanager/latest/userguide/security-encryption.html#security-encryption-authz) + **Amazon Simple Queue Service** permissions - [Amazon SQS Key management](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)