Testing your AWS KMS API calls

To use AWS KMS, you must have credentials that AWS 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 AWS KMS keys. You can also use DryRun to verify that the request parameters in a AWS KMS API call are correctly specified.

What is the DryRun parameter?

DryRun is an optional API parameter that you specify to verify that AWS KMS API calls will succeed. Use DryRun to test your API call, before actually making the call to AWS KMS. You can verify the following.

• That you have the necessary permissions to use AWS KMS keys.

• That you have specified the parameters in the call correctly.

AWS KMS supports using the DryRun parameter in certain API actions:

• CreateGrant

• Decrypt

• DeriveSharedSecret

• Encrypt

• GenerateDataKey

• GenerateDataKeyPair

• GenerateDataKeyPairWithoutPlaintext

• GenerateDataKeyWithoutPlaintext

• GenerateMac

• ReEncrypt

• RetireGrant

• RevokeGrant

• Sign

• Verify

• VerifyMac

Using the DryRun parameter will incur charges and will be billed as a standard API request. For more information about AWS KMS pricing, see AWS 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 AWS KMS requests to learn more.

Every call to an AWS KMS API operation is captured as an event and recorded in an AWS CloudTrail log. The output of any operations that specify the DryRun parameter appear in your CloudTrail log. For more information, see Logging AWS KMS API calls with AWS CloudTrail.

Specifying DryRun with the API

To use DryRun, specify the —dry-run parameter in AWS CLI commands and AWS KMS API calls that support the parameter. When you do, AWS KMS will verify whether your call will succeed. AWS 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