cookie

README

cookie

go package for cookie management

Thanks to A complete guide to working with Cookies in Go by Alex Edwards.

Documentation

Overview

package cookie implements basic, signed, and ecrypted cookies, drawing heavily from Alex Edward's work on cookies in Go: https://www.alexedwards.net/blog/working-with-cookies-in-go

Index

• Variables
• func NewCookieSecret() ([]byte, error)
• func Read(r *http.Request, name string) (string, error)
• func ReadEncrypted(r *http.Request, name string, secretKey []byte) (string, error)
• func ReadSigned(r *http.Request, name string, secretKey []byte) (string, error)
• func Write(w http.ResponseWriter, cookie http.Cookie) error
• func WriteEncrypted(w http.ResponseWriter, cookie http.Cookie, secretKey []byte) error
• func WriteSigned(w http.ResponseWriter, cookie http.Cookie, secretKey []byte) error
• type Cookie

Variables

var (
	ErrInitiation    = errors.New("initialization failure")
	ErrEncryption    = errors.New("encryption failure")
	ErrCookie        = errors.New("cookie failure")
	ErrSecretMissing = errors.New("secret key is missing")
)

Functions

func NewCookieSecret

func NewCookieSecret() ([]byte, error)

NewCookieSecret generates a random secret key for use with signed or encrypted cookies. Assumes secretLength is 32.

func Read

func Read(r *http.Request, name string) (string, error)

Read a basic base64 encoded cookie from the request, returning the decoded string

func ReadEncrypted

func ReadEncrypted(r *http.Request, name string, secretKey []byte) (string, error)

ReadEncrypted reads a cookie from the request and decrypts the AES-GCM encrypted value An encrypted cookie cannot be read by the client.

func ReadSigned

func ReadSigned(r *http.Request, name string, secretKey []byte) (string, error)

ReadSigned reads a cookie from the request and verifies the sha256 HMAC signature A signed cookie can be read by the client, but is tamper-evident.

func Write

func Write(w http.ResponseWriter, cookie http.Cookie) error

Write a cookie to the response without any additional modifications and basic length validation

func WriteEncrypted

func WriteEncrypted(w http.ResponseWriter, cookie http.Cookie, secretKey []byte) error

WriteEcrypted writes a cookie to the response with an AES-GCM encrypted value An encrypted cookie cannot be read by the client.

func WriteSigned

func WriteSigned(w http.ResponseWriter, cookie http.Cookie, secretKey []byte) error

WriteSigned writes a cookie to the response with a sha256 HMAC signature. A signed cookie can be read by the client, but is tamper-evident.

Types

type Cookie

type Cookie struct {
	Name   string
	Value  string
	Path   string // defaults to creation path
	Domain string // deafults to creation host

	Expires    time.Time
	RawExpires string

	// MaxAge=0 means no 'Max-Age' attribute specified.
	// MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'
	// MaxAge>0 means Max-Age attribute present and given in seconds
	MaxAge   int
	Secure   bool // only send via HTTPS or localhost
	HttpOnly bool // when true, JavaScript cannot access

	// SameSite allows a server to define a cookie attribute making it impossible for the browser to send this cookie along with cross-site requests.
	SameSite http.SameSite

	Raw      string
	Unparsed []string
}

Cookie defines an HTTP cookie. For more information see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies