Testing your permissions
To use Amazon KMS, you must have credentials that Amazon can use to authenticate your API requests. The credentials must include the permission to access KMS keys and aliases. The permissions are determined by key policies, IAM policies, grants, and cross-account access controls. In addition to controlling access to KMS keys, you can control access to your CloudHSM, and to your custom key stores.
You can specify the DryRun
API parameter to verify that you have the
necessary permissions to use Amazon KMS
keys. You can also use DryRun
to verify that the request parameters
in a Amazon KMS API call are correctly specified.
What is the DryRun parameter?
DryRun
is an optional API parameter that you specify to verify that Amazon KMS
API calls will succeed. Use DryRun
to test your API call, before actually
making the call to Amazon KMS. You can verify the following.
-
That you have the necessary permissions to use Amazon KMS keys.
-
That you have specified the parameters in the call correctly.
Amazon KMS supports using the DryRun
parameter in certain API actions:
Using the DryRun
parameter will incur charges and will be billed as a
standard API request. For more information about Amazon KMS pricing, see Amazon Key Management Service Pricing
All API requests using the DryRun
parameter apply to the request quota
of the API and can result in a throttling exception if you exceed an API request quota.
For example, calling Decrypt with
DryRun
or without DryRun
counts against the same
cryptographic operations quota. See Throttling Amazon KMS requests to learn more.
Every call to an Amazon KMS API operation is captured as an event and recorded in an
Amazon CloudTrail log. The output of any operations that specify the DryRun
parameter appear in your CloudTrail log. For more information, see Logging Amazon KMS API calls with Amazon CloudTrail.
Specifying DryRun with the API
To use DryRun
, specify the —dry-run
parameter in Amazon CLI
commands and Amazon KMS API calls that support the parameter. When you do, Amazon KMS will verify
whether your call will succeed. Amazon KMS calls that use DryRun
will
always fail and return a message with information about reason why the call failed. The
message can include the following exceptions:
-
DryRunOperationException
‐ The request would succeed ifDryRun
wasn’t specified. -
ValidationException
‐ The request failed from specifying an incorrect API parameter. -
AccessDeniedException
‐ You do not have permissions to perform the specified API action on the KMS resource.
For example, the following command uses the CreateGrant operation and creates a
grant that allows users who are authorized to assume the keyUserRole
role
to call the Decrypt operation on a
specified symmetric KMS key. The
DryRun
parameter is specified.
$
aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --dry-run