cookie

README

Cookie

Advanced cookie library for Go, support signed cookies.

Features

1. Lazy: Since cookie verification against multiple keys could be expensive, cookies are only verified lazily when accessed, not eagerly on each request.
2. Convenient: Signed cookies are stored the same way as unsigned cookies. An additional signature cookie is stored for each signed cookie, using a standard naming convention (cookie-name.sig). This allows other libraries to access the original cookies without having to know the signing mechanism.
3. compatibility for https://github.com/pillarjs/cookies

API

cookie.New(w http.ResponseWriter, r *http.Request[, keys ...string])

It returns a Cookies instance with optional keygrip for signed cookies.

cookies.Set(name, val string[, opts *Options])

It set the given cookie to the response and returns the current context to allow chaining. If options omit, it will use default options.

Options:

• MaxAge: a number representing the milliseconds for expiry (default to 0)
• Path: a string indicating the path of the cookie (default to "/").
• Domain: a string indicating the domain of the cookie (default to "").
• Secure: a boolean indicating whether the cookie is only to be sent over HTTP(S) (default to false).
• HTTPOnly: a boolean indicating whether the cookie is only to be sent over HTTP(S) (default to true).
• Signed: a boolean indicating whether the cookie is to be signed (default to false). If this is true, another cookie of the same name with the .sig suffix appended will also be sent.

cookies.Get(name string[, signed bool])

It returns the cookie with the given name from the Cookie header in the request. If such a cookie exists, its value is returned. Otherwise, nothing is returned. signed = true can optionally be passed as the second parameter. In this case, a signature cookie (a cookie of same name ending with the .sig suffix appended) is fetched. If the signature cookie does exist, cookie will check the hash of cookie-value whether matches registered keys.

Example

package main

import (
  "net/http"

  "github.com/go-http-utils/cookie"
)

func main() {
  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    cookies := cookie.New(w, r, "some key")

    cookies.Set("test", "some cookie", &cookie.Options{
      Signed:   true,
      HTTPOnly: true,
    })

    value, err := cookies.Get("test", true)
    if err != nil {
      w.WriteHeader(500)
      w.Write([]byte(err.Error()))
    } else {
      w.Write([]byte(value))
    }
  })

  http.ListenAndServe(":8080", nil)
}

Documentation

Index

• func SetHash(fn func(key, data string) []byte)
• type Cookies
  • func New(w http.ResponseWriter, r *http.Request, keys ...string) (cookie *Cookies)
  • func (c *Cookies) Get(name string, signed ...bool) (value string, err error)
  • func (c *Cookies) Remove(name string, options ...*Options)
  • func (c *Cookies) Set(name, val string, options ...*Options) *Cookies
• type Options

Functions

func SetHash

func SetHash(fn func(key, data string) []byte)

SetHash set a global hash function for signed cookies, default to:

func(key, data string) []byte {
	h := hmac.New(sha1.New, []byte(key))
	h.Write([]byte(data))
	return h.Sum(nil)
}

The default hash is for compatibility with https://github.com/pillarjs/cookies But it is easy to crack secret key. You should set a custom hash function, such as:

func(key, data string) []byte {
	h := hmac.New(sha256.New, []byte(key))
	h.Write([]byte(data))
	h.Write(salt) // some salt bytes
	return h.Sum(nil)
}

Types

type Cookies

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

Cookies manipulates http.Cookie easy, supports signed cookies.

func New

func New(w http.ResponseWriter, r *http.Request, keys ...string) (cookie *Cookies)

New returns a Cookies instance with optional keys for signed cookies.

func (*Cookies) Get

func (c *Cookies) Get(name string, signed ...bool) (value string, err error)

Get returns the cookie with the given name from the Cookie header in the request. If such a cookie exists, its value is returned. Otherwise, nothing is returned. signed = true can optionally be passed as the second parameter. In this case, a signature cookie (a cookie of same name ending with the .sig suffix appended) is fetched. If the signature cookie does exist, cookie will check the hash of cookie-value whether matches registered keys.

func (*Cookies) Remove

func (c *Cookies) Remove(name string, options ...*Options)

Remove remove the given cookie

func (*Cookies) Set

func (c *Cookies) Set(name, val string, options ...*Options) *Cookies

Set set the given cookie to the response and returns the current context to allow chaining. If options omit, it will use default options.

type Options

type Options struct {
	MaxAge   int    // optional
	Path     string // optional, default to "/"
	Domain   string // optional
	Secure   bool   // optional
	HTTPOnly bool   // optional, default to `true“
	Signed   bool   // optional
}

Options is used to setting cookie.