cookies

Documentation

Overview

Package cookies contains helper functions for setting and retrieving cookies, including signed and encrypted ones.

Cookie values are encoded and decoded using encoding/gob, so you must register any non-basic type that you want to store in a cookie, using encoding/gob.Register.

Signed cookies are signed using HMAC-SHA1. Encrypted cookies are encrypted with AES and then signed with HMAC-SHA1.

Index

• Constants
• Variables
• func SetDefaults(defaults *Options)
• type Cookies
  • func New(r *http.Request, w http.ResponseWriter, c *codec.Codec, ...) *Cookies
  • func (c *Cookies) Delete(name string)
  • func (c *Cookies) Get(name string, out interface{}) error
  • func (c *Cookies) GetCookie(name string) (*http.Cookie, error)
  • func (c *Cookies) GetEncrypted(name string, out interface{}) error
  • func (c *Cookies) GetSecure(name string, out interface{}) error
  • func (c *Cookies) Has(name string) bool
  • func (c *Cookies) Set(name string, value interface{}) error
  • func (c *Cookies) SetCookie(cookie *http.Cookie)
  • func (c *Cookies) SetEncrypted(name string, value interface{}) error
  • func (c *Cookies) SetEncryptedOpts(name string, value interface{}, o *Options) error
  • func (c *Cookies) SetOpts(name string, value interface{}, o *Options) error
  • func (c *Cookies) SetSecure(name string, value interface{}) error
  • func (c *Cookies) SetSecureOpts(name string, value interface{}, o *Options) error
• type Options
  • func Defaults() *Options

Constants

const (
	// Maximum cookie size. See section 6.3 at http://www.ietf.org/rfc/rfc2109.txt.
	MaxSize = 4096
)

Variables

var (
	// Cookie is too big. See MaxSize.
	ErrCookieTooBig = errors.New("cookie is too big (maximum size is 4096 bytes)")
	// Tried to use signed or encrypted cookies without a Signer.
	ErrNoSigner = errors.New("no signer specified")
	// Tried to use encrypted cookies without an Encrypter.
	ErrNoEncrypter = errors.New("no encrypter specified")

	// Maximum representable UNIX time with a signed 32 bit integer. This
	// means that cookies won't be really permanent, but they will expire
	// on January 19th 2038. I don't know about you, but I hope to be around
	// by that time, so hopefully I'll find a solution for this issue in the
	// next few years. See http://en.wikipedia.org/wiki/Year_2038_problem for
	// more information.
	Permanent = time.Unix(2147483647, 0).UTC()
)

Functions

func SetDefaults

func SetDefaults(defaults *Options)

SetDefaults changes the default cookie options.

Types

type Cookies

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

Cookies includes conveniency functions for setting and retrieving cookies. Use New() or gnd.la/app.Context.Cookies to create a Cookies instance.

func New

func New(r *http.Request, w http.ResponseWriter, c *codec.Codec, signer *cryptoutil.Signer, encrypter *cryptoutil.Encrypter, defaults *Options) *Cookies

New returns a new *Cookies object, which will read cookies from the given http.Request, and write them to the given http.ResponseWriter. Note that users will probably want to use gnd.la/app.Context.Cookies rather than this function to create a Cookies instance.

The secret parameter is used for secure (signed) cookies, while encryptionKey is also used for encrypted cookies. If you don't use secure nor encrypted cookies, you might leave both parameters empty. If you only need signed cookies, you might leave encryptionKey empty.

The default parameter specifies the default Options for the funcions which only take a name and a value. If you pass nil, Defaults will be used.

func (*Cookies) Delete

func (c *Cookies) Delete(name string)

Delete deletes with cookie with the given name.

func (*Cookies) Get

func (c *Cookies) Get(name string, out interface{}) error

Get uses the cookie value with the given name to populate the out argument. If the types don't match (e.g. the cookie was set to a string and you try to get an int), an error will be returned.

