建立授予

建立授予之前，請先了解自訂授予的選項。您可以使用授予限制條件以限制授予中的許可。此外，了解授予 CreateGrant 許可。從授予取得建立授予之許可的主體，在其可以建立的授予中受到限制。

主題

建立授與
授與 CreateGrant 許可

建立授與

若要建立授予，請呼叫 CreateGrant 操作。指定 KMS 金鑰、允許的授予操作清單，以及承授者委託人或承授者服務委託人。

當您指定承授者委託人時，您可以選擇指定淘汰委託人或淘汰服務委託人，並使用 Constraints 參數來定義授予限制。當您指定承授者服務主體時，您必須包含SourceArn授予限制條件。您也必須指定 RetiringServicePrincipal或 RetiringPrincipal。

當您建立、淘汰或撤銷授予時，可能會有短暫的延遲 (通常不到五分鐘)，然後才會在整個 AWS KMS中可用。如需詳細資訊，請參閱最終一致性模式 (授權)。

例如，下列 CreateGrant 命令會建立授予，以允許被授權擔任 keyUserRole 角色的使用者對指定的對稱 KMS 金鑰呼叫 Decrypt 操作。授權會使用 RetiringPrincipal 參數指定可淘汰授權的主體。同時也包含授權限制條件，僅當請求中的加密內容包含 "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 開發套件，則請使用選用名稱參數，以防止建立重複授予。如果 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 使用。

使用授予限制條件

授予限制條件會在為承授者主體提供授予的許可上設定條件。授予限制條件會取代金鑰政策或 IAM 政策中的條件索引鍵。

重要

請勿在此欄位包含機密或敏感資訊。此欄位可能在 CloudTrail 日誌與其他輸出中以純文字顯示。

AWS KMS 支援兩種類型的授予限制：加密內容限制和SourceArn限制。

加密內容限制條件

加密內容限制條件會在密碼編譯操作的請求中建立加密內容的要求。每個加密內容授予限制值最多可包含 8 個加密內容對。每個限制條件中的加密內容值不能超過 384 個字元。

加密內容限制條件僅在對稱加密 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 操作中的 Constraints 參數。此命令建立的授予會給予被授權擔任 keyUserRole 角色的使用者呼叫 Decrypt 操作的許可。但是，僅當 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 操作。


$ 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 受管金鑰的許可。此 EncryptionContextSubset 授與中的授與限制只有在請求中的加密內容包含 "subscriberID": "111122223333" 和 "tableName": "Services" 對時，才會讓授與中的許可生效。此授予限制條件表示授予允許 DynamoDB 僅針對您 AWS 帳戶中的特定資料表使用指定的 KMS 金鑰。

若要取得此輸出，請在您帳戶中 AWS 受管金鑰適用於 DynamoDB 的上執行 ListGrants 操作。


$ 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"
        }
    ]
}

SourceArn 限制條件

SourceArn

SourceArn 限制條件會將許可限制為代表特定 AWS 資源提出的請求，並以其 Amazon Resource Name (ARN) 識別。SourceArn 授予限制正在有效地將aws:SourceArn全域條件索引鍵放入授予中，並且僅在服務提出請求時進行評估 AWS 。

當授予指定時，一律需要SourceArn限制條件GranteeServicePrincipal。它可以選擇性地與搭配使用GranteePrincipal。

與加密內容限制不同，所有 KMS 金鑰類型的授予都支援 SourceArn 限制。

若要在授予中指定SourceArn限制條件，請在 CreateGrant 操作中使用 Constraints 參數。下列範例會建立授予，允許 AWS 服務主體呼叫 Encrypt和 Decrypt操作，但僅限於代表指定的 DynamoDB 資料表提出請求時。當授予指定時，需要SourceArn限制條件GranteeServicePrincipal。


$ aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-service-principal service-name.amazonaws.com \
    --operations Encrypt Decrypt \
    --retiring-service-principal service-name.amazonaws.com \
    --constraints '{"SourceArn":"arn:aws:dynamodb:us-east-1:111122223333:table/ExampleTable"}'

產生的授予如下所示。只有在請求包含符合授予限制中的SourceArn值的來源 ARN 時，授予中的許可才有效。


$ aws kms list-grants --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "Grants": [
        {
            "Name": "",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a",
            "Operations": [
                "Encrypt",
                "Decrypt"
            ],
            "GranteeServicePrincipal": "service-name.amazonaws.com",
            "Constraints": {
                "SourceArn": "arn:aws:dynamodb:us-east-1:111122223333:table/ExampleTable"
            },
            "CreationDate": 1718567315.0,
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "RetiringServicePrincipal": "service-name.amazonaws.com"
        }
    ]
}

您也可以在單一授予中結合多個限制條件。不過，您可以指定 EncryptionContextEquals或 EncryptionContextSubset，但不能同時指定兩者。

指定 GranteeServicePrincipal 時，需要SourceArn限制條件，因此建立具有多個限制條件之授予的有效組合為：

EncryptionContextEquals 取代為 SourceArn
EncryptionContextSubset 取代為 SourceArn

下列範例會使用 GranteeServicePrincipal和建立授予RetiringServicePrincipal，並同時包含 EncryptionContextSubset 限制條件和 SourceArn限制條件。


$ aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-service-principal service-name.amazonaws.com \
    --retiring-service-principal service-name.amazonaws.com \
    --operations Encrypt Decrypt GenerateDataKey DescribeKey \
    --constraints '{"EncryptionContextSubset":{"Department":"IT"},"SourceArn":"arn:aws:dynamodb:us-east-1:111122223333:table/ExampleTable"}'

產生的授予如下所示。請注意，回應包含 GranteeServicePrincipal和 RetiringServicePrincipal 欄位，而 Constraints 欄位同時包含 EncryptionContextSubset和 SourceArn。


$ aws kms list-grants --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "Grants": [
        {
            "Name": "",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a",
            "Operations": [
                "Encrypt",
                "Decrypt",
                "GenerateDataKey",
                "DescribeKey"
            ],
            "GranteeServicePrincipal": "service-name.amazonaws.com",
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                },
                "SourceArn": "arn:aws:dynamodb:us-east-1:111122223333:table/ExampleTable"
            },
            "CreationDate": 1718567315.0,
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "RetiringServicePrincipal": "service-name.amazonaws.com"
        }
    ]
}

授與 CreateGrant 許可

授予可以包含呼叫 CreateGrant 操作的許可。但是，當承授者主體從授予 (而非政策) 取得呼叫 CreateGrant 的許可時，該許可會受到限制。

承授者主體只能建立允許父項授予中部分或全部操作的授予。
其所建立授予中的授予限制條件必須至少與父項授予一樣嚴格。

這些限制不適用於從政策取得 CreateGrant 許可的主體，雖然其許可可以受到政策條件限制。

例如，假設有一個授與允許承授者主體呼叫 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。

此外，子項授予中的授予限制條件必須與父項授予中的限制程度相等嚴格或比之更嚴格。例如，子授與可以新增對組到父授與的 EncryptionContextSubset 限制，但不能將其移除。子授與可將 EncryptionContextSubset 限制變更為 EncryptionContextEquals 限制，但不能反向。

IAM 最佳實務不建議使用具有長期憑證的 IAM 使用者。盡可能使用提供臨時憑證的 IAM 角色。如需詳細資訊，請參閱《IAM 使用者指南》中的 IAM 中的安全性最佳實務。

例如，承授者主體可以使用其從父項授予中取得的 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 建立的授予必須在其父項授予或子集中包含操作，並且授予限制條件必須相同或更嚴格。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

控制對授予的存取

檢視授予