verifier

Documentation

Index

• Variables
• type Algorithm
• type KeyDirectory
• type NonceStorage
• type UncoveredBody
  • func (b UncoveredBody) Read(p []byte) (n int, err error)
• type Verifier
  • func (v *Verifier) Parse(w http.ResponseWriter, req *http.Request, now time.Time) (*http.Request, Algorithm, error)

Variables

var ErrBodyNotCovered = errors.New("the body cannot be read because it is not covered by a HTTP signature: include 'content-digest' and 'content-length' in the signature to fix this")

Types

type Algorithm

type Algorithm interface {
	Type() string
	Verify(ctx context.Context, base string, signature []byte) error
	ContentDigest() contentdigest.Digester
}

Algorithm to verify the incoming signed HTTP request with. The Type must be a valid entry in the HTTP Signature Algorithms registry https://www.rfc-editor.org/rfc/rfc9421.html#name-initial-contents

type KeyDirectory

type KeyDirectory interface {
	// GetKey looks up a signing key based on the key ID.
	//
	// It is not recommended to use the clientSpecifiedAlg, although this
	// is provided to adhere to the RFC spec.
	GetKey(ctx context.Context, kid string, clientSpecifiedAlg string) (Algorithm, error)
}

type NonceStorage

type NonceStorage interface {
	// Seen returns true if a nonce has been previously seen.
	//
	// An error is returned if there was a problem connecting to
	// the storage (for example, if database credentials were invalid).
	//
	// When implementing this interface you MUST mark the input nonce
	// as seen when Seen() is called, to protect against replay attacks.
	Seen(ctx context.Context, nonce string) (bool, error)
}

type UncoveredBody

type UncoveredBody struct {
}

UncoveredBody is an io.Reader which returns ErrBodyNotCovered when being read.

It is used to guard against applications treating an unsigned HTTP request body as trusted.

func (UncoveredBody) Read

func (b UncoveredBody) Read(p []byte) (n int, err error)

type Verifier

type Verifier struct {
	// NonceStorage is the storage layer
	// to check whether a nonce has been previously seen.
	NonceStorage NonceStorage

	// KeyDirectory is the directory used to look up
	// signing key material based on a key ID.
	KeyDirectory KeyDirectory

	// Tag is an application-specific tag for the signature as a String value.
	// This value is used by applications to help identify signatures relevant for specific applications or protocols.
	// See: https://www.rfc-editor.org/rfc/rfc9421.html#section-2.3-4.12
	//
	// In this verifier implementation a tag MUST be specified.
	// incoming requests must have only one signature matching the tag.
	Tag string

	// Validation is the options to use when validating the
	// signature params.
	Validation sigparams.ValidateOpts

	// Scheme is the expected URL scheme
	// that the verifier is running on.
	//
	// Should be 'https' in production.
	Scheme string

	// Authority is the expected HTTP authority
	// that the verifier is running on.
	Authority string

	// OnDeriveSigningString is a hook which can be used to log
	// the string to sign.
	//
	// This can be useful for debugging signature errors,
	// as you can compare the base signing string between the client
	// and server.
	OnDeriveSigningString func(ctx context.Context, stringToSign string)
}

Verifier verifies message signatures on an incoming HTTP request.

func (*Verifier) Parse

func (v *Verifier) Parse(w http.ResponseWriter, req *http.Request, now time.Time) (*http.Request, Algorithm, error)

Verification of an HTTP message signature is a process that takes as its input the signature context (including the target message, particularly its Signature and Signature-Input fields) and the requirements for the application.

The output of the verification is either a positive verification or an error.

See: https://www.rfc-editor.org/rfc/rfc9421.html#section-3.2

This method returns a parsed http.Request with all non-covered headers removed. The request body is also removed unless 'content-digest' and 'content-length' are included in the covered components.