hawk

README

hawk-go

hawk-go implements the Hawk HTTP authentication scheme in Go.

Documentation

Installation

go get go.mozilla.org/hawk

Documentation

Index

• Variables
• type Auth
  • func NewAuthFromRequest(req *http.Request, creds CredentialsLookupFunc, nonce NonceCheckFunc) (*Auth, error)
  • func NewRequestAuth(req *http.Request, creds *Credentials, tsOffset time.Duration) *Auth
  • func NewURLAuth(uri string, creds *Credentials, tsOffset time.Duration) (*Auth, error)
  • func ParseBewit(bewit string) (*Auth, error)
  • func ParseRequestHeader(header string) (*Auth, error)
  • func (auth *Auth) Bewit() string
  • func (auth *Auth) NormalizedString(t AuthType) string
  • func (auth *Auth) ParseHeader(header string, t AuthType) error
  • func (auth *Auth) PayloadHash(contentType string) hash.Hash
  • func (auth *Auth) RequestHeader() string
  • func (auth *Auth) ResponseHeader(ext string) string
  • func (auth *Auth) SetHash(h hash.Hash)
  • func (auth *Auth) StaleTimestampHeader() string
  • func (auth *Auth) UpdateOffset(header string) (time.Duration, error)
  • func (auth *Auth) Valid() error
  • func (auth *Auth) ValidHash(h hash.Hash) bool
  • func (auth *Auth) ValidResponse(header string) error
• type AuthError
  • func (e AuthError) Error() string
• type AuthFormatError
  • func (e AuthFormatError) Error() string
• type AuthType
  • func (a AuthType) String() string
• type CredentialError
  • func (e *CredentialError) Error() string
• type CredentialErrorType
  • func (t CredentialErrorType) String() string
• type Credentials
  • func (creds *Credentials) MAC() hash.Hash
• type CredentialsLookupFunc
• type NonceCheckFunc

Variables

var (
	ErrNoAuth             = AuthError("no Authorization header or bewit parameter found")
	ErrReplay             = AuthError("request nonce is being replayed")
	ErrInvalidMAC         = AuthError("invalid MAC")
	ErrBewitExpired       = AuthError("bewit expired")
	ErrTimestampSkew      = AuthError("timestamp skew too high")
	ErrMissingServerAuth  = AuthError("missing Server-Authentication header")
	ErrInvalidBewitMethod = AuthError("bewit only allows HEAD and GET requests")
)

var MaxTimestampSkew = time.Minute

MaxTimestampSkew is the maximum ±skew that a request timestamp can have without returning ErrTimestampSkew.

var Now = time.Now

Now is a func() time.Time that is used by the package to get the current time.

Types

type Auth

type Auth struct {
	Credentials Credentials

	Method     string
	RequestURI string
	Host       string
	Port       string

	MAC   []byte
	Nonce string
	Ext   string
	Hash  []byte

	// ReqHash is true if the request contained a hash
	ReqHash   bool
	IsBewit   bool
	Timestamp time.Time

	// ActualTimestamp is when the request was received
	ActualTimestamp time.Time
}

func NewAuthFromRequest

func NewAuthFromRequest(req *http.Request, creds CredentialsLookupFunc, nonce NonceCheckFunc) (*Auth, error)

NewAuthFromRequest parses a request containing an Authorization header or bewit parameter and populates an Auth. If creds is not nil it will be called to look up the associated credentials. If nonce is not nil it will be called to make sure the nonce is not replayed.

If the request does not contain a bewit or Authorization header, ErrNoAuth is returned. If the request contains a bewit and it is not a GET or HEAD request, ErrInvalidBewitMethod is returned. If there is an error parsing the provided auth details, an AuthFormatError will be returned. If creds returns an error, it will be returned. If nonce returns false, ErrReplay will be returned.

func NewRequestAuth

func NewRequestAuth(req *http.Request, creds *Credentials, tsOffset time.Duration) *Auth

NewRequestAuth builds a client Auth based on req and creds. tsOffset will be applied to Now when setting the timestamp.

func NewURLAuth

func NewURLAuth(uri string, creds *Credentials, tsOffset time.Duration) (*Auth, error)

NewURLAuth builds a client Auth based on uri and creds. tsOffset will be applied to Now when setting the timestamp.

func ParseBewit

func ParseBewit(bewit string) (*Auth, error)

ParseBewit parses a bewit token provided in a URL parameter and populates an Auth. If an error is returned it will always be of type AuthFormatError.

func ParseRequestHeader

func ParseRequestHeader(header string) (*Auth, error)

ParseRequestHeader parses a Hawk header (provided in the Authorization HTTP header) and populates an Auth. If an error is returned it will always be of type AuthFormatError.

func (*Auth) Bewit

func (auth *Auth) Bewit() string

Bewit creates and encoded request bewit parameter based on the auth.

func (*Auth) NormalizedString

