AWS SDK for Go (PILOT)
API Reference

PREVIEW DOCUMENTATION - This is a preview of a new format for the AWS SDK for Go API Reference documentation. For the current AWS SDK for Go API Reference, see https://docs.aws.amazon.com/sdk-for-go/api/.

We welcome your feedback on this new version of the documentation. Send your comments to aws-sdkdocs-feedback@amazon.com.

signer/v4

import "github.com/aws/aws-sdk-go/aws/signer/v4"

Package v4 implements signing for AWS V4 signer

Provides request signing for request that need to be signed with AWS V4 Signatures.

Standalone Signer

Generally using the signer outside of the SDK should not require any additional logic when using Go v1.5 or higher. The signer does this by taking advantage of the URL.EscapedPath method. If your request URI requires additional escaping you many need to use the URL.Opaque to define what the raw URI should be sent to the service as.

The signer will first check the URL.Opaque field, and use its value if set. The signer does require the URL.Opaque field to be set in the form of:

"//<hostname>/<path>" // e.g. "//example.com/some/path"

The leading "//" and hostname are required or the URL.Opaque escaping will not work correctly.

If URL.Opaque is not set the signer will fallback to the URL.EscapedPath() method and using the returned value. If you're using Go v1.4 you must set URL.Opaque if the URI path needs escaping. If URL.Opaque is not set with Go v1.5 the signer will fallback to URL.Path.

AWS v4 signature validation requires that the canonical string's URI path element must be the URI escaped form of the HTTP request's path. https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html

The Go HTTP client will perform escaping automatically on the request. Some of these escaping may cause signature validation errors because the HTTP request differs from the URI path or query that the signature was generated. https://golang.org/pkg/net/url/#URL.EscapedPath

Because of this, it is recommended that when using the signer outside of the SDK that explicitly escaping the request prior to being signed is preferable, and will help prevent signature validation errors. This can be done by setting the URL.Opaque or URL.RawPath. The SDK will use URL.Opaque first and then call URL.EscapedPath() if Opaque is not set.

If signing a request intended for HTTP2 server, and you're using Go 1.6.2 through 1.7.4 you should use the URL.RawPath as the pre-escaped form of the request URL. https://github.com/golang/go/issues/16847 points to a bug in Go pre 1.8 that fails to make HTTP2 requests using absolute URL in the HTTP message. URL.Opaque generally will force Go to make requests with absolute URL. URL.RawPath does not do this, but RawPath must be a valid escaping of Path or url.EscapedPath will ignore the RawPath escaping.

Test `TestStandaloneSign` provides a complete example of using the signer outside of the SDK and pre-escaping the URI path.