CreateGrant
Creates a grant for a KMS key. A grant is a policy instrument that allows AWS principals to use KMS keys in cryptographic operations.
Description
A grant gives AWS principals long-term permissions to use KMS keys in cryptographic operations. You can create a grant to allow a principal to use the KMS key in specified operations. You can also use a grant to allow the principal to delegate their grant permissions to other principals.
Request Syntax
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Type | Must be "application/x-amz-json-1.1" | Yes | string |
| X-Amz-Target | Must be "TrentService.CreateGrant" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The unique identifier for the KMS key that the grant applies to. | Yes | text |
| GranteePrincipal | The principal that is given permission to perform the operations that the grant permits. | Yes | text |
| Operations | A list of operations that the grant permits (as JSON array). | Yes | text |
| RetiringPrincipal | The principal that is given permission to retire the grant by using RetireGrant operation. | No | text |
| Constraints | A structure that you can use to allow the operations permitted by the grant only when the grant request includes particular encryption context keys or values (as JSON object). | No | text |
| Name | A friendly name for identifying the grant. Use the same name to refer to the same grant in subsequent requests. | No | text |
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.CreateGrant
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"Operations": [
"Decrypt",
"Encrypt"
],
"Name": "ExampleGrant"
}
Values in italics indicate user input and should be replaced with actual values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| GrantId | The unique identifier for the grant. | No | String |
| GrantToken | The grant token. Use this value to establish the scope of the grant during its early phase, before the grant is replicated to all Q-KMS hosts. | No | String |
Examples
Example 1: Create a grant for encryption and decryption
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.CreateGrant
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"Operations": [
"Decrypt",
"Encrypt"
],
"Name": "ExampleGrant"
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60",
"GrantToken": "AQpAM2RhZTk1MGMyNTk2ZmCjsrRInph6PxKRieR4..."
}
Values in italics indicate variable response values.
Example 2: Create a grant with encryption context constraints
Special Errors
| Error Code | Description |
|---|---|
| DependencyTimeoutException | The system timed out while trying to fulfill the request. |
| DisabledException | The request was rejected because the specified KMS key is disabled. |
| InvalidArnException | The request was rejected because a specified ARN was not valid. |
| InvalidGrantTokenException | The request was rejected because the specified grant token is not valid. |
| KeyUnavailableException | The request was rejected because the specified KMS key was not available. |
| KMSInternalException | The request was rejected because an internal error occurred. |
| KMSInvalidStateException | The request was rejected because the state of the specified resource is not valid for this request. |
| LimitExceededException | The request was rejected because a quota was exceeded. |
| NotFoundException | The request was rejected because the specified entity or resource could not be found. |
Permissions
To use the `CreateGrant` operation, you must have the following permissions:
- `kms:CreateGrant` on the KMS key
Try It Out
Test CreateGrant
Create a grant for a KMS key to allow specific cryptographic operations.
Coming Soon
This feature is currently under development and will be available soon.