auth

Documentation

Overview

Package auth implements authorization scheme Signature, which works using MIME headers.

The client is expected to authenticate requests by sending a header "Authorization" formatted like this:

Authorization: Signature keyId="(key_id)",algorithm="hmac-sha256",
    headers="timestamp token",signature="(see below)"

The first element in 'headers' must either be "timestamp" (recommended), or "date" referring to HTTP header "Date". github.com/joyent/gosign is an implementation in Golang, github.com/joyent/node-http-signature for Node.js.

This is how you generate aforementioned 'signature' on the Linux shell:

secret="geheim"
timestamp="$(date --utc +%s)"
token="streng"

printf "${timestamp}${token}" \
| openssl dgst -sha256 -hmac "${secret}" -binary \
| openssl enc -base64

After that it's using, for example, 'curl' like this:

curl -T \
  --header 'Authorization: …' \
  --header 'Timestamp: …' --header 'Token: …' \
  <filename> <url>

Index

• type AuthorizationHeader
  • func (a *AuthorizationHeader) CheckFormal(headers http.Header, timestampRecv, timeTolerance uint64) Failure
  • func (a *AuthorizationHeader) Parse(str string) (err Failure)
  • func (a *AuthorizationHeader) SatisfiedBy(headers http.Header, secret []byte) bool
• type Failure
  • func Authenticate(headers http.Header, secrets HmacSecrets, timestampRecv, timeTolerance uint64) Failure
• type HmacSecrets
  • func (m HmacSecrets) Insert(tuples []string) error

Types

type AuthorizationHeader

type AuthorizationHeader struct {
	KeyID         string
	Algorithm     string // only hmac-sha256 is currently recognized
	HeadersToSign []string
	Extensions    []string // not used here
	Signature     []byte
}

AuthorizationHeader represents a HTTP header which is used in authentication scheme "Signature".

func (*AuthorizationHeader) CheckFormal

func (a *AuthorizationHeader) CheckFormal(headers http.Header, timestampRecv, timeTolerance uint64) Failure

CheckFormal returns true if all listed headers are present and timestamp(s) (if provided) are within a tolerance.

func (*AuthorizationHeader) Parse

func (a *AuthorizationHeader) Parse(str string) (err Failure)

Parse translates a string representation to this struct.

Use this to deserialize the result of http.Header.Get(…).

func (*AuthorizationHeader) SatisfiedBy

func (a *AuthorizationHeader) SatisfiedBy(headers http.Header, secret []byte) bool

SatisfiedBy tests if the headers and shared secret result in the same signature as given in the header.

As this is a rather costly function, call 'CheckFormal' first to avoid 'SatisfiedBy' where possible.

type Failure

type Failure interface {
	error

	// SuggestedResponseCode gives a HTTP status code.
	SuggestedResponseCode() int
}

Failure adds a behavioural hint to an Error.

func Authenticate

func Authenticate(headers http.Header, secrets HmacSecrets, timestampRecv, timeTolerance uint64) Failure

Authenticate implements authorization scheme Signature: Knowledge of a shared secret is expressed by providing its "signature".

'timestampRecv' is the Unix Timestamp at the time when the request has been received.

type HmacSecrets

type HmacSecrets map[string][]byte

HmacSecrets maps keyIDs to shared secrets.

func (HmacSecrets) Insert

func (m HmacSecrets) Insert(tuples []string) error

Insert decodes the key/value pairs and adds/updates them into the existing HMAC shared secret collection.

The format of each pair is:

key=base64(value)

For example:

hmac-key-1=yql3kIDweM8KYm+9pHzX0PKNskYAU46Jb5D6nLftTvo=

The first tuple that cannot be decoded is returned as error string.