Working with grants - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with grants

The examples in this topic use the Amazon KMS API to create, view, retire, and revoke grants on Amazon KMS keys. For more details about using grants in Amazon KMS, see Grants in Amazon KMS.

Creating a grant

To create a grant for an Amazon KMS 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 users who can assume the ExampleKeyUser role to call the GenerateDataKey operation on the KMS key identified by the KeyId parameter.

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

Java

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

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:role/ExampleKeyUser"; 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 Amazon SDK for .NET.

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String granteePrincipal = "arn:aws:iam::111122223333:role/ExampleKeyUser"; 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 Amazon SDK for Python (Boto3).

# Create a grant # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee_principal = 'arn:aws:iam::111122223333:role/ExampleKeyUser' 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 Amazon SDK for Ruby.

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

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

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

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

// Create a grant // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const GranteePrincipal = 'arn:aws:iam::111122223333:role/ExampleKeyUser'; 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 example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $granteePrincipal = 'arn:aws:iam::111122223333:role/ExampleKeyUser' $operation = 'GenerateDataKey' $response = New-KMSGrant -GranteePrincipal $granteePrincipal -KeyId $keyId -Operation $operation

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

Viewing a grant

To get detailed information about the grants on a KMS key, use the ListGrants operation.

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 Amazon 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 Amazon KMS client object that you created in Creating a client.

These examples use the optional Limits parameter, which determines how many grants the operation returns.

Java

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

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key 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 Amazon SDK for .NET.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key 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 Amazon SDK for Python (Boto3).

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key 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 Amazon SDK for Ruby.

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

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

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key 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 Amazon SDK for JavaScript in Node.js.

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key 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 Amazon KMS grants for a KMS key, 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 Amazon Tools for PowerShell, see Output Pagination with Amazon Tools for PowerShell.

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key 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 Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

You must specify the KMS key in every ListGrants operations. However, you can further filter the grant list by specifying the grant ID or a grantee principal. The following examples get only the grants for a KMS key where the test-engineer role is the grantee principal.

Java

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

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantee = "arn:aws:iam::111122223333:role/test-engineer"; ListGrantsRequest req = new ListGrantsRequest().withKeyId(keyId).withGranteePrincipal(grantee); ListGrantsResult result = kmsClient.listGrants(req);
C#

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

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; String grantee = "arn:aws:iam::111122223333:role/test-engineer"; ListGrantsRequest listGrantsRequest = new ListGrantsRequest() { KeyId = keyId, GranteePrincipal = grantee }; ListGrantsResponse listGrantsResponse = kmsClient.ListGrants(listGrantsRequest);
Python

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

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee = 'arn:aws:iam::111122223333:role/test-engineer' response = kms_client.list_grants( KeyId=key_id, GranteePrincipal=grantee )
Ruby

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

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' grantee = 'arn:aws:iam::111122223333:role/test-engineer' response = kmsClient.list_grants({ key_id: keyId, grantee_principal: grantee })
PHP

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

// Listing grants on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $grantee = 'arn:aws:iam::111122223333:role/test-engineer'; $result = $KmsClient->listGrants([ 'KeyId' => $keyId, 'GranteePrincipal' => $grantee, ]);
Node.js

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

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

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

# Listing grants on a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $grantee = 'arn:aws:iam::111122223333:role/test-engineer' $response = Get-KMSGrantList -KeyId $keyId -GranteePrincipal $grantee

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

Retiring a grant

To retire a grant for a KMS 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 KMS key ID. For this operation, the KMS key ID must be Amazon Resource Name (ARN) of the KMS key. 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 Amazon KMS client object that you created in Creating a client.

Java

For details, see the retireGrant method in the Amazon 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 Amazon 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 Amazon 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 Amazon SDK for Ruby.

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

For details, see the RetireGrant method in the Amazon 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 Amazon 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 Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Revoking a grant

To revoke a grant to a KMS 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 Amazon KMS client object that you created in Creating a client.

Java

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

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

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

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

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

Python

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

# Revoke a grant on a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # Replace the following example grant ID with a valid one 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 Amazon SDK for Ruby.

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

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

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following example 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 Amazon SDK for JavaScript in Node.js.

// Revoke a grant on a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; // Replace the following example 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 KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' # Replace the following example grant ID with a valid one $grantId = 'grant1' Revoke-KMSGrant -KeyId $keyId -GrantId $grantId

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