func (*Cookies) GetCookie

func (c *Cookies) GetCookie(name string) (*http.Cookie, error)

GetCookie returns the raw *http.Coookie with the given name.

func (*Cookies) GetEncrypted

func (c *Cookies) GetEncrypted(name string, out interface{}) error

GetEncrypted works like Get, but for cookies set with SetEncrypted(). See SetEncrypted() for the guarantees made about the cookie value.

func (*Cookies) GetSecure

func (c *Cookies) GetSecure(name string, out interface{}) error

GetSecure works like Get, but for cookies set with SetSecure(). See SetSecure() for the guarantees made about the cookie value.

func (*Cookies) Has

func (c *Cookies) Has(name string) bool

Has returns true if a cookie with the given name exists.

func (*Cookies) Set

func (c *Cookies) Set(name string, value interface{}) error

Set sets the cookie with the given name and encodes the given value using the codec provided in New. If the cookie size if bigger than 4096 bytes, it returns ErrCookieTooBig.

The options used for the cookie are the default ones provided in New(), which will usually come from gnd.la/app.App.CookieOptions. If you need to specify different options, use SetOpts().

func (*Cookies) SetCookie

func (c *Cookies) SetCookie(cookie *http.Cookie)

SetCookie sets the given *http.Cookie.

func (*Cookies) SetEncrypted

func (c *Cookies) SetEncrypted(name string, value interface{}) error

SetEncrypted sets a tamper-proof and encrypted cookie. The value is first encrypted using *cryptoutil.Encrypter and the signed using *cryptoutil.Signer. By default, these use AES and HMAC-SHA1 respectivelly. The user will not be able to tamper with the cookie value nor reveal its contents.

If you haven't set a Signer (usually set automatically for you, derived from the gnd.la/app.App.Secret field) and an Encrypter (usually set automatically too, from gnd.la/app.App.EncryptionKey), this function will return an error.

The options used for the cookie are the default ones provided in New(), which will usually come from gnd.la/app.App.CookieOptions. If you need to specify different options, use SetEncryptedOpts().

func (*Cookies) SetEncryptedOpts

func (c *Cookies) SetEncryptedOpts(name string, value interface{}, o *Options) error

SetEncryptedOpts works like SetEncrypted(), but accepts and Options parameter.

func (*Cookies) SetOpts

func (c *Cookies) SetOpts(name string, value interface{}, o *Options) error

SetOpts works like Set(), but accepts an Options parameter.

func (*Cookies) SetSecure

func (c *Cookies) SetSecure(name string, value interface{}) error

SetSecure sets a tamper-proof cookie, using the a *cryptoutil.Signer to sign its value. By default, it uses HMAC-SHA1. The user will be able to see the value of the cookie, but he will not be able to manipulate it. If you also require the value to be protected from being revealed to the user, use SetEncrypted().

If you haven't set a Signer (usually set automatically for you, derived from the gnd.la/app.App.Secret field), this function will return an error.

The options used for the cookie are the default ones provided in New(), which will usually come from gnd.la/app.App.CookieOptions. If you need to specify different options, use SetSecureOpts().

func (*Cookies) SetSecureOpts

func (c *Cookies) SetSecureOpts(name string, value interface{}, o *Options) error

SetSecureOpts works like SetSecure(), but accepts an Options parameter.

type Options

type Options struct {
	Path     string
	Domain   string
	Expires  time.Time
	MaxAge   int
	Secure   bool
	HttpOnly bool
}

Options specify the default cookie Options used when setting a Cookie only by its name and value, like in Cookies.Set(), Cookies.SetSecure(), and Cookies.SetEncrypted().

For more information about the cookie fields, see net/http.Cookie.

func Defaults

func Defaults() *Options

Defaults returns the default coookie options, which are:

Path: "/"
Expires: Permanent (cookie never expires)

To change the defaults, use SetDefaults.