func (auth *Auth) NormalizedString(t AuthType) string

NormalizedString builds the string that will be HMACed to create a request MAC.

func (*Auth) ParseHeader

func (auth *Auth) ParseHeader(header string, t AuthType) error

ParseHeader parses a Hawk request or response header and populates auth. t must be AuthHeader if the header is an Authorization header from a request or AuthResponse if the header is a Server-Authorization header from a response.

func (*Auth) PayloadHash

func (auth *Auth) PayloadHash(contentType string) hash.Hash

PayloadHash initializes a hash for body validation. To validate a request or response body, call PayloadHash with contentType set to the body Content-Type with all parameters and prefix/suffix whitespace stripped, write the entire body to the returned hash, and then validate the hash with ValidHash.

func (*Auth) RequestHeader

func (auth *Auth) RequestHeader() string

RequestHeader builds a request header based on the auth.

func (*Auth) ResponseHeader

func (auth *Auth) ResponseHeader(ext string) string

ResponseHeader builds a response header based on the auth and provided ext, which may be an empty string. Use PayloadHash and SetHash before ResponseHeader to include a hash of the response payload.

func (*Auth) SetHash

func (auth *Auth) SetHash(h hash.Hash)

SetHash writes the final newline to h and sets auth.Hash to the sum. This is used to specify a response payload hash.

func (*Auth) StaleTimestampHeader

func (auth *Auth) StaleTimestampHeader() string

StaleTimestampHeader builds a signed WWW-Authenticate response header for use when Valid returns ErrTimestampSkew.

func (*Auth) UpdateOffset

func (auth *Auth) UpdateOffset(header string) (time.Duration, error)

UpdateOffset parses a signed WWW-Authenticate response header containing a stale timestamp error and updates auth.Timestamp with an adjusted timestamp.

func (*Auth) Valid

func (auth *Auth) Valid() error

Valid confirms that the timestamp is within skew and verifies the MAC.

If the request is valid, nil will be returned. If auth is a bewit and the method is not GET or HEAD, ErrInvalidBewitMethod will be returned. If auth is a bewit and the timestamp is after the the specified expiry, ErrBewitExpired will be returned. If auth is from a request header and the timestamp is outside the maximum skew, ErrTimestampSkew will be returned. If the MAC is not the expected value, ErrInvalidMAC will be returned.

func (*Auth) ValidHash

func (auth *Auth) ValidHash(h hash.Hash) bool

ValidHash writes the final newline to h and checks if it matches auth.Hash.

func (*Auth) ValidResponse

func (auth *Auth) ValidResponse(header string) error

ValidResponse checks that a response Server-Authorization header is correct.

ErrMissingServerAuth is returned if header is an empty string. ErrInvalidMAC is returned if the MAC is not the expected value.

type AuthError

type AuthError string

func (AuthError) Error

func (e AuthError) Error() string

type AuthFormatError

type AuthFormatError struct {
	Field string
	Err   string
}

func (AuthFormatError) Error

func (e AuthFormatError) Error() string

type AuthType

type AuthType int

const (
	AuthHeader AuthType = iota
	AuthResponse
	AuthBewit
)

func (AuthType) String

func (a AuthType) String() string

type CredentialError

type CredentialError struct {
	Type        CredentialErrorType
	Credentials *Credentials
}

CredentialError is returned by a CredentialsLookupFunc when the provided credentials ID is invalid.

func (*CredentialError) Error

func (e *CredentialError) Error() string

type CredentialErrorType

type CredentialErrorType int

const (
	UnknownID CredentialErrorType = iota
	UnknownApp
	IDAppMismatch
)

func (CredentialErrorType) String

func (t CredentialErrorType) String() string

type Credentials

type Credentials struct {
	ID   string
	Key  string
	Hash func() hash.Hash

	// Data may be set in a CredentialsLookupFunc to correlate the credentials
	// with an internal data record.
	Data interface{}

	App      string
	Delegate string
}

func (*Credentials) MAC

func (creds *Credentials) MAC() hash.Hash

type CredentialsLookupFunc

type CredentialsLookupFunc func(*Credentials) error

A CredentialsLookupFunc is called by NewAuthFromRequest after parsing the request auth. The Credentials will never be nil and ID will always be set. App and Delegate will be set if provided in the request. This function must look up the corresponding Key and Hash and set them on the provided Credentials. If the Key/Hash are found and the App/Delegate are valid (if provided) the error should be nil. If the Key or App could not be found or the App does not match the ID, then a CredentialError must be returned. Errors will propagate to the caller of NewAuthFromRequest, so internal errors may be returned.

type NonceCheckFunc

type NonceCheckFunc func(string, time.Time, *Credentials) bool

A NonceCheckFunc is called by NewAuthFromRequest and should make sure that the provided nonce is unique within the context of the provided time.Time and Credentials. It should return false if the nonce is being replayed.