Testing your permissions - Amazon Key Management Service
What is DryRun?Specifying DryRun with the API
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).

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 if DryRun 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