Working with Grants Using the AWS KMS API and the AWS SDK for PHP Version 3
A grant is another mechanism for providing permissions, an alternative to the key policy. You can use grants to give long-term access that allows AWS principals to use your AWS Key Management Service (AWS KMS) customer-managed CMKs. For more information, see Using Grants.
The following examples show how to:
-
Create a grant for a customer master key (CMK) using CreateGrant.
-
View a grant for a CMK using ListGrants.
-
Retire a grant for a CMK using RetireGrant.
-
Revoke a grant for a CMK using RevokeGrant.
All the example code for the AWS SDK for PHP Version 3 is available here on GitHub
Credentials
Before running the example code, configure your AWS credentials, as described in Credentials for the AWS SDK for PHP Version 3. Then import the AWS SDK for PHP, as described in Basic Usage Patterns of the AWS SDK for PHP Version 3.
For more information about using AWS Key Management Service (AWS KMS), see the AWS KMS Developer Guide.
Create a Grant
To create a grant for an AWS KMS CMK, use the CreateGrant operation.
Imports
require 'vendor/autoload.php'; use Aws\Kms\KmsClient; use Aws\Exception\AwsException;
Sample Code
$KmsClient = new Aws\Kms\KmsClient([ 'profile' => 'default', 'version' => '2014-11-01', 'region' => 'us-east-2' ]); $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $granteePrincipal = "arn:aws:iam::111122223333:user/Alice"; $operation = ['Encrypt', 'Decrypt']; // A list of operations that the grant allows. try { $result = $KmsClient->createGrant([ 'GranteePrincipal' => $granteePrincipal, 'KeyId' => $keyId, 'Operations' => $operation ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }
View a Grant
To get detailed information about the grants on an AWS KMS CMK, use the ListGrants operation.
Imports
require 'vendor/autoload.php'; use Aws\Kms\KmsClient; use Aws\Exception\AwsException;
Sample Code
$KmsClient = new Aws\Kms\KmsClient([ 'profile' => 'default', 'version' => '2014-11-01', 'region' => 'us-east-2' ]); $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $limit = 10; try { $result = $KmsClient->listGrants([ 'KeyId' => $keyId, 'Limit' => $limit, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }
Retire a Grant
To retire a grant for an AWS KMS CMK, use the RetireGrant operation. Retire a grant to clean up after you finish using it.
Imports
require 'vendor/autoload.php'; use Aws\Kms\KmsClient; use Aws\Exception\AwsException;
Sample Code
$KmsClient = new Aws\Kms\KmsClient([ 'profile' => 'default', 'version' => '2014-11-01', 'region' => 'us-east-2' ]); $grantToken = 'Place your grant token here'; try { $result = $KmsClient->retireGrant([ 'GrantToken' => $grantToken, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; } //Can also identify grant to retire by a combination of the grant ID and the Amazon Resource Name (ARN) of the customer master key (CMK) $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $grantId = 'Unique identifier of the grant returned during CreateGrant operation' try { $result = $KmsClient->retireGrant([ 'GrantId' => $grantToken, 'KeyId' => $keyId, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }
Revoke a Grant
To revoke a grant to an AWS KMS CMK, use the RevokeGrant operation. You can revoke a grant to explicitly deny operations that depend on it.
Imports
require 'vendor/autoload.php'; use Aws\Kms\KmsClient; use Aws\Exception\AwsException;
Sample Code
$KmsClient = new Aws\Kms\KmsClient([ 'profile' => 'default', 'version' => '2014-11-01', 'region' => 'us-east-2' ]); $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $grantId = "grant1"; try { $result = $KmsClient->revokeGrant([ 'KeyId' => $keyId, 'GrantId' => $grantId, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }