A key policy is a resource-based policy attached to a KMS key — every KMS key must have exactly one key policy. Key policies control which Alibaba Cloud accounts, Resource Access Management (RAM) users, and RAM roles have permissions to manage or use KMS keys.
Key policies grant access to Alibaba Cloud accounts, Resource Access Management (RAM) users, and RAM roles. Within the current account, you can designate principals as key administrators or key users. Principals from other Alibaba Cloud accounts can only be designated as key users.
In this document:
How key policies and RAM policies work together
Key policies coexist with identity-based RAM policies. Together, they determine whether a request to access a KMS key is allowed.
The evaluation outcome depends on the request source:
Same-account access: A principal in the key-owning account can manage or use the key if Allow is returned and Explicit Deny is not returned in either Result A or Result B. Either a key policy in KMS or a RAM policy is sufficient — you do not need both.
Cross-account access: A principal from another account can use the key only if Allow is returned in both Result A and Result B. Both a key policy in KMS and a RAM policy in the external account are required.
The key-owning account is the Alibaba Cloud account used to create the key. To find the creator, open the KMS console, go to the key details page, and check Created By. Alternatively, call DescribeKey and check the Creator field. For details on Explicit Deny and Implicit Deny, see Policy evaluation process.
Granting cross-account access
Cross-account access requires two steps — both are mandatory:
In KMS: Add the external RAM user or RAM role as a principal in the key policy and grant the required usage permissions.
In the external account: Use that account to grant the RAM user or RAM role a RAM policy that allows access to the key.
If either step is missing, the cross-account request is denied. For details, see Custom policies, Grant permissions to a RAM user, and Grant permissions to a RAM role.
Limits and constraints
Key policies apply only to keys in KMS instances. Configure a key policy when you create a key, or modify it afterward. See Manage a key and Configure a key policy.
Key policies apply only when keys are accessed through a KMS endpoint. If you use a KMS instance endpoint, the permission policies configured on the associated application access points (AAPs) apply instead.
Granting cross-account access consumes the Access Management Quota of the KMS instance, calculated by the number of external Alibaba Cloud accounts. After you revoke cross-account permissions, if no resources of the KMS instance are shared to other Alibaba Cloud accounts, wait approximately 5 minutes for the quota to be restored.
A key policy must be in JSON format and cannot exceed 32,768 bytes.
Key policy structure
A key policy contains a Version and one or more Statement entries.
`Version`: Set to
1.`Statement`: Each statement contains the following fields.
Statement fields
| Field | Required | Description |
|---|---|---|
Sid | No | Statement identifier. Up to 128 characters: letters, digits, and _ / + = . @ -. |
Effect | Yes | Allow or Deny. |
Principal | Yes | The account, RAM user, or RAM role to grant access to. |
Action | Yes | The KMS API operations to allow or deny. Must start with kms:. |
Resource | Yes | Set to * to target the current key. |
Condition | No | Conditions for the policy to take effect. Format: "Condition": {"condition operator": {"condition key": "condition value"}}. See Policy elements and Condition keys. |
Supported principals
The Principal field accepts:
The current Alibaba Cloud account (
acs:ram::<account-id>:*)RAM users and RAM roles in the current account
RAM users and RAM roles in other Alibaba Cloud accounts (usage permissions only)
Action permissions scope
Only actions within the following scope take effect. Actions outside this scope are ignored.
Key management actions — for administrators:
"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"
]Key usage actions — for applications and services performing cryptographic operations:
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:GenerateAndExportDataKey",
"kms:AsymmetricEncrypt",
"kms:AsymmetricDecrypt",
"kms:DescribeKey",
"kms:DescribeKeyVersion",
"kms:ListKeyVersions",
"kms:ListAliasesByKeyId",
"kms:TagResource"
]Example key policy
The following policy applies to a key in the 119285303511**** account. It grants:
Full permissions (
kms:*) to the entire accountManagement permissions to
key_ramuser1in the same accountUsage permissions to
key_ramuser2in the same account andkey_ramuser3in the190325303126****account
{
"Statement": [
{
"Sid": "kms default key policy",
"Action": [
"kms:*"
],
"Effect": "Allow",
"Principal": {
"RAM": [
"acs:ram::119285303511****:*"
]
},
"Resource": [
"*"
]
},
{
"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"
],
"Effect": "Allow",
"Principal": {
"RAM": [
"acs:ram::119285303511****:user/key_ramuser1"
]
},
"Resource": [
"*"
]
},
{
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:GenerateAndExportDataKey",
"kms:AsymmetricEncrypt",
"kms:AsymmetricDecrypt",
"kms:DescribeKey",
"kms:DescribeKeyVersion",
"kms:ListKeyVersions",
"kms:ListAliasesByKeyId",
"kms:TagResource"
],
"Effect": "Allow",
"Principal": {
"RAM": [
"acs:ram::119285303511****:user/key_ramuser2",
"acs:ram::190325303126****:user/key_ramuser3"
]
},
"Resource": [
"*"
]
}
],
"Version": "1"
}