securecookie

README

securecookie

Documentation

Overview

Package gorilla/securecookie encodes and decodes authenticated and optionally encrypted cookie values.

Secure cookies can't be forged, because their values are validated using HMAC. When encrypted, the content is also inaccessible to malicious eyes.

To use it, first create a new SecureCookie instance:

var hashKey = []byte("very-secret")
var blockKey = []byte("a-lot-secret")
var s = securecookie.New(hashKey, blockKey)

The hashKey is required, used to authenticate the cookie value using HMAC. It is recommended to use a key with 32 or 64 bytes.

The blockKey is optional, used to encrypt the cookie value -- set it to nil to not use encryption. If set, the length must correspond to the block size of the encryption algorithm. For AES, used by default, valid lengths are 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

Strong keys can be created using the convenience function GenerateRandomKey().

Once a SecureCookie instance is set, use it to encode a cookie value:

func SetCookieHandler(w http.ResponseWriter, r *http.Request) {
	value := map[string]string{
		"foo": "bar",
	}
	if encoded, err := s.Encode("cookie-name", value); err == nil {
		cookie := &http.Cookie{
			Name:  "cookie-name",
			Value: encoded,
			Path:  "/",
		}
		http.SetCookie(w, cookie)
	}
}

Later, use the same SecureCookie instance to decode and validate a cookie value:

func ReadCookieHandler(w http.ResponseWriter, r *http.Request) {
	if cookie, err := r.Cookie("cookie-name"); err == nil {
		value := make(map[string]string)
		if err = s2.Decode("cookie-name", cookie.Value, &value); err == nil {
			fmt.Fprintf(w, "The value of foo is %q", value["foo"])
		}
	}
}

We stored a map[string]string, but secure cookies can hold any value that can be encoded using encoding/gob. To store custom types, they must be registered first using gob.Register(). For basic types this is not needed; it works out of the box.

Index

• Variables
• func DecodeMulti(name string, value string, dst interface{}, codecs ...Codec) error
• func EncodeMulti(name string, value interface{}, codecs ...Codec) (string, error)
• func GenerateRandomKey(length int) []byte
• type Codec
  • func CodecsFromPairs(keyPairs ...[]byte) []Codec
• type GobEncoder
  • func (e GobEncoder) Deserialize(src []byte, dst interface{}) error
  • func (e GobEncoder) Serialize(src interface{}) ([]byte, error)
• type JSONEncoder
  • func (e JSONEncoder) Deserialize(src []byte, dst interface{}) error
  • func (e JSONEncoder) Serialize(src interface{}) ([]byte, error)
• type MultiError
  • func (m MultiError) Error() string
• type SecureCookie
  • func New(hashKey, blockKey []byte) *SecureCookie
  • func (s *SecureCookie) BlockFunc(f func([]byte) (cipher.Block, error)) *SecureCookie
  • func (s *SecureCookie) Decode(name, value string, dst interface{}) error
  • func (s *SecureCookie) Encode(name string, value interface{}) (string, error)
  • func (s *SecureCookie) HashFunc(f func() hash.Hash) *SecureCookie
  • func (s *SecureCookie) MaxAge(value int) *SecureCookie
  • func (s *SecureCookie) MaxLength(value int) *SecureCookie
  • func (s *SecureCookie) MinAge(value int) *SecureCookie
  • func (s *SecureCookie) SetSerializer(sz Serializer) *SecureCookie
• type Serializer

Variables

var (
	ErrMacInvalid = errors.New("securecookie: the value is not valid")
)

Functions

func DecodeMulti

func DecodeMulti(name string, value string, dst interface{}, codecs ...Codec) error

DecodeMulti decodes a cookie value using a group of codecs.

The codecs are tried in order. Multiple codecs are accepted to allow key rotation.

func EncodeMulti

func EncodeMulti(name string, value interface{}, codecs ...Codec) (string, error)

EncodeMulti encodes a cookie value using a group of codecs.

The codecs are tried in order. Multiple codecs are accepted to allow key rotation.

func GenerateRandomKey

func GenerateRandomKey(length int) []byte

GenerateRandomKey creates a random key with the given length in bytes.

Types

type Codec

type Codec interface {
	Encode(name string, value interface{}) (string, error)
	Decode(name, value string, dst interface{}) error
}

