Menu
Amazon Web Services
General Reference (Version 1.0)

Troubleshooting AWS Signature Version 4 Errors

When you develop code that implements Signature Version 4, you might receive errors from AWS products that you test against. The errors typically come from an error in the canonicalization of the request, the incorrect derivation or use of the signing key, or a validation failure of signature-specific parameters sent along with the request.

Troubleshooting AWS Signature Version 4 Canonicalization Errors

Consider the following request:

https://iam.amazonaws.com/?MaxItems=100 &Action=ListGroupsForUser &UserName=Test &Version=2010-05-08 &X-Amz-Date=20120223T063000Z &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIAIOSFODNN7EXAMPLE/20120223/us-east-1/iam/aws4_request &X-Amz-SignedHeaders=host &X-Amz-Signature=<calculated value>

If you incorrectly calculate the canonical request or the string to sign, the signature verification step performed by the service fails. The following example is a typical error response, which includes the canonical string and the string to sign as computed by the service. You can troubleshoot your calculation error by comparing the returned strings with the canonical string and your calculated string to sign.

<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> <Error> <Type>Sender</Type> <Code>SignatureDoesNotMatch</Code> <Message>The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details. The canonical string for this request should have been 'GET / Action=ListGroupsForUser&MaxItems=100&UserName=Test&Version=2010-05-08&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential =AKIAIOSFODNN7EXAMPLE%2F20120223%2Fus-east-1%2Fiam%2Faws4_request&X-Amz-Date=20120223T063000Z&X-Amz-SignedHeaders=host host:iam.amazonaws.com host <hashed-value>' The String-to-Sign should have been 'AWS4-HMAC-SHA256 20120223T063000Z 20120223/us-east-1/iam/aws4_request <hashed-value>' </Message> </Error> <RequestId>4ced6e96-5de8-11e1-aa78-a56908bdf8eb</RequestId> </ErrorResponse>

For testing with an SDK, we recommend troubleshooting by verifying each derivation step against known values. For more information, see Signature Version 4 Test Suite.

Troubleshooting AWS Signature Version 4 Credential Scope Errors

AWS products validate credentials for proper scope; the credential parameter must specify the correct service, region, and date. For example, the following credential references the Amazon RDS service:

Credential=AKIAIOSFODNN7EXAMPLE/20120224/us-east-1/rds/aws4_request

If you use the same credentials to submit a request to IAM, you'll receive the following error response:

<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> <Error> <Type>Sender</Type> <Code>SignatureDoesNotMatch</Code> <Message>Credential should be scoped to correct service: 'iam'. </Message> </Error> <RequestId>aa0da9de-5f2b-11e1-a2c0-c1dc98b6c575</RequestId>

The credential must also specify the correct region. For example, the following credential for an IAM request incorrectly specifies the US West (N. California) region.

Credential=AKIAIOSFODNN7EXAMPLE/20120224/us-west-1/iam/aws4_request

If you use the credential to submit a request to IAM, which accepts only the us-east-1 region specification, you'll receive the following response:

<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> <Error> <Type>Sender</Type> <Code>SignatureDoesNotMatch</Code> <Message>Credential should be scoped to a valid region, not 'us-east-1'. </Message> </Error> <RequestId>8e229682-5f27-11e1-88f2-4b1b00f424ae</RequestId> </ErrorResponse>

You'll receive the same type of invalid region response from AWS products that are available in multiple regions if you submit requests to a region that differs from the region specified in your credential scope.

The credential must also specify the correct region for the service and action in your request.

The date that you use as part of the credential must match the date value in the x-amz-date header. For example, the following x-amz-date header value does not match the date value used in the Credential parameter that follows it.

x-amz-date:"20120224T213559Z" Credential=AKIAIOSFODNN7EXAMPLE/20120225/us-east-1/iam/aws4_request

If you use this pairing of x-amz-date header and credential, you'll receive the following error response:

<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> <Error> <Type>Sender</Type> <Code>SignatureDoesNotMatch</Code> <Message>Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP: '20120225' != '20120224', from '20120 224T213559Z'.</Message> </Error> <RequestId>9d6ddd2b-5f2f-11e1-b901-a702cd369eb8</RequestId> </ErrorResponse>

An expired signature can also generate an error response. For example, the following error response was generated due to an expired signature.

<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> <Error> <Type>Sender</Type> <Code>SignatureDoesNotMatch</Code> <Message>Signature expired: 20120306T074514Z is now earlier than 20120306T074556Z (20120306T080056Z - 15 min.)</Message> </Error> <RequestId>fcc88440-5dec-11e1-b901-a702cd369eb8</RequestId> </ErrorResponse>

Troubleshooting AWS Signature Version 4 Key Signing Errors

Errors that are caused by an incorrect derivation of the signing key or improper use of cryptography are more difficult to troubleshoot. The error response will tell you that the signature does not match. If you verified that the canonical string and the string to sign are correct, the cause of the signature mismatch is most likely one of the two following issues:

  • The secret access key does not match the access key ID that you specified in the Credential parameter.

  • There is a problem with your key derivation code.

To check whether the secret key matches the access key ID, you can use your secret key and access key ID with a known working implementation. One way is to use one of the AWS SDKs to write a program that makes a simple request to AWS using the access key ID and secret access key that you want to use.

To check whether your key derivation code is correct, you can compare it to our example derivation code. For more information, see Examples of How to Derive a Signing Key for Signature Version 4.