Use CreateGrant
with an AWS SDK or CLI
The following code examples show how to use CreateGrant
.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
- .NET
-
- AWS SDK for .NET
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. public static async Task Main() { var client = new AmazonKeyManagementServiceClient(); // The identity that is given permission to perform the operations // specified in the grant. var grantee = "arn:aws:iam::111122223333:role/ExampleRole"; // The identifier of the AWS KMS key to which the grant applies. You // can use the key ID or the Amazon Resource Name (ARN) of the KMS key. var keyId = "7c9eccc2-38cb-4c4f-9db3-766ee8dd3ad4"; var request = new CreateGrantRequest { GranteePrincipal = grantee, KeyId = keyId, // A list of operations that the grant allows. Operations = new List<string> { "Encrypt", "Decrypt", }, }; var response = await client.CreateGrantAsync(request); string grantId = response.GrantId; // The unique identifier of the grant. string grantToken = response.GrantToken; // The grant token. Console.WriteLine($"Id: {grantId}, Token: {grantToken}"); } }
-
For API details, see CreateGrant in AWS SDK for .NET API Reference.
-
- CLI
-
- AWS CLI
-
To create a grant
The following
create-grant
example creates a grant that allows theexampleUser
user to use thedecrypt
command on the1234abcd-12ab-34cd-56ef-1234567890ab
example KMS key. The retiring principal is theadminRole
role. The grant uses theEncryptionContextSubset
grant constraint to allow this permission only when the encryption context in thedecrypt
request includes the"Department": "IT"
key-value pair.aws kms create-grant \ --key-id
1234abcd-12ab-34cd-56ef-1234567890ab
\ --grantee-principalarn:aws:iam::123456789012:user/exampleUser
\ --operationsDecrypt
\ --constraintsEncryptionContextSubset={Department=IT}
\ --retiring-principalarn:aws:iam::123456789012:role/adminRole
Output:
{ "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2", "GrantToken": "<grant token here>" }
To view detailed information about the grant, use the
list-grants
command.For more information, see Grants in AWS KMS in the AWS Key Management Service Developer Guide.
-
For API details, see CreateGrant
in AWS CLI Command Reference.
-
- Java
-
- SDK for Java 2.x
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. /** * Grants permissions to a specified principal on a customer master key (CMK) asynchronously. * * @param keyId The unique identifier for the customer master key (CMK) that the grant applies to. * @param granteePrincipal The principal that is given permission to perform the operations that the grant permits on the CMK. * @return A {@link CompletableFuture} that, when completed, contains the ID of the created grant. * @throws RuntimeException If an error occurs during the grant creation process. */ public CompletableFuture<String> grantKeyAsync(String keyId, String granteePrincipal) { List<GrantOperation> grantPermissions = List.of( GrantOperation.ENCRYPT, GrantOperation.DECRYPT, GrantOperation.DESCRIBE_KEY ); CreateGrantRequest grantRequest = CreateGrantRequest.builder() .keyId(keyId) .name("grant1") .granteePrincipal(granteePrincipal) .operations(grantPermissions) .build(); CompletableFuture<CreateGrantResponse> responseFuture = getAsyncClient().createGrant(grantRequest); responseFuture.whenComplete((response, ex) -> { if (ex == null) { logger.info("Grant created successfully with ID: " + response.grantId()); } else { if (ex instanceof KmsException kmsEx) { throw new RuntimeException("Failed to create grant: " + kmsEx.getMessage(), kmsEx); } else { throw new RuntimeException("An unexpected error occurred: " + ex.getMessage(), ex); } } }); return responseFuture.thenApply(CreateGrantResponse::grantId); }
-
For API details, see CreateGrant in AWS SDK for Java 2.x API Reference.
-
- Kotlin
-
- SDK for Kotlin
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. suspend fun createNewGrant( keyIdVal: String?, granteePrincipalVal: String?, operation: String, ): String? { val operationOb = GrantOperation.fromValue(operation) val grantOperationList = ArrayList<GrantOperation>() grantOperationList.add(operationOb) val request = CreateGrantRequest { keyId = keyIdVal granteePrincipal = granteePrincipalVal operations = grantOperationList } KmsClient { region = "us-west-2" }.use { kmsClient -> val response = kmsClient.createGrant(request) return response.grantId } }
-
For API details, see CreateGrant
in AWS SDK for Kotlin API reference.
-
- PHP
-
- SDK for PHP
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. /*** * @param string $keyId * @param string $granteePrincipal * @param array $operations * @param array $grantTokens * @return Result */ public function createGrant(string $keyId, string $granteePrincipal, array $operations, array $grantTokens = []) { $args = [ 'KeyId' => $keyId, 'GranteePrincipal' => $granteePrincipal, 'Operations' => $operations, ]; if($grantTokens){ $args['GrantTokens'] = $grantTokens; } try{ return $this->client->createGrant($args); }catch(KmsException $caught){ if($caught->getAwsErrorMessage() == "InvalidGrantTokenException"){ echo "The request was rejected because the specified grant token is not valid.\n"; } throw $caught; } }
-
For API details, see CreateGrant in AWS SDK for PHP API Reference.
-
- Python
-
- SDK for Python (Boto3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. class GrantManager: def __init__(self, kms_client): self.kms_client = kms_client @classmethod def from_client(cls) -> "GrantManager": """ Creates a GrantManager instance with a default KMS client. :return: An instance of GrantManager initialized with the default KMS client. """ kms_client = boto3.client("kms") return cls(kms_client) def create_grant( self, key_id: str, principal: str, operations: [str] ) -> dict[str, str]: """ Creates a grant for a key that lets a principal generate a symmetric data encryption key. :param key_id: The ARN or ID of the key. :param principal: The principal to grant permission to. :param operations: The operations to grant permission for. :return: The grant that is created. """ try: return self.kms_client.create_grant( KeyId=key_id, GranteePrincipal=principal, Operations=operations, ) except ClientError as err: logger.error( "Couldn't create a grant on key %s. Here's why: %s", key_id, err.response["Error"]["Message"], ) raise
-
For API details, see CreateGrant in AWS SDK for Python (Boto3) API Reference.
-
For a complete list of AWS SDK developer guides and code examples, see Using this service with an AWS SDK. This topic also includes information about getting started and details about previous SDK versions.