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 ¶
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 ¶
Functions ¶
func GenerateKey ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files