session

Documentation

Overview

Package session provides a safer, shorter, faster session cookie.

:dart: Purpose

Safer because of random salt in the tokens and understandable/auditable source code. Shorter because of Base91 (no Base64), compression and index instead of key names. Faster because of AES (no RSA) and custom bar-metal serializer.

:closed_lock_with_key: Encryption

The current trend about symmetric encryption is to prefer ChaCha20Poly1305 (server side). In addition to its cryptographic qualities, ChaCha20 is easy to configure, and requires few CPU/memory resources.

On the other hand, on AMD and Intel processors, AES is faster (optimized instructions). Moreover, the Go crypto allows to configure AES well.

See also: https://go.dev/blog/tls-cipher-suites

Therefore this package uses only AES-GCM 128 bits (256 bits is not yet relevant in 2022). This may change for a future version, please share your thoughts.

:cookie: Session cookie

The serialization uses a format invented for the occasion which is called "incorruptible" (a mocktail that Garçon de café likes to serve). The format is: MagicCode (1 byte) + Radom (1 byte) + Presence bits (1 byte) + Token expiration (0 or 3 bytes) + Client IP (0, 4 or 16 bytes) + up to 31 other custom values (from 0 to 7900 bytes).

See https://pkg.go.dev/github.com/teal-finance/garcon/session/incorruptible

Optionally, some random padding can be appended. This feature is currently disabled.

When the token is too long, its payload is compressed with Snappy S2.

Then, the 128 bits AES-GCM encryption. This adds 16 bytes of header, including the authentication.

Finally, the Base91 encoding, adding some more bytes.

In the end, an "incorruptible" of 3 bytes (the minimum) becomes a Base91 of 21 or 22 bytes.

:no_entry_sign: Limitations

It works very well with a single server: the secrets could be generated at startup.

On the other hand, in an environment with load-balancer, or with an authentication server, you have to share the encryption key. In this last case, the Quid solution (signature verified by public key) is to be preferred.

Index

• Constants
• type Session
  • func New(urls []*url.URL, resErr reserr.ResErr, secretKey []byte, expiry time.Duration, ...) *Session
  • func (s *Session) BearerToken(r *http.Request) (base91 string, err error)
  • func (s *Session) Chk(next http.Handler) http.Handler
  • func (s *Session) CookieToken(r *http.Request) (base91 string, err error)
  • func (s *Session) Decode(str string) (dtoken.DToken, error)
  • func (s *Session) DecodeBearerToken(r *http.Request) (dt dtoken.DToken, err error)
  • func (s *Session) DecodeCookieToken(r *http.Request) (dt dtoken.DToken, err error)
  • func (s *Session) DecodeToken(r *http.Request) (dtoken.DToken, error)
  • func (s *Session) Encode(dt dtoken.DToken) (string, error)
  • func (s Session) NewCookie(dt dtoken.DToken) (http.Cookie, error)
  • func (s Session) NewCookieFromToken(base91 string, expiry time.Time) http.Cookie
  • func (s *Session) Set(next http.Handler) http.Handler
  • func (s Session) SetCookie(w http.ResponseWriter, r *http.Request) dtoken.DToken
  • func (s *Session) Vet(next http.Handler) http.Handler

Constants

const (
	HTTP  = "http"
	HTTPS = "https"
)

Supported URL shemes.

Types

type Session

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

func New

func New(urls []*url.URL, resErr reserr.ResErr, secretKey []byte, expiry time.Duration, setIP bool) *Session

func (*Session) BearerToken

func (s *Session) BearerToken(r *http.Request) (base91 string, err error)

func (*Session) Chk

func (s *Session) Chk(next http.Handler) http.Handler

Chk accepts requests only if it has a valid cookie. Chk does not verify the "Authorization" header. See the Vet() function to also verify the "Authorization" header. Chk also stores the decoded token in the request context. In dev. testing, Chk accepts any request but does not store invalid tokens.

func (*Session) CookieToken

func (s *Session) CookieToken(r *http.Request) (base91 string, err error)

func (*Session) Decode

func (s *Session) Decode(str string) (dtoken.DToken, error)

func (*Session) DecodeBearerToken

func (s *Session) DecodeBearerToken(r *http.Request) (dt dtoken.DToken, err error)

func (*Session) DecodeCookieToken

func (s *Session) DecodeCookieToken(r *http.Request) (dt dtoken.DToken, err error)

func (*Session) DecodeToken

func (s *Session) DecodeToken(r *http.Request) (dtoken.DToken, error)

func (*Session) Encode

func (s *Session) Encode(dt dtoken.DToken) (string, error)

func (Session) NewCookie

func (s Session) NewCookie(dt dtoken.DToken) (http.Cookie, error)

func (Session) NewCookieFromToken

func (s Session) NewCookieFromToken(base91 string, expiry time.Time) http.Cookie

func (*Session) Set

func (s *Session) Set(next http.Handler) http.Handler

Set puts a "session" cookie when the request has no valid "incorruptible" token. The token is searched the "session" cookie and in the first "Authorization" header. The "session" cookie (that is added in the response) contains the "tiny" token. Finally, Set stores the decoded token in the request context.

func (Session) SetCookie

func (s Session) SetCookie(w http.ResponseWriter, r *http.Request) dtoken.DToken

func (*Session) Vet

func (s *Session) Vet(next http.Handler) http.Handler

Vet accepts requests having a valid token either in the "session" cookie or in the first "Authorization" header. Vet also stores the decoded token in the request context. In dev. testing, Vet accepts any request but does not store invalid tokens.