Detailed introduction to key policies - Key Management Service

A key policy is a resource-based policy that controls which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use a KMS key. Each key in a KMS instance must have exactly one key policy. This topic provides detailed information about key policies.

Relationship between key policies and RAM policies

Policy description

Key policies and RAM policies control access to KMS keys from different dimensions. After you add RAM users or RAM roles to a key policy, you can also configure RAM policies to manage the KMS operation permissions for those RAM users or RAM roles.

Key Policy: A resource-based policy attached to a specific key. It specifies which identities (RAM users, RAM roles, or Alibaba Cloud accounts) can manage or use the key. For more information, see Configure a key policy.
RAM policy: An identity-based policy attached to a RAM user or RAM role. It specifies which KMS operations the identity can perform. For more information, see Manage RAM user permissions, Manage permissions for a RAM role, and Custom policies.

Permission evaluation priority

RAM users or RAM roles under the current account (key creator account):
- Evaluation principle: "Any Allow is sufficient" (OR logic). Access is allowed if either of the following conditions is met and there is no Explicit Deny.
  Note
  For more information about Explicit Deny and Implicit Deny, see How RAM evaluates policies.
  - The KMS key policy explicitly allows the user or role.
  - The RAM policy explicitly allows the user or role.
- Detailed rules:
  KMS key policy (resource-based)
  RAM policy (identity-based)
  Evaluation result
  Allow
  Not configured
  Allow
  Not configured
  Allow
  Allow
  Allow
  Allow
  Allow
  Allow
  Deny
  Deny
  Deny
  Allow
  Deny
  Not configured
  Not configured
  Deny
RAM users or RAM roles under a different account (cross-account):
- Evaluation principle: "Both must allow" (AND logic). Access is allowed only when both of the following conditions are met.
  - The KMS key policy explicitly allows the external user or role (or external account).
  - The RAM policy explicitly allows the external user or role to call KMS operations.
- Detailed rules:
  KMS key policy (resource-based)
  RAM policy (identity-based)
  Evaluation result
  Allow
  Deny
  Deny
  Deny
  Allow
  Deny
  Allow
  Allow
  Allow
  Not configured
  Not configured
  Deny

Usage notes

Key policies apply only to keys within a KMS instance. You can configure a key policy during key creation or modify it afterward. For more information, see Create a key and Configure a key policy.
Authorizing RAM users or roles from other Alibaba Cloud accounts consumes the Accounts in Use quota of the KMS instance, calculated based on the number of Alibaba Cloud accounts. If you revoke cross-account authorization and the instance no longer shares resources with that account, wait approximately 5 minutes before checking the quota. The quota will be returned.
A key policy applies only to access control when you access a key through the KMS service endpoint. If you access a key through a KMS instance endpoint, access depends on the permission policy configured in the Application Access Point (AAP).
A key policy must be in JSON format and cannot exceed 32,768 bytes in length.

Key policy structure

A complete key policy contains the following elements:

Version: The version of the key policy. Currently, only version 1 is supported.
Statement: The statements of the key policy. Each key policy contains one or more statements. Each statement contains the following parameters.
- Sid
  Optional. A custom statement identifier. The identifier can be up to 128 characters in length and can contain uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and the following special characters: _ / + = . @ -
- Effect
  Required. Specifies whether to allow or deny the actions in the statement. Valid values: Allow or Deny.
- Principal
  Required. The identity to which the policy applies. You can specify one of the following:
  - The current Alibaba Cloud account, which is the account that owns the key.
  - RAM users or RAM roles under the current Alibaba Cloud account.
  - RAM users or RAM roles under a different Alibaba Cloud account.
    Important
    After you authorize RAM users or roles from another Alibaba Cloud account, you must also use the Alibaba Cloud account that manages those RAM identities to grant them permission to use the key in RAM. Otherwise, the RAM identities cannot use the key.
    For more information, see Custom policies, Manage RAM user permissions, and Manage permissions for a RAM role.
- Action
  Required. The API operations to allow or deny. The value must start with "kms:". Only the following operations are valid. Operations outside this list will not take effect.
  Permission list
```
 "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:Create*",
                "kms:Enable*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Set*",
                "kms:Update*",
                "kms:Delete*",
                "kms:Cancel*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ImportKeyMaterial",
                "kms:ScheduleKeyDeletion"
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
                "kms:TagResource"
            ]
```
- Resource
  Required. The target resource to which the policy applies. The Resource value can only be *, which indicates the current KMS key.
- Condition
  Optional. The conditions under which the policy takes effect. A condition element, also called a condition block, consists of one or more condition clauses. Each clause contains a condition operator, a condition key, and a condition value. For more information, see Permission policy elements.
  The format is "Condition": {"condition operator": {"condition key": "condition value"}}.
  - condition operator: For more information, see Condition operator types.
  - condition key and condition value: For the condition keys and valid values supported by key policies, see Policy condition keys.

FAQ

How do I view the key creator?

Console: Log on to the KMS console. On the Keys page, open the key details page and view the Created By.
API: Call the DescribeKey operation. The Creator field in the response indicates the key creator.

KMS key policy (resource-based)	RAM policy (identity-based)	Evaluation result
Allow	Not configured	Allow
Not configured	Allow	Allow
Allow	Allow	Allow
Allow	Deny	Deny
Deny	Allow	Deny
Not configured	Not configured	Deny