AWS kms documentation change
Summary
Added documentation for SourceArn grant constraint and clarified requirements when using grantee service principals. Restructured grant constraints section to separate encryption context constraints from the new SourceArn constraint.
Security assessment
The changes introduce documentation for the SourceArn constraint, which enhances security by restricting grant permissions to specific AWS resources. This adds a new security control mechanism but doesn't address a specific vulnerability. The updates clarify security requirements for service principals but show no evidence of fixing an existing security issue.
Diff
diff --git a/kms/latest/developerguide/create-grant-overview.md b/kms/latest/developerguide/create-grant-overview.md index 12a8fa7d5..5f5fec2f0 100644 --- a//kms/latest/developerguide/create-grant-overview.md +++ b//kms/latest/developerguide/create-grant-overview.md @@ -24 +24,3 @@ Before creating a grant, learn about the options for customizing your grant. You -To create a grant, call the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. Specify a KMS key, a [grantee principal](./grants.html#terms-grantee-principal), and a list of allowed [grant operations](./grants.html#terms-grant-operations). You can also designate an optional [retiring principal](./grants.html#terms-retiring-principal). To customize the grant, use optional `Constraints` parameters to define [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html). +To create a grant, call the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. Specify a KMS key, a list of allowed [grant operations](./grants.html#terms-grant-operations), and either a [grantee principal](./grants.html#terms-grantee-principal) or a [grantee service principal](./grants.html#terms-grantee-service-principal). + +When you specify a **grantee principal** , you can optionally designate a [retiring principal](./grants.html#terms-retiring-principal) or [retiring service principal](./grants.html#terms-retiring-service-principal), and use the `Constraints` parameter to define [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html). When you specify a **grantee service principal** , you must include a SourceArn grant constraint. You must also specify either a `RetiringServicePrincipal` or a `RetiringPrincipal`. @@ -57 +59 @@ For code examples that demonstrate how to create grants in several programming l -[Grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) set conditions on the permissions that the grant gives to the grantee principal. Grant constraints take the place of [condition keys](./policy-conditions.html) in a [key policy](./key-policies.html) or [IAM policy](./iam-policies.html). Each grant constraint value can include up to 8 encryption context pairs. The encryption context value in each grant constraint cannot exceed 384 characters. +[Grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) set conditions on the permissions that the grant gives to the grantee principal. Grant constraints take the place of [condition keys](./policy-conditions.html) in a [key policy](./key-policies.html) or [IAM policy](./iam-policies.html). @@ -63 +65,3 @@ Do not include confidential or sensitive information in this field. This field m -AWS KMS supports two grant constraints, `EncryptionContextEquals` and `EncryptionContextSubset`, both of which establish requirements for the [encryption context](./encrypt_context.html) in a request for a cryptographic operation. +AWS KMS supports two types of grant constraints: encryption context constraints and the `SourceArn` constraint. + +#### Encryption context constraints @@ -65 +69 @@ AWS KMS supports two grant constraints, `EncryptionContextEquals` and `Encryptio -The encryption context grant constraints are designed to be used with [grant operations](./grants.html#terms-grant-operations) that have an encryption context parameter. +Encryption context constraints establish requirements for the [encryption context](./encrypt_context.html) in a request for a cryptographic operation. Each encryption context grant constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters. @@ -76 +80 @@ The encryption context grant constraints are designed to be used with [grant ope -AWS KMS supports the following encryption context grant constraints. +AWS KMS supports two encryption context grant constraints. @@ -201,0 +206,99 @@ To get this output, run the [ListGrants](https://docs.aws.amazon.com/kms/latest/ +#### SourceArn constraint + +**SourceArn** + + +The `SourceArn` constraint restricts grant permissions to requests made on behalf of a specific AWS resource, identified by its Amazon Resource Name (ARN). The `SourceArn` grant constraint is effectively putting an [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) global condition key into the grant and is only evaluated when the request is made by an AWS service. + +The `SourceArn` constraint is always required when the grant specifies a `GranteeServicePrincipal`. It can optionally be used with `GranteePrincipal`. + +Unlike encryption context constraints, the `SourceArn` constraint is supported on grants for _all types_ of KMS keys. + +To specify a `SourceArn` constraint in a grant, use the `Constraints` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. The following example creates a grant that allows an AWS service principal to call the `Encrypt` and `Decrypt` operations, but only when the request is made on behalf of the specified DynamoDB table. The `SourceArn` constraint is required when the grant specifies a `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"}'** + + +The resulting grant looks like the following. The permissions in the grant are effective only when the request includes a source ARN that matches the `SourceArn` value in the grant constraint. + + + $ 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" + } + ] + } + +You can also combine multiple constraints in a single grant. However, you can specify either `EncryptionContextEquals` or `EncryptionContextSubset`, but not both. + +When `GranteeServicePrincipal` is specified, the `SourceArn` constraint is required, so the valid combinations to create grant with multiple constraints are: + + * `EncryptionContextEquals` with `SourceArn` + + * `EncryptionContextSubset` with `SourceArn` + + + + +The following example creates a grant with `GranteeServicePrincipal` and `RetiringServicePrincipal`, and includes both an `EncryptionContextSubset` constraint and a `SourceArn` constraint. + + + $ 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"}'** + + +The resulting grant looks like the following. Notice that the response includes `GranteeServicePrincipal` and `RetiringServicePrincipal` fields, and the `Constraints` field contains both `EncryptionContextSubset` and `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"** + } + ] + } +