The Wayback Machine - https://web.archive.org/web/20211021025004/https://docs.aws.amazon.com/kms/latest/developerguide/programming-grants.html
Working with grants - AWS Key Management Service
Creating a grantViewing a grantRetiring a grantRevoking a grant

Working with grants

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

Creating a grant

To create a grant for an AWS 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 Alice, an IAM user in the account, 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 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 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: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 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: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 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: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 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:user/Alice'
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 AWS 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: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 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: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 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: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 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 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.

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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS Tools for PowerShell, see Output Pagination with AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 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 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 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

grant_token = Place your grant token here

response = kmsClient.retire_grant({
  grant_token: grant_token
})
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 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 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 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";

// &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 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";

// &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 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'

# &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 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'

# &fake-grant-id;
grant_id = 'grant1'

response = kmsClient.revoke_grant({
  key_id: key_id,
  grant_id: grant_id
})
PHP

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