Skip to content

Commit 1148427

Browse files
authored
reformat signer/v4 package doc (#2640)
1 parent b238d3f commit 1148427

File tree

2 files changed

+32
-31
lines changed

2 files changed

+32
-31
lines changed
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"id": "16a15922-898f-472d-b59d-d9deb6922968",
3+
"type": "bugfix",
4+
"description": "Fix confusing doc header in `aws/signer/v4` package.",
5+
"modules": [
6+
"."
7+
]
8+
}

aws/signer/v4/v4.go

Lines changed: 24 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,41 @@
1-
// Package v4 implements signing for AWS V4 signer
1+
// Package v4 implements the AWS signature version 4 algorithm (commonly known
2+
// as SigV4).
23
//
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.
56
//
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.
710
//
8-
// Generally using the signer outside of the SDK should not require any additional
11+
// # Pre-escaping a request URI
912
//
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.
1119
//
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.
1424
//
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:
1726
//
1827
// "//<hostname>/<path>"
1928
//
2029
// // e.g.
2130
// "//example.com/some/path"
2231
//
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.
3734
//
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.
4337
//
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
4639
package v4
4740

4841
import (

0 commit comments

Comments
 (0)