README
¶
hawk-go 
hawk-go implements the Hawk HTTP authentication scheme in Go.
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
- type AuthFormatError
- type AuthType
- type CredentialError
- type CredentialErrorType
- type Credentials
- type CredentialsLookupFunc
- type NonceCheckFunc
Constants ¶
This section is empty.
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.
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 ¶
NewRequestAuth builds a client Auth based on req and creds. tsOffset will be applied to Now when setting the timestamp.
func NewURLAuth ¶
NewURLAuth builds a client Auth based on uri and creds. tsOffset will be applied to Now when setting the timestamp.
func ParseBewit ¶
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 ¶
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) NormalizedString ¶
NormalizedString builds the string that will be HMACed to create a request MAC.
func (*Auth) ParseHeader ¶
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 ¶
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 ¶
RequestHeader builds a request header based on the auth.
func (*Auth) ResponseHeader ¶
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 ¶
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 ¶
StaleTimestampHeader builds a signed WWW-Authenticate response header for use when Valid returns ErrTimestampSkew.
func (*Auth) UpdateOffset ¶
UpdateOffset parses a signed WWW-Authenticate response header containing a stale timestamp error and updates auth.Timestamp with an adjusted timestamp.
func (*Auth) Valid ¶
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 ¶
ValidHash writes the final newline to h and checks if it matches auth.Hash.
func (*Auth) ValidResponse ¶
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 AuthFormatError ¶
func (AuthFormatError) Error ¶
func (e AuthFormatError) Error() 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