Codec defines an interface to encode and decode cookie values.

func CodecsFromPairs

func CodecsFromPairs(keyPairs ...[]byte) []Codec

CodecsFromPairs returns a slice of SecureCookie instances.

It is a convenience function to create a list of codecs for key rotation.

type GobEncoder

type GobEncoder struct{}

GobEncoder encodes cookie values using encoding/gob. This is the simplest encoder and can handle complex types via gob.Register.

func (GobEncoder) Deserialize

func (e GobEncoder) Deserialize(src []byte, dst interface{}) error

Deserialize decodes a value using gob.

func (GobEncoder) Serialize

func (e GobEncoder) Serialize(src interface{}) ([]byte, error)

Serialize encodes a value using gob.

type JSONEncoder

type JSONEncoder struct{}

JSONEncoder encodes cookie values using encoding/json. Users who wish to encode complex types need to satisfy the json.Marshaller and json.Unmarshaller interfaces.

func (JSONEncoder) Deserialize

func (e JSONEncoder) Deserialize(src []byte, dst interface{}) error

Deserialize decodes a value using encoding/json.

func (JSONEncoder) Serialize

func (e JSONEncoder) Serialize(src interface{}) ([]byte, error)

Serialize encodes a value using encoding/json.

type MultiError

type MultiError []error

MultiError groups multiple errors.

func (MultiError) Error

func (m MultiError) Error() string

type SecureCookie

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

SecureCookie encodes and decodes authenticated and optionally encrypted cookie values.

func New

func New(hashKey, blockKey []byte) *SecureCookie

New returns a new SecureCookie.

hashKey is required, used to authenticate values using HMAC. Create it using GenerateRandomKey(). It is recommended to use a key with 32 or 64 bytes.

blockKey is optional, used to encrypt values. Create it using GenerateRandomKey(). The key length must correspond to the block size of the encryption algorithm. For AES, used by default, valid lengths are 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256. The default encoder used for cookie serialization is encoding/gob.

func (*SecureCookie) BlockFunc

func (s *SecureCookie) BlockFunc(f func([]byte) (cipher.Block, error)) *SecureCookie

BlockFunc sets the encryption function used to create a cipher.Block.

Default is crypto/aes.New.

func (*SecureCookie) Decode

func (s *SecureCookie) Decode(name, value string, dst interface{}) error

Decode decodes a cookie value.

It decodes, verifies a message authentication code, optionally decrypts and finally deserializes the value.

The name argument is the cookie name. It must be the same name used when it was stored. The value argument is the encoded cookie value. The dst argument is where the cookie will be decoded. It must be a pointer.

func (*SecureCookie) Encode

func (s *SecureCookie) Encode(name string, value interface{}) (string, error)

Encode encodes a cookie value.

It serializes, optionally encrypts, signs with a message authentication code, and finally encodes the value.

The name argument is the cookie name. It is stored with the encoded value. The value argument is the value to be encoded. It can be any value that can be encoded using encoding/gob. To store special structures, they must be registered first using gob.Register().

func (*SecureCookie) HashFunc

func (s *SecureCookie) HashFunc(f func() hash.Hash) *SecureCookie

HashFunc sets the hash function used to create HMAC.

Default is crypto/sha256.New.

func (*SecureCookie) MaxAge

func (s *SecureCookie) MaxAge(value int) *SecureCookie

MaxAge restricts the maximum age, in seconds, for the cookie value.

Default is 86400 * 30. Set it to 0 for no restriction.

func (*SecureCookie) MaxLength

func (s *SecureCookie) MaxLength(value int) *SecureCookie

MaxLength restricts the maximum length, in bytes, for the cookie value.

Default is 4096, which is the maximum value accepted by Internet Explorer.

func (*SecureCookie) MinAge

func (s *SecureCookie) MinAge(value int) *SecureCookie

MinAge restricts the minimum age, in seconds, for the cookie value.

Default is 0 (no restriction).

func (*SecureCookie) SetSerializer

func (s *SecureCookie) SetSerializer(sz Serializer) *SecureCookie

Encoding sets the encoding/serialization method for cookies.

Default is encoding/gob.

type Serializer

type Serializer interface {
	Serialize(src interface{}) ([]byte, error)
	Deserialize(src []byte, dst interface{}) error
}

Serializer provides an interface for providing custom serializers for cookie values.