Menu
AWS Key Management Service
Developer Guide

Working with Grants

The examples in this topic use the AWS KMS API to create, view, retire, and revoke grants on AWS KMS customer master keys (CMKs).

Creating a Grant

To create a grant for an AWS KMS customer master key, use the CreateGrant operation.

This example uses the kmsClient client object that you created in Creating a Client.

JavaC#
Java

For details, see the createGrant method in the AWS SDK for Java API Reference.

// Create a grant // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; String operation = GrantOperation.Encrypt; CreateGrantRequest req = new CreateGrantRequest(); req.setKeyId(keyId); req.setGranteePrincipal(granteePrincipal); req.setOperation(operation); CreateGrantResult result = kmsClient.createGrant(req);
C#

For details, see the CreateGrant method in the AWS SDK for .NET.

// Create a grant // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; String operation = GrantOperation.Encrypt; CreateGrantRequest createGrantRequest = new CreateGrantRequest() { KeyId = keyId, GranteePrincipal = granteePrincipal, Operations = new List<string>() { operation } }; CreateGrantResponse createGrantResult = kmsClient.CreateGrant(createGrantRequest);

Viewing a Grant

To get detailed information about the grants on an AWS KMS customer master key, use the ListGrants operation.

This example uses the kmsClient client object that you created in Creating a Client.

JavaC#
Java

For details about the Java implementation, see the listGrants method in the AWS SDK for Java API Reference.

// Listing grants on a CMK // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; Integer limit = 10; String marker = null; ListGrantsRequest req = new ListGrantsRequest().withKeyId(keyId).withMarker(marker).withLimit(limit); ListGrantsResult result = kmsClient.listGrants(req);
C#

For details, see the EnableKey method in the AWS SDK for .NET.

// Listing grants on a CMK // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; int limit = 10; String marker = null; ListGrantsRequest listGrantsRequest = new ListGrantsRequest() { KeyId = keyId, Limit = limit, Marker = marker }; ListGrantsResponse listGrantsResponse = kmsClient.ListGrants(listGrantsRequest);

Retiring a Grant

To retire a grant for an AWS KMS customer master key, use the RetireGrant operation. You should retire a grant to clean up after you are done using it.

This example uses the kmsClient client object that you created in Creating a Client.

JavaC#
Java

For details, see the retireGrant method in the AWS SDK for Java API Reference.

// Retire a grant // String grantToken = Place your grant token here; RetireGrantRequest req = new RetireGrantRequest().withGrantToken(grantToken); kmsClient.retireGrant(req);
C#

For details, see the EnableKey method in the AWS SDK for .NET.

// Retire a grant // String grantToken = "Place your grant token here"; RetireGrantRequest retireGrantRequest = new RetireGrantRequest() { GrantToken = grantToken }; kmsClient.RetireGrant(retireGrantRequest);

Revoking a Grant

To revoke a grant to an AWS KMS customer master key, use the RevokeGrant operation. You can revoke a grant to explicitly deny operations that depend on it.

This example uses the kmsClient client object that you created in Creating a Client.

JavaC#
Java

For details, see the revokeGrant method in the AWS SDK for Java API Reference.

// Revoke a grant on a CMK // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantId = "grant1"; RevokeGrantRequest req = new RevokeGrantRequest().withKeyId(keyId).withGrantId(grantId); kmsClient.revokeGrant(req);
C#

For details, see the EnableKey method in the AWS SDK for .NET.

// Revoke a grant on a CMK // // Replace the following fictitious key ARN with a valid key ID String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantId = "grant1"; RevokeGrantRequest revokeGrantRequest = new RevokeGrantRequest() { KeyId = keyId, GrantId = grantId }; kmsClient.RevokeGrant(revokeGrantRequest);