Working with grants using the Amazon KMS API and the Amazon SDK for PHP version 3
A grant is another mechanism for providing permissions. It is an alternative to the key policy. You can use grants to give long-term access that allows Amazon principals to use your Amazon Key Management Service (Amazon KMS) customer-managed Amazon KMS keys. For more information, see Grants in Amazon KMS in the Amazon Key Management Service Developer Guide.
The following examples show how to:
-
Create a grant for a KMS key using CreateGrant.
-
View a grant for a KMS key using ListGrants.
-
Retire a grant for a KMS key using RetireGrant.
-
Revoke a grant for a KMS key using RevokeGrant.
All the example code for the Amazon SDK for PHP is available here on
GitHub
Credentials
Before running the example code, configure your Amazon credentials, as described in Credentials. Then import the Amazon SDK for PHP, as described in Basic usage.
For more information about using Amazon Key Management Service (Amazon KMS), see the Amazon KMS Developer Guide.
Create a grant
To create a grant for an Amazon KMS key, use the CreateGrant operation.
Imports
require 'vendor/autoload.php'; 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 Amazon KMS key, use the ListGrants operation.
Imports
require 'vendor/autoload.php'; 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 Amazon KMS key, use the RetireGrant operation. Retire a grant to clean up after you finish using it.
Imports
require 'vendor/autoload.php'; 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 Amazon KMS key, use the RevokeGrant operation. You can revoke a grant to explicitly deny operations that depend on it.
Imports
require 'vendor/autoload.php'; 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"; }