Documentation

Overview

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

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.

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

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.

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddComputePayloadSHA256Middleware

func AddComputePayloadSHA256Middleware(stack *middleware.Stack) error

    AddComputePayloadSHA256Middleware adds computePayloadSHA256 to the operation middleware stack

    func AddContentSHA256HeaderMiddleware

    func AddContentSHA256HeaderMiddleware(stack *middleware.Stack) error

      AddContentSHA256HeaderMiddleware adds ContentSHA256Header to the operation middleware stack

      func AddUnsignedPayloadMiddleware

      func AddUnsignedPayloadMiddleware(stack *middleware.Stack) error

        AddUnsignedPayloadMiddleware adds unsignedPayload to the operation middleware stack

        func GetPayloadHash

        func GetPayloadHash(ctx context.Context) (v string)

          GetPayloadHash retrieves the payload hash to use for signing

          Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

          func RemoveComputePayloadSHA256Middleware

          func RemoveComputePayloadSHA256Middleware(stack *middleware.Stack) error

            RemoveComputePayloadSHA256Middleware removes computePayloadSHA256 from the operation middleware stack

            func RemoveContentSHA256HeaderMiddleware

            func RemoveContentSHA256HeaderMiddleware(stack *middleware.Stack) error

              RemoveContentSHA256HeaderMiddleware removes contentSHA256Header middleware from the operation middleware stack

              func SetPayloadHash

              func SetPayloadHash(ctx context.Context, hash string) context.Context

                SetPayloadHash sets the payload hash to be used for signing the request

                Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

                func SwapComputePayloadSHA256ForUnsignedPayloadMiddleware

                func SwapComputePayloadSHA256ForUnsignedPayloadMiddleware(stack *middleware.Stack) error

                  SwapComputePayloadSHA256ForUnsignedPayloadMiddleware replaces the ComputePayloadSHA256 middleware with the UnsignedPayload middleware.

                  Use this to disable computing the Payload SHA256 checksum and instead use UNSIGNED-PAYLOAD for the SHA256 value.

                  Types

                  type HTTPPresigner

                  type HTTPPresigner interface {
                  	PresignHTTP(
                  		ctx context.Context, credentials aws.Credentials, r *http.Request,
                  		payloadHash string, service string, region string, signingTime time.Time,
                  		optFns ...func(*SignerOptions),
                  	) (url string, signedHeader http.Header, err error)
                  }

                    HTTPPresigner is an interface to a SigV4 signer that can sign create a presigned URL for a HTTP requests.

                    type HTTPSigner

                    type HTTPSigner interface {
                    	SignHTTP(ctx context.Context, credentials aws.Credentials, r *http.Request, payloadHash string, service string, region string, signingTime time.Time, optFns ...func(*SignerOptions)) error
                    }

                      HTTPSigner is an interface to a SigV4 signer that can sign HTTP requests

                      type HashComputationError

                      type HashComputationError struct {
                      	Err error
                      }

                        HashComputationError indicates an error occurred while computing the signing hash

                        func (*HashComputationError) Error

                        func (e *HashComputationError) Error() string

                          Error is the error message

                          func (*HashComputationError) Unwrap

                          func (e *HashComputationError) Unwrap() error

                            Unwrap returns the underlying error if one is set

                            type PresignHTTPRequestMiddleware

                            type PresignHTTPRequestMiddleware struct {
                            	// contains filtered or unexported fields
                            }

                              PresignHTTPRequestMiddleware provides the Finalize middleware for creating a presigned URL for an HTTP request.

                              Will short circuit the middleware stack and not forward onto the next Finalize handler.

                              func NewPresignHTTPRequestMiddleware

                              func NewPresignHTTPRequestMiddleware(options PresignHTTPRequestMiddlewareOptions) *PresignHTTPRequestMiddleware

                                NewPresignHTTPRequestMiddleware returns a new PresignHTTPRequestMiddleware initialized with the presigner.

                                func (*PresignHTTPRequestMiddleware) HandleFinalize

                                  HandleFinalize will take the provided input and create a presigned url for the http request using the SigV4 presign authentication scheme.

                                  Since the signed request is not a valid HTTP request

                                  func (*PresignHTTPRequestMiddleware) ID

                                    ID provides the middleware ID.

                                    type PresignHTTPRequestMiddlewareOptions

                                    type PresignHTTPRequestMiddlewareOptions struct {
                                    	CredentialsProvider aws.CredentialsProvider
                                    	Presigner           HTTPPresigner
                                    	LogSigning          bool
                                    }

                                      PresignHTTPRequestMiddlewareOptions is the options for the PresignHTTPRequestMiddleware middleware.

                                      type PresignedHTTPRequest

                                      type PresignedHTTPRequest struct {
                                      	URL          string
                                      	Method       string
                                      	SignedHeader http.Header
                                      }

                                        PresignedHTTPRequest provides the URL and signed headers that are included in the presigned URL.

                                        type SignHTTPRequestMiddleware

                                        type SignHTTPRequestMiddleware struct {
                                        	// contains filtered or unexported fields
                                        }

                                          SignHTTPRequestMiddleware is a `FinalizeMiddleware` implementation for SigV4 HTTP Signing

                                          func NewSignHTTPRequestMiddleware

                                          func NewSignHTTPRequestMiddleware(options SignHTTPRequestMiddlewareOptions) *SignHTTPRequestMiddleware

                                            NewSignHTTPRequestMiddleware constructs a SignHTTPRequestMiddleware using the given Signer for signing requests

                                            func (*SignHTTPRequestMiddleware) HandleFinalize

                                              HandleFinalize will take the provided input and sign the request using the SigV4 authentication scheme

                                              func (*SignHTTPRequestMiddleware) ID

                                                ID is the SignHTTPRequestMiddleware identifier

                                                type SignHTTPRequestMiddlewareOptions

                                                type SignHTTPRequestMiddlewareOptions struct {
                                                	CredentialsProvider aws.CredentialsProvider
                                                	Signer              HTTPSigner
                                                	LogSigning          bool
                                                }

                                                  SignHTTPRequestMiddlewareOptions is the configuration options for the SignHTTPRequestMiddleware middleware.

                                                  type Signer

                                                  type Signer struct {
                                                  	// contains filtered or unexported fields
                                                  }

                                                    Signer applies AWS v4 signing to given request. Use this to sign requests that need to be signed with AWS V4 Signatures.

                                                    func NewSigner

                                                    func NewSigner(optFns ...func(signer *SignerOptions)) *Signer

                                                      NewSigner returns a new SigV4 Signer

                                                      func (*Signer) PresignHTTP

                                                      func (s *Signer) PresignHTTP(
                                                      	ctx context.Context, credentials aws.Credentials, r *http.Request,
                                                      	payloadHash string, service string, region string, signingTime time.Time,
                                                      	optFns ...func(*SignerOptions),
                                                      ) (signedURI string, signedHeaders http.Header, err error)

                                                        PresignHTTP signs AWS v4 requests with the payload hash, service name, region the request is made to, and time the request is signed at. The signTime allows you to specify that a request is signed for the future, and cannot be used until then.

                                                        Returns the signed URL and the map of HTTP headers that were included in the signature or an error if signing the request failed. For presigned requests these headers and their values must be included on the HTTP request when it is made. This is helpful to know what header values need to be shared with the party the presigned request will be distributed to.

                                                        The payloadHash is the hex encoded SHA-256 hash of the request payload, and must be provided. Even if the request has no payload (aka body). If the request has no payload you should use the hex encoded SHA-256 of an empty string as the payloadHash value.

                                                        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
                                                        

                                                        Some services such as Amazon S3 accept alternative values for the payload hash, such as "UNSIGNED-PAYLOAD" for requests where the body will not be included in the request signature.

                                                        https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html

                                                        PresignHTTP differs from SignHTTP in that it will sign the request using query string instead of header values. This allows you to share the Presigned Request's URL with third parties, or distribute it throughout your system with minimal dependencies.

                                                        PresignHTTP will not set the expires time of the presigned request automatically. To specify the expire duration for a request add the "X-Amz-Expires" query parameter on the request with the value as the duration in seconds the presigned URL should be considered valid for. This parameter is not used by all AWS services, and is most notable used by Amazon S3 APIs.

                                                        expires := 20 * time.Minute
                                                        query := req.URL.Query()
                                                        query.Set("X-Amz-Expires", strconv.FormatInt(int64(expires/time.Second), 10)
                                                        req.URL.RawQuery = query.Encode()
                                                        

                                                        This method does not modify the provided request.

                                                        func (Signer) SignHTTP

                                                        func (s Signer) SignHTTP(ctx context.Context, credentials aws.Credentials, r *http.Request, payloadHash string, service string, region string, signingTime time.Time, optFns ...func(options *SignerOptions)) error

                                                          SignHTTP signs AWS v4 requests with the provided payload hash, service name, region the request is made to, and time the request is signed at. The signTime allows you to specify that a request is signed for the future, and cannot be used until then.

                                                          The payloadHash is the hex encoded SHA-256 hash of the request payload, and must be provided. Even if the request has no payload (aka body). If the request has no payload you should use the hex encoded SHA-256 of an empty string as the payloadHash value.

                                                          "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
                                                          

                                                          Some services such as Amazon S3 accept alternative values for the payload hash, such as "UNSIGNED-PAYLOAD" for requests where the body will not be included in the request signature.

                                                          https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html

                                                          Sign differs from Presign in that it will sign the request using HTTP header values. This type of signing is intended for http.Request values that will not be shared, or are shared in a way the header values on the request will not be lost.

                                                          The passed in request will be modified in place.

                                                          type SignerOptions

                                                          type SignerOptions struct {
                                                          	// Disables the Signer's moving HTTP header key/value pairs from the HTTP
                                                          	// request header to the request's query string. This is most commonly used
                                                          	// with pre-signed requests preventing headers from being added to the
                                                          	// request's query string.
                                                          	DisableHeaderHoisting bool
                                                          
                                                          	// Disables the automatic escaping of the URI path of the request for the
                                                          	// siganture's canonical string's path. For services that do not need additional
                                                          	// escaping then use this to disable the signer escaping the path.
                                                          	//
                                                          	// S3 is an example of a service that does not need additional escaping.
                                                          	//
                                                          	// http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html
                                                          	DisableURIPathEscaping bool
                                                          
                                                          	// The logger to send log messages to.
                                                          	Logger logging.Logger
                                                          
                                                          	// Enable logging of signed requests.
                                                          	// This will enable logging of the canonical request, the string to sign, and for presigning the subsequent
                                                          	// presigned URL.
                                                          	LogSigning bool
                                                          }

                                                            SignerOptions is the SigV4 Signer options.

                                                            type SigningError

                                                            type SigningError struct {
                                                            	Err error
                                                            }

                                                              SigningError indicates an error condition occurred while performing SigV4 signing

                                                              func (*SigningError) Error

                                                              func (e *SigningError) Error() string

                                                              func (*SigningError) Unwrap

                                                              func (e *SigningError) Unwrap() error

                                                                Unwrap returns the underlying error cause