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.
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.