hawk: go.mozilla.org/hawk Index | Files

package hawk

import "go.mozilla.org/hawk"

Index

Package Files

hawk.go

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.

type Auth Uses

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 Uses

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 Uses

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 Uses

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

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

func ParseBewit Uses

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 Uses

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 Uses

func (auth *Auth) Bewit() string

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

func (*Auth) NormalizedString Uses

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

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

func (*Auth) ParseHeader Uses

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 Uses

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 Uses

func (auth *Auth) RequestHeader() string

RequestHeader builds a request header based on the auth.

func (*Auth) ResponseHeader Uses

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 Uses

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 Uses

func (auth *Auth) StaleTimestampHeader() string

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

func (*Auth) UpdateOffset Uses

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 Uses

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 Uses

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 Uses

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 Uses

type AuthError string

func (AuthError) Error Uses

func (e AuthError) Error() string

type AuthFormatError Uses

type AuthFormatError struct {
    Field string
    Err   string
}

func (AuthFormatError) Error Uses

func (e AuthFormatError) Error() string

type AuthType Uses

type AuthType int
const (
    AuthHeader AuthType = iota
    AuthResponse
    AuthBewit
)

func (AuthType) String Uses

func (a AuthType) String() string

type CredentialError Uses

type CredentialError struct {
    Type        CredentialErrorType
    Credentials *Credentials
}

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

func (*CredentialError) Error Uses

func (e *CredentialError) Error() string

type CredentialErrorType Uses

type CredentialErrorType int
const (
    UnknownID CredentialErrorType = iota
    UnknownApp
    IDAppMismatch
)

func (CredentialErrorType) String Uses

func (t CredentialErrorType) String() string

type Credentials Uses

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 Uses

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

type CredentialsLookupFunc Uses

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 Uses

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.

Package hawk imports 15 packages (graph) and is imported by 8 packages. Updated 2016-07-21. Refresh now. Tools for package owners.