south

README

South: stateless authenticated sessions

See this blog post for more background information about the protocol.

This package provides authentication tokens which can be used in place of the usual session IDs where the user ID is stored in the session data on the server.

Read for more information the API documentation at godoc.org.

Documentation

Overview

Package south provides stateless HTTP authentication using cookies.

It works by saving the user ID and creation time to a cookie, signed with HMAC-256. This cookie can later be verified. Note: this package only signs the cookie, it doesn't encrypt it. Therefore, the user ID and the creation time (in seconds) will be visible.

The user ID must be able to fit in a cookie value and not contain a colon. This means simple identifiers (including numbers) are allowed, but also e-mail adresses as defined by the HTML5 spec: https://html.spec.whatwg.org/multipage/forms.html#valid-e-mail-address.

Index

• Constants
• Variables
• func GenerateKey() ([]byte, error)
• type Store
  • func New(key []byte, path string) (*Store, error)
  • func (s *Store) NewToken(id string) (*Token, error)
  • func (s *Store) Verify(c *http.Cookie) (*Token, error)
• type Token
  • func (t *Token) Cookie() *http.Cookie
  • func (t *Token) Id() string

Constants

const DefaultCookieName = "sessionToken"

const DefaultDuration = 7 * 86400 // seven days

DefaultDuration is the default session duration for a session store.

const KeySize = sha256.Size

KeySize is the minimum size of the HMAC-SHA256 key.

Variables

var (
	ErrInvalidId    = errors.New("south: user ID contains invalid characters")
	ErrInvalidToken = errors.New("south: invalid token")
	ErrExpiredToken = errors.New("south: token expired")
	ErrKeySize      = errors.New("south: key does not have the right size")
)

Functions

func GenerateKey

func GenerateKey() ([]byte, error)

GenerateKey returns a new key of the right size for use by the session store.

Types

type Store

type Store struct {
	// The time after which tokens will expire, defaulting to DefaultDuration.
	Duration int

	// CookieName is the cookie name returned by Token.Cookie(), defaulting to
	// DefaultCookieName.
	CookieName string
	// contains filtered or unexported fields
}

Store saves authentication tokens inside cookies.

func New

func New(key []byte, path string) (*Store, error)

New returns a new session store. A new key can be generated using GenerateKey(). Returns an error if the key does not have the right length.

func (*Store) NewToken

func (s *Store) NewToken(id string) (*Token, error)

NewToken returns a new Token for this user ID. An error may be returned if the id doesn't adhere to the requirements (see package documentation for requirements on token IDs).

func (*Store) Verify

func (s *Store) Verify(c *http.Cookie) (*Token, error)

Verify verifies the token encapsulated inside the HTTP cookie. The error returned can be ErrInvalidToken or ErrExpiredToken for invalid or expred tokens, respectively.

ErrExpiredToken will not normally be returned, as cookie tokens should be removed by the browser once they expire.

type Token

type Token struct {
	// contains filtered or unexported fields
}

Token is a single authentication token for one user ID.

func (*Token) Cookie

func (t *Token) Cookie() *http.Cookie

Cookie returns a new cookie that can be appended to a request. You may want to regenerate the cookie for each request, to keep the session alive.

The returned cookie is secure by default: the 'secure' and 'httpOnly' flags are set. If you want to use this cookie over plain HTTP without SSL (making the token vulnerable to interception) or want to read it using JavaScript (making the token vulnerable to XSS attacks), you may modify the relevant flags inside the returned cookie.

func (*Token) Id

func (t *Token) Id() string

Id returns the user ID for this token.