本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立授予
建立授予之前，請先了解自訂授予的選項。您可以使用*授予限制條件*以限制授予中的許可。此外，了解授予 `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)呼叫 [Decrypt](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 開發套件](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)，則請使用選用[名稱](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 政策](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` 角色的使用者呼叫 [Decrypt](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 僅針對您 AWS 帳戶中的特定資料表使用指定的 KMS 金鑰。
若要取得此輸出，請在您帳戶中 AWS 受管金鑰 適用於 DynamoDB 的 上執行 [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) 操作。
```
$ 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` 建立的授予必須在其父項授予或子集中包含操作，並且授予限制條件必須相同或更嚴格。