sigv4a

Documentation

Overview

Package sigv4a implements request signing for AWS Signature Version 4a (asymmetric).

The algorithm for Signature Version 4a is identical to that of plain v4 apart from the following:

• A request can be signed for multiple regions. This is represented in the signature using the X-Amz-Region-Set header. The credential scope string used in the calculation correspondingly lacks the region component from that of plain v4.
• The string-to-sign component of the calculation is instead signed with an ECDSA private key. This private key is typically derived from your regular AWS credentials.

Index

• type SignRequestInput
• type Signer
  • func New(opts ...v4.SignerOption) *Signer
  • func (s *Signer) SignRequest(in *SignRequestInput, opts ...v4.SignerOption) error

Types

type SignRequestInput

type SignRequestInput struct {
	// The input request, which will modified in-place during signing.
	Request *http.Request

	// The SHA256 hash of the input request body.
	//
	// This value is NOT required to sign the request, but it is recommended to
	// provide it (or provide a Body on the HTTP request that implements
	// io.Seeker such that the signer can calculate it for you). Many services
	// do not accept requests with unsigned payloads.
	//
	// If a value is not provided, and DisableImplicitPayloadHashing has not
	// been set on SignerOptions, the signer will attempt to derive the payload
	// hash itself. The request's Body MUST implement io.Seeker in order to do
	// this, if it does not, the magic value for unsigned payload is used. If
	// the body does implement io.Seeker, but a call to Seek returns an error,
	// the signer will forward that error.
	PayloadHash []byte

	// The identity used to sign the request.
	Credentials credentials.Credentials

	// The service for which this request is to be signed.
	//
	// The appropriate value for this field is determined by the service
	// vendor.
	Service string

	// The set of regions for which this request is to be signed.
	//
	// The sentinel {"*"} is used to indicate that the signed request is valid
	// in all regions. Callers MUST set a value for this field - the API will
	// not fill in a default and the resulting signature will ultimately be
	// invalid.
	//
	// The acceptable values for list entries of this field are determined by
	// the service vendor.
	RegionSet []string

	// Wall-clock time used for calculating the signature.
	//
	// If the zero-value is given (generally by the caller not setting it), the
	// signer will instead use the current system clock time for the signature.
	Time time.Time
}

SignRequestInput is the set of inputs for the Sigv4a signing process.

type Signer

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

Signer signs requests with AWS Signature Version 4a.

Unlike Sigv4, AWS SigV4a signs requests with an ECDSA private key. This is derived automatically from the AWS credential identity passed to SignRequest. This derivation result is cached on the Signer and is uniquely identified by the access key ID (AKID) of the credentials that were provided.

Because of this, the caller is encouraged to create multiple instances of Signer for different underlying identities (e.g. IAM roles).

func New

func New(opts ...v4.SignerOption) *Signer

New returns an instance of Signer with applied options.

func (*Signer) SignRequest

func (s *Signer) SignRequest(in *SignRequestInput, opts ...v4.SignerOption) error

SignRequest signs an HTTP request with AWS Signature Version 4, modifying the request in-place by adding the headers that constitute the signature.

SignRequest will modify the request by setting the following headers:

• Host: required in general for HTTP/1.1 as well as for v4-signed requests
• X-Amz-Date: required for v4a-signed requests
• X-Amz-Region-Set: used to convey the regions for which the request is signed in v4a
• X-Amz-Security-Token: required for v4a-signed requests IF present on credentials used to sign, otherwise this header will not be set
• Authorization: contains the v4a signature string

The request MUST have a Host value set at the time that this API is called, such that it can be included in the signature calculation. Standard library HTTP clients set this as a request header by default, meaning that a request signed without a Host value will end up transmitting with the Host header anyway, which will cause the request to be rejected by the service due to signature mismatch (the Host header is required to be signed with Sigv4).

Generally speaking, using http.NewRequest will ensure that request instances are sufficiently initialized to be used with this API, though it is not strictly required.

SignRequest may be called any number of times on an http.Request instance, the header values set as part of the signature will simply be re-calculated. Note that v4a signatures are non-deterministic due to the random component of ECDSA signing, callers should not expect two calls to SignRequest() to produce an identical signature.