package v4

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

Package v4 implements the AWS signature version 4 algorithm (commonly known as SigV4).

For more information about SigV4, see Signing AWS API requests in the IAM user guide.

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.

Pre-escaping a request URI

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.

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.

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 escaping will not work correctly.

The TestStandaloneSign unit test provides a complete example of using the signer outside of the SDK and pre-escaping the URI path.

Index

Constants 

const (

	// Version of signing v4
	Version = "SigV4"
)

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 AddStreamingEventsPayload 

func AddStreamingEventsPayload(stack *middleware.Stack) error

AddStreamingEventsPayload adds the streamingEventsPayload middleware to the 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 GetSignedRequestSignature 

func GetSignedRequestSignature(r *http.Request) ([]byte, error)

GetSignedRequestSignature attempts to extract the signature of the request. Returning an error if the request is unsigned, or unable to extract the signature.

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.

func UseDynamicPayloadSigningMiddleware 

func UseDynamicPayloadSigningMiddleware(stack *middleware.Stack) error

UseDynamicPayloadSigningMiddleware swaps the compute payload sha256 middleware with a resolver middleware that switches between unsigned and signed payload based on TLS state for request. This middleware should not be used for AWS APIs that do not support unsigned payload signing auth. By default, SDK uses this middleware for known AWS APIs that support such TLS based auth selection .

Usage example - S3 PutObject API allows unsigned payload signing auth usage when TLS is enabled, and uses this middleware to dynamically switch between unsigned and signed payload based on TLS state for request.

Types

type ComputePayloadSHA256 

type ComputePayloadSHA256 struct{}

ComputePayloadSHA256 computes SHA256 payload hash to sign.

Will not set the Unsigned Payload magic SHA value, if a SHA has already been stored in the context. (e.g. application pre-computed SHA256 before making API call).

This middleware does not check the X-Amz-Content-Sha256 header, if that header is serialized a middleware must translate it into the context.

func (*ComputePayloadSHA256) HandleFinalize 

func (m *ComputePayloadSHA256) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize computes the payload hash for the request, storing it to the context. This is a no-op if a caller has previously set that value.

func (*ComputePayloadSHA256) ID 

func (m *ComputePayloadSHA256) ID() string

ID is the middleware name

type ContentSHA256Header 

type ContentSHA256Header struct{}

ContentSHA256Header sets the X-Amz-Content-Sha256 header value to the Payload hash stored in the context.

func (*ContentSHA256Header) HandleFinalize 

func (m *ContentSHA256Header) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize sets the X-Amz-Content-Sha256 header value to the Payload hash stored in the context.

func (*ContentSHA256Header) ID 

func (m *ContentSHA256Header) ID() string

ID returns the ContentSHA256HeaderMiddleware identifier

type EventStreamSigner 

type EventStreamSigner interface {
	GetSignature(ctx context.Context, headers, payload []byte, signingTime time.Time, optFns ...func(*StreamSignerOptions)) ([]byte, error)
}

EventStreamSigner is an AWS EventStream protocol signer.

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 

func (s *PresignHTTPRequestMiddleware) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

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 

func (*PresignHTTPRequestMiddleware) ID() string

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.

Deprecated: AWS service clients no longer use this middleware. Signing as an SDK operation is now performed through an internal per-service middleware which opaquely selects and uses the signer from the resolved auth scheme.

func NewSignHTTPRequestMiddleware 

func NewSignHTTPRequestMiddleware(options SignHTTPRequestMiddlewareOptions) *SignHTTPRequestMiddleware

NewSignHTTPRequestMiddleware constructs a SignHTTPRequestMiddleware using the given Signer for signing requests.

Deprecated: SignHTTPRequestMiddleware is deprecated.

func (*SignHTTPRequestMiddleware) HandleFinalize 

func (s *SignHTTPRequestMiddleware) HandleFinalize(ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

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

Deprecated: SignHTTPRequestMiddleware is deprecated.

func (*SignHTTPRequestMiddleware) ID 

func (s *SignHTTPRequestMiddleware) ID() string

ID is the SignHTTPRequestMiddleware identifier.

Deprecated: SignHTTPRequestMiddleware is deprecated.

type SignHTTPRequestMiddlewareOptions 

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

SignHTTPRequestMiddlewareOptions is the configuration options for SignHTTPRequestMiddleware.

Deprecated: SignHTTPRequestMiddleware is deprecated.

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

	// Disables setting the session token on the request as part of signing
	// through X-Amz-Security-Token. This is needed for variations of v4 that
	// present the token elsewhere.
	DisableSessionToken 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

type StreamSigner 

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

StreamSigner implements Signature Version 4 (SigV4) signing of event stream encoded payloads.

func NewStreamSigner 

func NewStreamSigner(credentials aws.Credentials, service, region string, seedSignature []byte, optFns ...func(*StreamSignerOptions)) *StreamSigner

NewStreamSigner returns a new AWS EventStream protocol signer.

func (*StreamSigner) GetSignature 

func (s *StreamSigner) GetSignature(ctx context.Context, headers, payload []byte, signingTime time.Time, optFns ...func(*StreamSignerOptions)) ([]byte, error)

GetSignature signs the provided header and payload bytes.

type StreamSignerOptions 

type StreamSignerOptions struct{}

StreamSignerOptions is the configuration options for StreamSigner.

type StreamingEventsPayload 

type StreamingEventsPayload struct{}

StreamingEventsPayload signs input event stream messages.

func (*StreamingEventsPayload) HandleFinalize 

func (s *StreamingEventsPayload) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize marks the input stream to be signed with SigV4.

func (*StreamingEventsPayload) ID 

func (s *StreamingEventsPayload) ID() string

ID identifies the middleware.

type UnsignedPayload 

type UnsignedPayload struct{}

UnsignedPayload sets the SigV4 request payload hash to unsigned.

Will not set the Unsigned Payload magic SHA value, if a SHA has already been stored in the context. (e.g. application pre-computed SHA256 before making API call).

This middleware does not check the X-Amz-Content-Sha256 header, if that header is serialized a middleware must translate it into the context.

func (*UnsignedPayload) HandleFinalize 

func (m *UnsignedPayload) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize sets the payload hash magic value to the unsigned sentinel.

func (*UnsignedPayload) ID 

func (m *UnsignedPayload) ID() string

ID returns the unsignedPayload identifier

Source Files

middleware.go presign_middleware.go stream.go v4.go

Version
v1.31.0
Published
Sep 20, 2024
Platform
linux/amd64
Imports
23 packages
Last checked
4 minutes ago –

Tools for package owners.