README

hawk-go Build Status

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

Documentation

Installation

go get go.mozilla.org/hawk
Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

View Source
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")
)
View Source
var MaxTimestampSkew = time.Minute

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

    View Source
    var Now = time.Now

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

      Functions

      This section is empty.

      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.

                                              Source Files