Skip to content

Commit

Permalink
reformat signer/v4 package doc (#2640)
Browse files Browse the repository at this point in the history
  • Loading branch information
lucix-aws authored May 14, 2024
1 parent b238d3f commit 1148427
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 31 deletions.
8 changes: 8 additions & 0 deletions .changelog/16a15922898f472db59dd9deb6922968.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"id": "16a15922-898f-472d-b59d-d9deb6922968",
"type": "bugfix",
"description": "Fix confusing doc header in `aws/signer/v4` package.",
"modules": [
"."
]
}
55 changes: 24 additions & 31 deletions aws/signer/v4/v4.go
Original file line number Diff line number Diff line change
@@ -1,48 +1,41 @@
// Package v4 implements signing for AWS V4 signer
// Package v4 implements the AWS signature version 4 algorithm (commonly known
// as SigV4).
//
// Provides request signing for request that need to be signed with
// AWS V4 Signatures.
// For more information about SigV4, see [Signing AWS API requests] in the IAM
// user guide.
//
// # Standalone Signer
// While this implementation CAN work in an external context, it is developed
// primarily for SDK use and you may encounter fringe behaviors around header
// canonicalization.
//
// Generally using the signer outside of the SDK should not require any additional
// # Pre-escaping a request URI
//
// The signer does this by taking advantage of the URL.EscapedPath method. If your request URI requires
// AWS v4 signature validation requires that the canonical string's URI path
// component must be the escaped form of the HTTP request's path.
//
// The Go HTTP client will perform escaping automatically on the HTTP request.
// This may cause signature validation errors because the request differs from
// the URI path or query from which the signature was generated.
//
// additional escaping you many need to use the URL.Opaque to define what the raw URI should be sent
// to the service as.
// Because of this, we recommend that you explicitly escape the request when
// using this signer outside of the SDK to prevent possible signature mismatch.
// This can be done by setting URL.Opaque on the request. The signer will
// prefer that value, falling back to the return of URL.EscapedPath if unset.
//
// 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:
// When setting URL.Opaque you must do so 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.
//
// 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.
// http://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
// The leading "//" and hostname are required or the escaping will not work
// correctly.
//
// 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.
// The TestStandaloneSign unit test provides a complete example of using the
// signer outside of the SDK and pre-escaping the URI path.
//
// Test `TestStandaloneSign` provides a complete example of using the signer
// outside of the SDK and pre-escaping the URI path.
// [Signing AWS API requests]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html
package v4

import (
Expand Down

0 comments on commit 1148427

Please sign in to comment.