本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 补助金 AWS KMS
*授权*是一种策略分析工具，允许 [AWS 主体](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)将 KMS 密钥用于加密操作中。它还可以让他们查看 KMS 密钥 (`DescribeKey`) 以及创建和管理授权。在授权访问 KMS 密钥时，将考虑授权与[密钥策略](key-policies.md)和 [IAM policy](iam-policies.md)。授权通常用于临时权限，因为您可以在不更改密钥策略或 IAM policy 的情况下创建授权、使用其权限并将其删除。
与之集成的 AWS 服务通常使用赠款 AWS KMS 来加密您的静态数据。该服务代表账户中的用户创建授权，使用其权限，并在其任务完成后立即停用授权。有关 AWS 服务如何使用授权的详细信息，请参阅服务用户指南或开发者指南中的*静态加密*主题。
授权是一种非常灵活且有用的访问控制机制。当您为 KMS 密钥创建授权时，授权允许被授权主体对 KMS 密钥调用指定授权操作，前提是该授权中指定的所有条件都得到满足。
+ 每个授权只允许访问一个 KMS 密钥。您可以在不同的 AWS 账户中为 KMS 密钥创建授权。
+ 授权可以允许访问 KMS 密钥，但不能拒绝访问。
+ 每个授权都有一名[被授权主体](#terms-grantee-principal)。被授权者委托人可以代表一个或多个与 KMS 密钥 AWS 账户 相同的身份，也可以在不同的账户中代表一个或多个身份。
+ 授权只能允许[授权操作](#terms-grant-operations)。授权操作必须由授权中的 KMS 密钥支持。如果您指定了不支持的操作，则[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)请求会失败并出现`ValidationError`异常。
+ 被授权主体可以使用授权给予他们的权限，而无需指定授权，就像权限来自密钥策略或 IAM policy 一样。但是，由于 AWS KMS API 遵循[最终一致性](#terms-eventual-consistency)模型，因此当您创建、停用或撤销授权时，可能会有短暂的延迟，直到更改始终 AWS KMS可用。要立即使用授权中的权限，[请使用授权令牌](using-grant-token.md)。
+ 授权委托人可以删除授权（[停用](#terms-retire-grant)或者[撤销](#terms-revoke-grant)它）。删除授权会清除授权允许的所有权限。您不必确定要添加或删除哪些策略来撤销授权。
+ AWS KMS 限制每个 KMS 密钥的授权数量。有关更多信息，请参阅 [每个 KMS 密钥的授权数：50000](resource-limits.md#grants-per-key)。
在创建授权和给予其他人创建授权的权限时务必谨慎。创建授权的权限会带来安全影响，就像允许 [kms: PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) 权限设置策略一样。
+ 有权为 KMS 密钥创建授权的用户可以使用授权来允许用户和角色（包括 AWS 服务`kms:CreateGrant`）使用 KMS 密钥。委托人可以是您自己的身份，也可以是其他账户 AWS 账户 或组织中的身份。
+ 授权只能允许一部分 AWS KMS 操作。您可以使用授权允许委托人查看 KMS 密钥，在加密操作中使用它，以及创建和停用授权。有关详细信息，请参阅[授权操作](#terms-grant-operations)。您还可以使用[授权约束](create-grant-overview.md#grant-constraints)来限制对称加密密钥授权中的权限。
+ 委托人可以获得从密钥策略或 IAM policy 创建授权的权限。通过策略获得的 `kms:CreateGrant` 权限的主体可以为基于 KMS 密钥的任何[授权操作](#terms-grant-operations)创建授权。这些主体无需拥有他们对密钥的授权权限。当您在策略中允许 `kms:CreateGrant` 权限时，您可以使用[策略条件](grant-authorization.md)来限制此权限。
+ 委托人还可以获得从授权创建授权的权限。这些主体只能委派他们被授予的权限，即使他们具有来自策略的其他权限也是如此。有关更多信息，请参阅 [授予 CreateGrant 权限](create-grant-overview.md#grant-creategrant)。
## 授权概念
为了有效地使用授权，您需要了解 AWS KMS 使用的术语和概念。
**授权约束**
限制授权中的权限的条件。目前， AWS KMS 支持基于加密操作请求中的[加密上下文](encrypt_context.md)的授予限制。有关更多信息，请参阅 [使用授权约束](create-grant-overview.md#grant-constraints)。
**授权 ID**
KMS 密钥的授权的唯一标识符。您可以使用授权 ID 和[密钥标识符](concepts.md#key-id)来标识[RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html)或[RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html)请求中的授权。
**授权操作**
您可以在授权中允许的 AWS KMS 操作。如果您指定其他操作，则[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)请求会失败，但会出现`ValidationError`异常。这些也是接受[授权令牌](#grant_token)的操作。有关这些权限的详细信息，请参阅 [AWS KMS 权限](kms-api-permissions-reference.md)。
这些授权操作实际上代表使用操作的权限。因此，对于 `ReEncrypt` 操作，您可以指定 `ReEncryptFrom`、`ReEncryptTo` 或此两者 `ReEncrypt*`。
授权操作包括：
+ 加密操作
+ [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)
+ 其他操作
+ [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)
您允许的授权操作必须由授权中的 KMS 密钥支持。如果您指定了不支持的操作，则[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)请求会失败并出现`ValidationError`异常。例如，对称加密 KMS 密钥的授权不能允许 [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) 或 [https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) 操作。非对称 KMS 密钥的授权不能允许生成数据密钥或数据密钥对的操作。
**授权令牌**
AWS KMS API 遵循[最终一致性](#terms-eventual-consistency)模型。当您创建授权时，可能会出现短暂的延迟，才能使更改在整个 AWS KMS中可用。更改通常需要不到几秒钟的时间即可在整个系统中传播，但在某些情况下，可能需要几分钟。如果您尝试在系统中完全传播之前使用授权，您可能会收到访问被拒绝的错误。授权令牌允许您引用授权并立即使用授权权限。
*授权令牌*是代表授权的唯一、非秘密、长度可变的 base64 编码字符串。您可以使用授权令牌来标识任何[授权操作](#terms-grant-operations)中的授权。但是，由于令牌值是哈希摘要，它不会显示有关授权的任何详细信息。
授权令牌设计为仅在授权传播到整个 AWS KMS中时使用。之后，[被授权者委托人](#terms-grantee-principal)可以在不提供授权令牌或授权的任何其他证据的情况下使用授权中的权限。您可以随时使用授权令牌，但是一旦授权最终保持一致，就 AWS KMS 使用授权而不是授权令牌来确定权限。
例如，以下命令调用该[GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)操作。它使用授权令牌来表示给予调用者（被授权者委托人）对指定的 KMS 密钥调用 `GenerateDataKey` 的权限的授权。
```
$ aws kms generate-data-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-spec AES_256 \
--grant-token $token
```
您还可以使用授权令牌来标识管理授权的操作中的授权。例如，[即将退休的委托](#terms-retiring-principal)人可以在调用[RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html)操作时使用授权令牌。
```
$ aws kms retire-grant \
--grant-token $token
```
`CreateGrant` 是返回授权令牌的唯一操作。您无法从任何其他 AWS KMS 操作或该操作的[CloudTrail 日志事件](ct-creategrant.md)中获取授权令牌。 CreateGrant [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html)和[ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html)操作返回[授权 ID](#terms-grant-id)，但不返回授权令牌。
有关更多信息，请参阅 [使用授权令牌](using-grant-token.md)。
**被授权者委托人**
获取授权中指定的权限的身份。每个授权都有一个被授权主体，但被授权主体可以代表多个身份。
被授权者委托人可以是任何 AWS 委托人，包括 AWS 账户 （根）、I [AM 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)、[IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)[、联合角色或用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)或代入角色用户。被授权者委托人可以与 KMS 密钥位于同一账户中，也可以位于不同的账户中。但是，被授权者委托人不能是[服务委托人](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services)、[IAM 组](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html)，或 [AWS 组织](https://docs.aws.amazon.com/organizations/latest/userguide/)。
IAM 最佳实践不鼓励使用具有长期凭证的 IAM 用户。而应尽可能使用提供临时凭证的 IAM 角色。有关更多信息，请参阅《IAM 用户指南》中的 [IAM 安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)**。
**停用（授权）**
终止授权。当您使用完权限时，将停用授权。
撤销和停用授权都会删除授权。但是，停用由授权中指定的委托人完成。撤消通常由密钥管理员执行。有关更多信息，请参阅 [停用和撤销授权](grant-delete.md)。
**停用委托人**
可以[停用授权](#terms-retire-grant)的委托人。您可以在授权中指定停用委托人，但这不是必需的。即将退出的委托人可以是任何 AWS 委托人，包括 AWS 账户 IAM 用户、IAM 角色、联合用户和代入角色用户。停用委托人可以与 KMS 密钥位于同一账户中，也可以位于不同的账户中。
IAM 最佳实践不鼓励使用具有长期凭证的 IAM 用户。而应尽可能使用提供临时凭证的 IAM 角色。有关更多信息，请参阅《IAM 用户指南》中的 [IAM 安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)**。
除了补助金中规定的退休本金外，补助金还可由设立补助金 AWS 账户 的所在地收回。如果授权允许 `RetireGrant` 操作，[被授权者委托人](#terms-grantee-principal)可以停用授权。此外，即将退休 AWS 账户 的委托人 AWS 账户 或可以将撤回补助金的权限委托给同 AWS 账户一个IAM委托人。有关更多信息，请参阅 [停用和撤销授权](grant-delete.md)。
**撤销（授予）**
终止授权。您将撤销积极拒绝授权允许的权限的授权。
撤销和停用授权都会删除授权。但是，停用由授权中指定的委托人完成。撤消通常由密钥管理员执行。有关更多信息，请参阅 [停用和撤销授权](grant-delete.md)。
**最终一致性（用于授权）**
AWS KMS API 遵循[最终一致性](https://en.wikipedia.org/wiki/Eventual_consistency)模型。当您创建、停用或撤销授权时，可能会出现短暂的延迟，才能使更改在整个 AWS KMS中可用。更改通常需要不到几秒钟的时间即可在整个系统中传播，但在某些情况下，可能需要几分钟。
如果您遇到意外错误，您可能会注意到这个短暂的延迟。例如，如果您尝试管理新的授权，或者在新授权中使用这些权限 AWS KMS，则可能会收到拒绝访问的错误。如果您停用或撤销授权，则被授权者委托人可能仍然能够在短时间内使用其权限，直到完全删除该授权为止。典型的策略是重试请求，有些策略 AWS SDKs 包括自动退避和重试逻辑。
AWS KMS 具有缓解这种短暂延迟的功能。
+ 要立即使用新授权中的权限，请使用[授权令牌](using-grant-token.md)。您可以使用授权令牌来引用任何[授权操作](#terms-grant-operations)中的授权。有关说明，请参阅[使用授权令牌](using-grant-token.md)。
+ 该[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)操作具有防止重试操作创建重复授权的`Name`参数。
授权令牌将取代授权的有效性，直到服务中的所有终端节点都使用新的授权状态更新为止。在大多数情况下，最终一致性将在五分钟内实现。
有关更多信息，请参阅[AWS KMS 最终一致性](accessing-kms.md#programming-eventual-consistency)。
# AWS KMS 补助金的最佳实践
AWS KMS 建议在创建、使用和管理拨款时采用以下最佳做法。
+ 将授权中的权限限制为被授权者委托人所需的权限。使用[最小特权访问权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)的原则。
+ 使用特定的被授权者委托人（如 IAM 角色），并授予被授权委托人仅使用他们所需的 API 操作的权限。
+ 使用加密上下文[授权约束](grants.md#terms-grant-constraint)以确保调用方正在将 KMS 密钥用于预期目的。有关如何在请求中使用加密上下文来保护数据的详细信息，请参阅*AWS 安全博客 EncryptionContext*中的[如何使用 AWS Key Management Service 和保护加密数据的完整性](https://aws.amazon.com/blogs/security/how-to-protect-the-integrity-of-your-encrypted-data-by-using-aws-key-management-service-and-encryptioncontext/)。
**提示**
尽可能使用[EncryptionContextEqual](create-grant-overview.md#grant-constraints)授权约束。[EncryptionContextSubset](create-grant-overview.md#grant-constraints)授权约束更难正确使用。如果您需要使用它，请仔细阅读文档并测试授权约束以确保它按预期工作。
+ 删除重复的授权。重复授权具有相同的密钥 ARN、API 操作、被授权者委托人、加密上下文和名称。如果您停用或撤销原始授予，但保留重复项授权，则剩余的重复授权将构成意外的权限提升。为了在重试 `CreateGrant` 请求时避免重复授权，请使用 [`Name` 参数](create-grant-overview.md#grant-create)。要检测重复的授权，请使用[ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html)操作。如果您意外创建了重复授权，请尽快停用或撤销该授权。
**注意**
[AWS 托管密钥](concepts.md#aws-managed-key)的授权可能看起来像重复授权，但具有不同的被授权者委托人。
`ListGrants` 响应中的 `GranteePrincipal` 字段通常包含授权的被授权者委托人。但是，当赠款中的受赠方委托人是 AWS 服务时，该`GranteePrincipal`字段包含[服务委托](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services)人，它可能代表几个不同的受赠方委托人。
+ 请记住，授权不会自动过期。当权限不再需要时，立即[停用或撤销授权](grant-delete.md)。未删除的授权可能会对加密资源造成安全风险。
# 控制对授权的访问
您可以控制对在密钥策略、IAM policy 和授权中创建和管理授权的操作的访问权限。从授权中获得 `CreateGrant` 权限的委托人具有[更有限的授权权限](create-grant-overview.md#grant-creategrant)。
| API 操作 | 密钥策略或 IAM policy | 授权 |
| --- | --- | --- |
| CreateGrant | ✓ | ✓ |
| ListGrants | ✓ | - |
| ListRetirableGrants | ✓ | - |
| 停用授权 | （有限。请参阅 [停用和撤销授权](grant-delete.md)） | ✓ |
| RevokeGrant | ✓ | - |
当您使用密钥策略或 IAM 策略来控制对创建和管理授权的操作的访问权限时，您可以使用以下一个或多个策略条件来限制权限。 AWS KMS 支持以下所有与 Grant 相关的条件键。有关详细信息和示例，请参阅 [AWS KMS 条件键](conditions-kms.md)。
[kms: GrantConstraintType](conditions-kms.md#conditions-kms-grant-constraint-type)
允许委托人仅在授权包含指定的[授权约束](create-grant-overview.md#grant-constraints)时创建授权。
[kms: GrantIsFor AWSResource](conditions-kms.md#conditions-kms-grant-is-for-aws-resource)
`RevokeGrant`仅当[与之集成的 AWS 服务代表委托人 AWS KMS发送请求时，](https://aws.amazon.com/kms/features/#AWS_Service_Integration)才允许委托人拨打`CreateGrant``ListGrants`、或。
[kms: GrantOperations](conditions-kms.md#conditions-kms-grant-operations)
允许委托人创建授权，但将授权限制为指定操作。
[kms: GranteePrincipal](conditions-kms.md#conditions-kms-grantee-principal)
允许委托人仅为指定的[被授权者委托人](grants.md#terms-grantee-principal)创建授权。
[kms: RetiringPrincipal](conditions-kms.md#conditions-kms-retiring-principal)
允许委托人仅在授权指定特定的[停用委托人](grants.md#terms-retiring-principal)时创建授权。
# 创建授权
在创建授权之前，请了解用于自定义授权的选项。您可以使用*授权约束*来限制授权中的权限。此外，了解授予 `CreateGrant` 权限的相关信息。获得从授权创建授权的权限的委托人在其可以创建的授权中受到限制。
**Topics**
+ [创建授予](#grant-create)
+ [授予 CreateGrant 权限](#grant-creategrant)
## 创建授予
要创建授权，请调用该[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)操作。指定 KMS 密钥，[被授权者委托人](grants.md#terms-grantee-principal)，以及允许的[授权操作](grants.md#terms-grant-operations)的列表。您还可以指定一个可选的[停用委托人](grants.md#terms-retiring-principal)。要自定义授权，请使用可选 `Constraints` 参数来定义[授予约束](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html)。
当您创建、停用或撤销授权时，可能会出现短暂的延迟（通常不到五分钟），才能使更改在整个 AWS KMS中可用。有关更多信息，请参阅[最终一致性（用于授权）](grants.md#terms-eventual-consistency)。
例如，以下 `CreateGrant` 命令会创建一个授权，以允许被授权代入 `keyUserRole` 角色的用户对指定的 [对称 KMS 密钥](symm-asymm-choose-key-spec.md#symmetric-cmks) 调用 [解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 操作。授权使用 `RetiringPrincipal` 参数，指定可以停用授权的委托人。其中还包含一个授权约束，仅当请求中的[加密上下文](encrypt_context.md)包含 `"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}
```
如果您的代码重试 `CreateGrant` 操作，或者使用[自动重试请求的AWS SDK](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)，请使用可选的 [Name](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-Name) 参数来防止创建重复授权。如果 AWS KMS 收到的授权`CreateGrant`请求具有与现有授权相同的属性（包括名称），则它会将该请求识别为重试，并且不会创建新的授权。您无法使用 `Name` 值来标识任何 AWS KMS 操作中的授权。
**重要**
不要在授权名称中包含机密或敏感信息。它可能以纯文本形式出现在 CloudTrail 日志和其他输出中。
```
$ 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}
```
有关演示如何通过多种编程语言创建授权的代码示例，请参阅 [`CreateGrant`与 AWS SDK 或 CLI 配合使用](example_kms_CreateGrant_section.md)。
### 使用授权约束
[授权约束](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html)设置授权给予被授权者委托人的权限的条件。授权约束取代[密钥策略](key-policies.md)或 [IAM policy](iam-policies.md) 中的[条件键](policy-conditions.md)。每个授权约束值最多可以包含 8 个加密上下文对。每个授权约束中的加密上下文值不能超过 384 个字符。
**重要**
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
AWS KMS 支持两个授予限制，`EncryptionContextEquals`和`EncryptionContextSubset`，这两个约束都规定了[加密操作请求中的加密上下](encrypt_context.md)文的要求。
加密上下文授权约束旨在与具有加密上下文参数的[授权操作](grants.md#terms-grant-operations)结合使用。
+ 加密上下文约束仅在对称加密 KMS 密钥的授权中有效。使用其他 KMS 密钥的加密操作不支持加密上下文。
+ 对于 `DescribeKey` 和 `RetireGrant` 操作，加密上下文约束将被忽略。`DescribeKey` 和 `RetireGrant` 不包括加密上下文参数，但您可以将这些操作包含在具有加密上下文约束的授权中。
+ 您可以将授权中的加密上下文约束用于 `CreateGrant` 操作。加密上下文约束要求使用 `CreateGrant` 权限创建的任何授权具有同样严格或更严格的加密上下文约束。
AWS KMS 支持以下加密上下文授予限制。
**EncryptionContextEquals**
使用 `EncryptionContextEquals` 为允许的请求指定精确的加密上下文。
`EncryptionContextEquals` 要求请求中的加密上下文对与授权约束中加密上下文对区分大小写的完全匹配。上下文对可以按任意顺序显示，不过每一对中的键和值不能有改变。
例如，如果 `EncryptionContextEquals` 授权约束需要 `"Department": "IT"` 加密上下文对，则授权仅在请求中的加密上下文完全是 `"Department": "IT"` 时，允许指定类型的请求。
**EncryptionContextSubset**
使用 `EncryptionContextSubset` 来要求请求包含特定的加密上下文对。
`EncryptionContextSubset` 要求请求中包含授权约束中的所有加密上下文对（区分大小写的完全匹配），但请求也可以包含其他的加密上下文对。上下文对可以按任意顺序显示，不过每一对中的键和值不能有改变。
例如，如果 `EncryptionContextSubset` 授权约束需要 `Department=IT` 加密上下文对，则授权在请求中的加密上下文为 `"Department": "IT"` 或者包含 `"Department": "IT"` 以及其他加密上下文对（例如 `"Department": "IT","Purpose": "Test"`）时，允许指定类型的请求。
要在对称加密 KMS 密钥的授权中指定加密上下文约束，请在[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)操作中使用`Constraints`参数。此命令创建的授权将向被授权代入 `keyUserRole` 角色的用户调用 [解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 操作的权限。不过，该权限仅在 `Decrypt` 请求中的加密上下文是 `"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 EncryptionContextEquals={Department=IT}
```
生成的授权与以下项目类似。请注意，向 `keyUserRole` 角色授予的权限仅在 `Decrypt` 请求使用授权约束中指定的相同加密上下文对时有效。要查找 KMS 密钥的授权，请使用[ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html)操作。
```
$ 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"
}
]
}
```
为了满足 `EncryptionContextEquals` 授权约束，`Decrypt` 操作的请求中的加密上下文必须是 `"Department": "IT"` 对。来自被授予者委托人的以下请求将满足 `EncryptionContextEquals` 授权约束。
```
$ 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
```
当授权约束为 `EncryptionContextSubset` 时，请求中的加密上下文对必须在授权约束中包含加密上下文对，不过请求也可以包括其他加密上下文对。以下授权约束要求请求中的一个加密上下文对是 `"Deparment": "IT"`。
```
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
```
来自被授权者委托人的以下请求将满足本示例中 `EncryptionContextEqual` 和 `EncryptionContextSubset` 授权约束的要求。
```
$ 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
```
但是，来自被授权者委托人的以下请求将满足 `EncryptionContextSubset` 授权约束，但不满足 `EncryptionContextEquals` 授权约束。
```
$ 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 服务通常在授权中使用加密上下文限制，从而允许他们在您的中使用 KMS 密钥 AWS 账户。例如，Amazon DynamoDB 使用类似下面的授权来获得为账户中的 DynamoDB 使用 [AWS 托管式密钥](concepts.md#aws-managed-key) 的权限。此授权中的 `EncryptionContextSubset` 授权约束使授权中的权限仅在请求中的加密上下文包含 `"subscriberID": "111122223333"` 和 `"tableName": "Services"` 对时有效。此授权约束意味着，授权仅允许 DynamoDB 将指定的 KMS 密钥用于 AWS 账户中的特定表。
要获得此输出，请在您的账户中[ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html)对 Dynam AWS 托管式密钥 oDB 运行该操作。
```
$ 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"
}
]
}
```
## 授予 CreateGrant 权限
授权可以包括调用 `CreateGrant` 操作的权限。但是，当[被授权者委托人](grants.md#terms-grantee-principal)获取从授权中，而不是从策略中调用 `CreateGrant` 的权限时，该权限将收到限制。
+ 被授权者委托人只能创建允许父授权中部分或全部操作的授权。
+ 他们创建的授权中的[授权约束](#grant-constraints)必须至少与父授权中的约束一样严格。
这些限制不适用于从策略中获取 `CreateGrant` 权限的委托人，尽管它们的权限可以由[策略条件](grant-authorization.md)限制。
例如，考虑一个授权，该授权允许被授权委托人调用 `GenerateDataKey`、`Decrypt` 和 `CreateGrant` 操作。我们将允许 `CreateGrant` 权限的授权称为*父授权*。
```
# 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"
}
},
}
]
}
```
被授权者委托人 exampleUser 可以使用此权限创建授权，其中包括在原始授权中指定的操作的任意子集，例如 `CreateGrant` 和 `Decrypt`。*子级授权*不能包含其他操作，如 `ScheduleKeyDeletion` 或者 `ReEncrypt`。
此外，子授权中的[授权约束](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html)必须与父授权具有相同的限制或更严格的限制。例如，子授权可以添加对到父授权中的 `EncryptionContextSubset` 约束，但不能从中删除对。子授权可以将 `EncryptionContextSubset` 约束更改为 `EncryptionContextEquals` 约束，但不能反之。
IAM 最佳实践不鼓励使用具有长期凭证的 IAM 用户。而应尽可能使用提供临时凭证的 IAM 角色。有关更多信息，请参阅《IAM 用户指南》中的 [IAM 安全最佳实践](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)**。
例如，被授权者委托人可以使用从父级授权那里获得的 `CreateGrant` 权限以创建以下子级授权。子级授权中的操作是父级授权中操作的子集，并且授权约束更严格。
```
# 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"
}
},
}
]
}
```
子级授权中的被授权者委托人 `anotherUser` 可以使用它们的 `CreateGrant` 权限来创建授权。然而，`anotherUser` 创建的授权必须将操作包含在其父授权或子集中，并且授权约束必须相同或更严格。
# 查看授权
要查看授权，请使用[ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html)操作。您必须指定授权所适用的 KMS 密钥。您还可以按授权 ID 或被授权者委托人筛选授权列表。有关更多示例，请参阅[`ListGrants`与 AWS SDK 或 CLI 配合使用](example_kms_ListGrants_section.md)。
要查看 AWS 账户 和地区中具有特定[退休本金的所有补助金](grants.md#terms-retiring-principal)，请使用[ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html)。响应包括每项授权的详细信息。
**注意**
`ListGrants` 响应中的 `GranteePrincipal` 字段通常包含授权的被授权者委托人。但是，当赠款中的受赠方委托人是 AWS 服务时，该`GranteePrincipal`字段包含[服务委托](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services)人，它可能代表几个不同的受赠方委托人。
例如，以下命令列出 KMS 密钥的所有授权。
```
$ 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"
]
}
]
}
```
# 使用授权令牌
AWS KMS API 遵循[最终一致性](grants.md#terms-eventual-consistency)模型。创建授权时，授权可能不会立即生效。可能会出现短暂的延迟，才能使更改在整个 AWS KMS中可用。更改通常需要不到几秒钟的时间即可在整个系统中传播，但在某些情况下，可能需要几分钟。更改完全传播到整个系统后，被授权者主体可以使用授权中的权限，而无需指定授权令牌或授权的任何证据。但是，如果拨款过于新以至于所有人都不知道 AWS KMS，则请求可能会因`AccessDeniedException`错误而失败。
要立即使用新授权中的权限，请使用该授权的[授权令牌](grants.md#grant_token)。保存[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)操作返回的授权令牌。然后在 AWS KMS 操作请求中提交授权令牌。您可以向任何 AWS KMS 授权[操作](grants.md#terms-grant-operations)提交授权令牌，也可以在同一个请求中提交多个授权令牌。
以下示例使用该`CreateGrant`操作创建允许[GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)和[解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)操作的授权。它将保存 `CreateGrant` 在 `token` 变量中返回的授权令牌。然后，在调用 `GenerateDataKey` 操作时，它使用 `token` 变量中的授权令牌。
```
# 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
```
具有权限的主体也可以使用授权令牌来停用新授权，即使授权在整个 AWS KMS中可用之前。（`RevokeGrant` 操作不接受授权令牌。） 有关更多信息，请参阅 [停用和撤销授权](grant-delete.md)。
```
# Retire the grant
$ aws kms retire-grant --grant-token $token
```
# 停用和撤销授权
要删除某个授权，请停用或撤销该授权。
[RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html)和[RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html)操作彼此非常相似。这两个操作都会删除授权，从而消除授权允许的权限。这些操作之间的主要区别在于它们是如何获得授权的。
**RevokeGrant**
与大多数 AWS KMS 操作一样，对`RevokeGrant`操作的访问权限通过[密钥策略](key-policies.md)和 [IAM 策略](iam-policies.md)进行控制。任何`kms:RevokeGrant`获得许可的委托人都可以调用[RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html)该 API。该权限包含在授予给密钥管理员的标准权限中。通常，管理员会撤销授权以拒绝授权允许的权限。
**RetireGrant**
授权决定谁可以停用它。此设计使您能够控制授权的生命周期，而无需更改密钥策略或 IAM policy。通常，当您使用授权的权限时，将停用授权。
授权可以通过授权中指定的可选[停用委托人](grants.md#terms-retiring-principal)停用。[被授权者委托人](grants.md#terms-grantee-principal)还可以停用授权，但只有当他们也是停用委托人或者授权包括 `RetireGrant` 操作时。作为备份，创建补助金 AWS 账户 的用户可以停用补助金。
有一个可用于 IAM policy 的 `kms:RetireGrant` 权限，但它具有有限的实用工具。授权中指定的委托人无需 `kms:RetireGrant` 权限即可停用授权。单独的 `kms:RetireGrant` 权限不允许委托人停用授权。`kms:RetireGrant` 权限在[密钥策略](key-policies.md)或[资源控制策略](resource-control-policies.md)中无效。
+ 要拒绝停用授权的权限，您可以使用 IAM 策略中的 `kms:RetireGrant` 权限来执行 `Deny` 操作。
+ 拥有 KMS 密钥的人可以将`kms:RetireGrant`权限委托给账户中的 IAM 委托人。 AWS 账户
+ 如果即将退休的委托人不同 AWS 账户，则另一个账户中的管理员可以使用`kms:RetireGrant`向该账户中的 IAM 委托人委托人委托授予撤销授权。
AWS KMS API 遵循[最终一致性](grants.md#terms-eventual-consistency)模型。当您创建、停用或撤销授权时，可能会出现短暂的延迟，才能使更改在整个 AWS KMS中可用。更改通常需要不到几秒钟的时间即可在整个系统中传播，但在某些情况下，可能需要几分钟。如果您需要在新的授权开始使用之前立即将其删除 AWS KMS，[请使用授权令牌](using-grant-token.md)停用该授权。您不能使用授权令牌撤销授权。