aws4

README

aws4

Documentation

Overview

Package aws4 allows for signing requests and verifying signatures using AWS Signature Version 4.

Signing follows the Signature Version 4 format as specified by AWS in the AWS General Reference, section Signing AWS requests: https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html (2020-06-02T09:07:55+00:00). The official AWS SDK for Go was consulted for compatibility and implementation details: https://docs.aws.amazon.com/sdk-for-go/api/aws/signer/v4/ (2020-06-02T09:07:55+00:00).

Verification of signatures compatible with AWS Signature Version 4 has been added as well.

Index

• Variables
• func AccessKeyIDFromRequest(req *http.Request) string
• type Signer
  • func NewSigner(provider credentials.Provider) *Signer
  • func NewSignerWithStaticCredentials(id string, secret string, token string) *Signer
  • func NewSignerWithTimeNowFunc(provider credentials.Provider, timeNowFunc func() time.Time) *Signer
  • func (s *Signer) Presign(req *http.Request, body io.ReadSeeker, service string, region string, ...) error
  • func (s *Signer) Sign(req *http.Request, body io.ReadSeeker, service string, region string, ...) error
  • func (s *Signer) Validate(req *http.Request) (*SigningContext, error)
• type SigningContext
  • func (s *SigningContext) AddSigToRequest()
  • func (s *SigningContext) Build() error
  • func (s *SigningContext) Parse() error

Variables

var (
	// ErrMalformedSignature indicates the request does not have a signature or it is malformed
	ErrMalformedSignature = errors.New("malformed signature")
	// ErrExpiredSignature indicates the request has a properly formatted signature, but it has expired
	ErrExpiredSignature = errors.New("expired signature")
	// ErrInvalidSignature indicates the request has a properly formatted signature, but it is invalid for the credentials provided
	ErrInvalidSignature = errors.New("invalid signature")
	// ErrInvalidSignatureAlgorithm indicates the signature algorithm specified in the request does not match the current one
	ErrInvalidSignatureAlgorithm = errors.New("invalid signature algorithm")
)

Functions

func AccessKeyIDFromRequest

func AccessKeyIDFromRequest(req *http.Request) string

AccessKeyIDFromRequest attempts to retrieve the access key ID used for signing the request, checking for a presigned query parameter first before trying to parse a signed Authorization header.

If no credentials are found or they appear malformed, an empty string is returned.

Types

type Signer

type Signer struct {
	// The provider to use for retrieving credentials to sign the request against. Must be
	// provided in order to sign requests.
	Provider credentials.Provider
	// contains filtered or unexported fields
}

Signer allows for signing and presigning HTTP requests as well as verifying request signatures

func NewSigner

func NewSigner(provider credentials.Provider) *Signer

NewSigner returns a new Signer with the given provider set.

func NewSignerWithStaticCredentials

func NewSignerWithStaticCredentials(id string, secret string, token string) *Signer

NewSignerWithStaticCredentials returns a new Signer with a static credentials provider set, using the given access key ID, secret and optional session token as signing credentials.

func NewSignerWithTimeNowFunc

func NewSignerWithTimeNowFunc(provider credentials.Provider, timeNowFunc func() time.Time) *Signer

NewSignerWithTimeNowFunc returns a new Signer with the given provider and a custom function for returning the current time set. This should only be used for unit testing, Signer will default to the current time if no custom function has been defined.

func (*Signer) Presign

func (s *Signer) Presign(req *http.Request, body io.ReadSeeker, service string, region string, expiry time.Duration, signTime time.Time) error

Presign signs the provided request using its body, the requested service and region at the specified signing time. It also allows for an expiry to be defined after which the request's signature becomes invalid. Passing an expiry of 0 disables this additional check, creating a signature with unlimited validity.

Presign will modify the request, escaping the host and URL as required and adding query parameters containing signature values. This type of signing is intended for requests that are shared with third parties or performed in a way that cannot preserve the defined header values. Note that all header values provided with the original request must be provided when performing the request after signing since they are included in the signature.

If no error is returned, the request originally provided will contain all information necessary and can be executed using standard Go HTTP clients to perform the signed request. Should an error be returned instead, discarding the original request is advised before attempting to sign it again since it may contain a half-completed signature.

func (*Signer) Sign

func (s *Signer) Sign(req *http.Request, body io.ReadSeeker, service string, region string, signTime time.Time) error

Sign signs the provided request using its body, the requested service and region at the specified signing time.

Sign will modify the request, escaping the host and URL as required and adding headers containing signature values. This type of signing is intended for requests that will not be shared and can be performed while maintaining the defined header values.

If no error is returned, the request originally provided will contain all information necessary and can be executed using standard Go HTTP clients to perform the signed request. Should an error be returned instead, discarding the original request is advised before attempting to sign it again since it may contain a half-completed signature.

func (*Signer) Validate

func (s *Signer) Validate(req *http.Request) (*SigningContext, error)

Validate validates the provided request, returning a parsed SigningContext containing information about the signature. If the signature is malformed or invalid, an error is returned instead.

Validate can be used to validate signed as well as presigned requests using the credentials associated with the Signer. During validation, the request is modified (as the signature will be re-generated using the Signer's credentials to verify it), however after successful validation, it will be restored to its original state.

If no error is returned, the request can be assumed to contain a valid signature and can be continued to be processed. Should an error be returned instead, the original request should not be processed any further as the signature might be invalid and the request might be in a modified, invalid state.

type SigningContext

type SigningContext struct {
	// Original HTTP request to sign, will be modified during signing and signature validation
	Request *http.Request
	// Body of the request
	Body io.ReadSeeker
	// Query of the original HTTP request, used for preparing a presigned signature while processing
	Query url.Values
	// Credentials to sign request with or validate against
	Credentials credentials.Credentials
	// Region of service request is sent for
	Region string
	// Service request is sent for
	Service string
	// Signing time for request
	SignTime time.Time
	// Expiry of request signature, 0 indicating a signature with no expiry
	Expiry time.Duration
	// Indicates whether the request is unsigned
	IsPresign bool
	// Toggles whether payload signing should be skipped
	UnsignedPayload bool
	// contains filtered or unexported fields
}

SigningContext stores information relevant to signing a request

func (*SigningContext) AddSigToRequest

func (s *SigningContext) AddSigToRequest()

AddSigToRequest adds the calculated request signature to the request's header or query, depending on whether the request should be signed or presigned.

func (*SigningContext) Build

func (s *SigningContext) Build() error

Build builds a signature for the request using the given signing context.

If no error is returned, the signing context's request will have all required values set and can be used to perform a signed request. Should an error be returned instead, discarding the signing context is advised before attempting to build it again since it may contain a half-completed signature.

func (*SigningContext) Parse

func (s *SigningContext) Parse() error

Parse parses the signed requests into the given signing context, verifying its signature in the process.

If no error is returned, the signing context will have its values filled out and the original request restored, ready to be processed by the consuming party. Should an error be returned instead, discarding the signing context is advised before attempting to build it again since it may contain a half-completed signature.