Working with grants - AWS Key Management Service

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). For more details about using grants in AWS KMS, see Using grants.

Creating a grant

To create a grant for an AWS KMS customer master key, use the CreateGrant operation. The response includes only the grant ID and grant token. To get detailed information about the grant, use the ListGrants operation, as shown in Viewing a grant.

These examples create a grant that allows Alice, an IAM user in the account, to call the GenerateDataKey operation on the CMK identified by the KeyId parameter.

In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.

Java

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

// Create a grant // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN 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.GenerateDataKey.toString(); CreateGrantRequest request = new CreateGrantRequest() .withKeyId(keyId) .withGranteePrincipal(granteePrincipal) .withOperations(operation); CreateGrantResult result = kmsClient.createGrant(request);
C#

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

// Create a grant // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN 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.GenerateDataKey; CreateGrantRequest createGrantRequest = new CreateGrantRequest() { KeyId = keyId, GranteePrincipal = granteePrincipal, Operations = new List<string>() { operation } }; CreateGrantResponse createGrantResult = kmsClient.CreateGrant(createGrantRequest);
Python

For details, see the create_grant method in the AWS SDK for Python (Boto3).

# Create a grant # Replace the following fictitious CMK ARN with a valid CMK ID or ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee_principal = 'arn:aws:iam::111122223333:user/Alice' operation = ['GenerateDataKey'] response = kms_client.create_grant( KeyId=key_id, GranteePrincipal=grantee_principal, Operations=operation )
Ruby

For details, see the create_grant instance method in the AWS SDK for Ruby.

# Create a grant # Replace the following fictitious CMK ARN with a valid CMK ID or ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' granteePrincipal = 'arn:aws:iam::111122223333:user/Alice' operation = ['GenerateDataKey'] response = kmsClient.create_grant({ key_id: keyId, grantee_principal: granteePrincipal, operations: operation })
PHP

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

// Create a grant // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; $operation = ['GenerateDataKey'] $result = $KmsClient->createGrant([ 'GranteePrincipal' => $granteePrincipal, 'KeyId' => $keyId, 'Operations' => $operation ]);
Node.js

For details, see the createGrant property in the AWS SDK for JavaScript in Node.js.

// Create a grant // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const GranteePrincipal = 'arn:aws:iam::111122223333:user/Alice'; const Operations: ["GenerateDataKey"]; kmsClient.createGrant({ KeyId, GranteePrincipal, Operations }, (err, data) => { ... });
PowerShell

To create a grant, use the New-KMSGrant cmdlet.

# Create a grant # Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $granteePrincipal = 'arn:aws:iam::111122223333:user/Alice' $operation = 'GenerateDataKey' $response = New-KMSGrant -GranteePrincipal $granteePrincipal -KeyId $keyId -Operation $operation

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.

Viewing a grant

To get detailed information about the grants on an AWS KMS customer master key, use the ListGrants operation. These examples use the optional Limits parameter, which determines how many grants the operation returns.

Note

The GranteePrincipal field in the ListGrants response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the GranteePrincipal field contains the service principal, which might represent several different grantee principals.

In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.

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 CMK ARN with a valid CMK ID or ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; Integer limit = 10; ListGrantsRequest req = new ListGrantsRequest().withKeyId(keyId).withLimit(limit); ListGrantsResult result = kmsClient.listGrants(req);
C#

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

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

For details, see the list_grants method in the AWS SDK for Python (Boto3).

# Listing grants on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.list_grants( KeyId=key_id, Limit=10 )
Ruby

For details, see the list_grants instance method in the AWS SDK for Ruby.

# Listing grants on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.list_grants({ key_id: keyId, limit: 10 })
PHP

For details, see the ListGrants method in the AWS SDK for PHP.

// Listing grants on a CMK // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $limit = 10; $result = $KmsClient->listGrants([ 'KeyId' => $keyId, 'Limit' => $limit, ]);
Node.js

For details, see the listGrants property in the AWS SDK for JavaScript in Node.js.

