|
1 |
| -// Package v4 implements signing for AWS V4 signer |
| 1 | +// Package v4 implements the AWS signature version 4 algorithm (commonly known |
| 2 | +// as SigV4). |
2 | 3 | //
|
3 |
| -// Provides request signing for request that need to be signed with |
4 |
| -// AWS V4 Signatures. |
| 4 | +// For more information about SigV4, see [Signing AWS API requests] in the IAM |
| 5 | +// user guide. |
5 | 6 | //
|
6 |
| -// # Standalone Signer |
| 7 | +// While this implementation CAN work in an external context, it is developed |
| 8 | +// primarily for SDK use and you may encounter fringe behaviors around header |
| 9 | +// canonicalization. |
7 | 10 | //
|
8 |
| -// Generally using the signer outside of the SDK should not require any additional |
| 11 | +// # Pre-escaping a request URI |
9 | 12 | //
|
10 |
| -// The signer does this by taking advantage of the URL.EscapedPath method. If your request URI requires |
| 13 | +// AWS v4 signature validation requires that the canonical string's URI path |
| 14 | +// component must be the escaped form of the HTTP request's path. |
| 15 | +// |
| 16 | +// The Go HTTP client will perform escaping automatically on the HTTP request. |
| 17 | +// This may cause signature validation errors because the request differs from |
| 18 | +// the URI path or query from which the signature was generated. |
11 | 19 | //
|
12 |
| -// additional escaping you many need to use the URL.Opaque to define what the raw URI should be sent |
13 |
| -// to the service as. |
| 20 | +// Because of this, we recommend that you explicitly escape the request when |
| 21 | +// using this signer outside of the SDK to prevent possible signature mismatch. |
| 22 | +// This can be done by setting URL.Opaque on the request. The signer will |
| 23 | +// prefer that value, falling back to the return of URL.EscapedPath if unset. |
14 | 24 | //
|
15 |
| -// The signer will first check the URL.Opaque field, and use its value if set. |
16 |
| -// The signer does require the URL.Opaque field to be set in the form of: |
| 25 | +// When setting URL.Opaque you must do so in the form of: |
17 | 26 | //
|
18 | 27 | // "//<hostname>/<path>"
|
19 | 28 | //
|
20 | 29 | // // e.g.
|
21 | 30 | // "//example.com/some/path"
|
22 | 31 | //
|
23 |
| -// The leading "//" and hostname are required or the URL.Opaque escaping will |
24 |
| -// not work correctly. |
25 |
| -// |
26 |
| -// If URL.Opaque is not set the signer will fallback to the URL.EscapedPath() |
27 |
| -// method and using the returned value. |
28 |
| -// |
29 |
| -// AWS v4 signature validation requires that the canonical string's URI path |
30 |
| -// element must be the URI escaped form of the HTTP request's path. |
31 |
| -// http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html |
32 |
| -// |
33 |
| -// The Go HTTP client will perform escaping automatically on the request. Some |
34 |
| -// of these escaping may cause signature validation errors because the HTTP |
35 |
| -// request differs from the URI path or query that the signature was generated. |
36 |
| -// https://golang.org/pkg/net/url/#URL.EscapedPath |
| 32 | +// The leading "//" and hostname are required or the escaping will not work |
| 33 | +// correctly. |
37 | 34 | //
|
38 |
| -// Because of this, it is recommended that when using the signer outside of the |
39 |
| -// SDK that explicitly escaping the request prior to being signed is preferable, |
40 |
| -// and will help prevent signature validation errors. This can be done by setting |
41 |
| -// the URL.Opaque or URL.RawPath. The SDK will use URL.Opaque first and then |
42 |
| -// call URL.EscapedPath() if Opaque is not set. |
| 35 | +// The TestStandaloneSign unit test provides a complete example of using the |
| 36 | +// signer outside of the SDK and pre-escaping the URI path. |
43 | 37 | //
|
44 |
| -// Test `TestStandaloneSign` provides a complete example of using the signer |
45 |
| -// outside of the SDK and pre-escaping the URI path. |
| 38 | +// [Signing AWS API requests]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html |
46 | 39 | package v4
|
47 | 40 |
|
48 | 41 | import (
|
|
0 commit comments