// Listing grants on a CMK // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const Limit = 10; kmsClient.listGrants({ KeyId, Limit }, (err, data) => { ... });
PowerShell

To view the details of all AWS KMS grants for a CMK, use the Get-KMSGrantList cmdlet.

To limit the number of output objects, this example uses the Select-Object cmdlet, instead of the Limit parameter, which is being deprecated in list cmdlets. For help with paginating output in AWS Tools for PowerShell, see Output Pagination with AWS Tools for PowerShell.

# Listing grants on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $limit = 10 $response = Get-KMSGrantList -KeyId $keyId | Select-Object -First $limit

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.

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.

To retire a grant, provide the grant token, or both the grant ID and CMK ID. For this operation, the CMK ID must be Amazon Resource Name (ARN) of the CMK. The grant token is returned by the CreateGrant operation. The grant ID is returned by the CreateGrant and ListGrants operations.

RetireGrant doesn't return a response. To verify that it was effective, use the ListGrants operation.

In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.

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 RetireGrant 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);
Python

For details, see the retire_grant method in the AWS SDK for Python (Boto3).

# Retire a grant grant_token = Place your grant token here response = kms_client.retire_grant( GrantToken=grant_token )
Ruby

For details, see the retire_grant instance method in the AWS SDK for Ruby.

# Retire a grant grantToken = Place your grant token here response = kmsClient.retire_grant({ grant_token: grantToken })
PHP

For details, see the RetireGrant method in the AWS SDK for PHP.

// Retire a grant // $grantToken = 'Place your grant token here'; $result = $KmsClient->retireGrant([ 'GrantToken' => $grantToken, ]);
Node.js

For details, see the retireGrant property in the AWS SDK for JavaScript in Node.js.

// Retire a grant // const GrantToken = 'Place your grant token here'; kmsClient.retireGrant({ GrantToken }, (err, data) => { ... });
PowerShell

To retire a grant, use the Disable-KMSGrant cmdlet. To get the grant token, use the New-KMSGrant cmdlet. The GrantToken parameter takes a string, so you don't need to convert output that the Read-Host cmdlet returns.

# Retire a grant $grantToken = Read-Host -Message Place your grant token here Disable-KMSGrant -GrantToken $grantToken

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.

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.

In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.

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 CMK ARN with a valid CMK ID or ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // &fake-grant-id; String grantId = "grant1"; RevokeGrantRequest req = new RevokeGrantRequest().withKeyId(keyId).withGrantId(grantId); kmsClient.revokeGrant(req);
C#

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

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

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.

Python

For details, see the revoke_grant method in the AWS SDK for Python (Boto3).

# Revoke a grant on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # &fake-grant-id; grant_id = 'grant1' response = kms_client.revoke_grant( KeyId=key_id, GrantId=grant_id )
Ruby

For details, see the revoke_grant instance method in the AWS SDK for Ruby.

# Revoke a grant on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # &fake-grant-id; grantId = 'grant1' response = kmsClient.revoke_grant({ key_id: keyId, grant_id: grantId })
PHP

For details, see the RevokeGrant method in the AWS SDK for PHP.

// Revoke a grant on a CMK // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following fictitious grant ID with a valid one $grantId = "grant1"; $result = $KmsClient->revokeGrant([ 'KeyId' => $keyId, 'GrantId' => $grantId, ]);
Node.js

For details, see the revokeGrant property in the AWS SDK for JavaScript in Node.js.

// Revoke a grant on a CMK // // Replace the following fictitious CMK ARN with a valid CMK ID or ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following fictitious grant ID with a valid one const GrantId = 'grant1'; kmsClient.revokeGrant({ GrantId, KeyId }, (err, data) => { ... });
PowerShell

To revoke a grant, use the Revoke-KMSGrant cmdlet.

# Revoke a grant on a CMK # Replace the following fictitious CMK ARN with a valid CMK ID or ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # Replace the following fictitious grant ID with a valid one $grantId = 'grant1' Revoke-KMSGrant -KeyId $keyId -GrantId $grantId

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.