securecookie

README

Secure Cookie

This is a copy of the gorilla/securecookie package with the v2 changes I'm working on.

Documentation

Index

• Variables
• func DecodeMulti(name string, value string, dst any, codecs ...Codec) error
• func EncodeMulti(name string, value any, codecs ...Codec) (string, error)
• func GenerateRandomKey(length int) []byte
• type Codec
• type GobEncoder
  • func (e GobEncoder) Deserialize(src []byte, dst any) error
  • func (e GobEncoder) Serialize(src any) ([]byte, error)
• type JSONEncoder
  • func (e JSONEncoder) Deserialize(src []byte, dst any) error
  • func (e JSONEncoder) Serialize(src any) ([]byte, error)
• type MultiError
  • func (m MultiError) Error() string
• type NopEncoder
  • func (e NopEncoder) Deserialize(src []byte, dst any) error
  • func (e NopEncoder) Serialize(src any) ([]byte, error)
• type Options
• type SecureCookie
  • func New(key []byte, options *Options) (*SecureCookie, error)
  • func (s *SecureCookie) Decode(name, value string, dst any) (int64, error)
  • func (s *SecureCookie) Encode(name string, value any) (string, error)
• type Serializer

Variables

var (
	ErrKeyLength        = fmt.Errorf("the key must be %d bytes", chacha20poly1305.KeySize)
	ErrDecryptionFailed = fmt.Errorf("the value could not be decrypted")
	ErrNoCodecs         = fmt.Errorf("no codecs provided")
	ErrValueNotByte     = fmt.Errorf("the value is not a []byte")
	ErrValueNotBytePtr  = fmt.Errorf("the value is not a *[]byte")
	ErrValueTooLong     = fmt.Errorf("the value is too long")
	ErrTimestampInvalid = fmt.Errorf("the timestamp is invalid")
	ErrTimestampTooNew  = fmt.Errorf("the timestamp is too new")
	ErrTimestampExpired = fmt.Errorf("the timestamp is expired")
)

var DefaultOptions = &Options{
	MinAge:     0,
	MaxAge:     86400 * 30,
	MaxLength:  4096,
	Serializer: JSONEncoder{},
	TimeFunc: func() int64 {
		return time.Now().UTC().Unix()
	},
}

Functions

func DecodeMulti

func DecodeMulti(name string, value string, dst any, 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.

On error, may return a MultiError.

func EncodeMulti

func EncodeMulti(name string, value any, 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.

On error, may return a MultiError.

func GenerateRandomKey

func GenerateRandomKey(length int) []byte

GenerateRandomKey creates a random key with the given length in bytes. On failure, returns nil.

Note that keys created using `GenerateRandomKey()` are not automatically persisted. New keys will be created when the application is restarted, and previously issued cookies will not be able to be decoded.

Callers should explicitly check for the possibility of a nil return, treat it as a failure of the system random number generator, and not continue.

Types

type Codec

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

Codec defines an interface to encode and decode cookie values.

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 any) error

Deserialize decodes a value using gob.

func (GobEncoder) Serialize

func (e GobEncoder) Serialize(src any) ([]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 any) error

Deserialize decodes a value using encoding/json.

func (JSONEncoder) Serialize

func (e JSONEncoder) Serialize(src any) ([]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 NopEncoder

type NopEncoder struct{}

NopEncoder does not encode cookie values, and instead simply accepts a []byte (as an any) and returns a []byte. This is particularly useful when you encoding an object upstream and do not wish to re-encode it.

func (NopEncoder) Deserialize

func (e NopEncoder) Deserialize(src []byte, dst any) error

Deserialize passes a []byte through as-is.

func (NopEncoder) Serialize

func (e NopEncoder) Serialize(src any) ([]byte, error)

Serialize passes a []byte through as-is.

type Options

type Options struct {
	RotatedKeys [][]byte
	MinAge      int64
	MaxAge      int64
	MaxLength   int
	Serializer  Serializer
	TimeFunc    func() int64
}

type SecureCookie

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

SecureCookie encodes and decodes authenticated and optionally encrypted cookie values.

func New

func New(key []byte, options *Options) (*SecureCookie, error)

New returns a new SecureCookie.

Key is required and must be 32 bytes, used to authenticate and encrypt cookie values.

Note that keys created using GenerateRandomKey() are not automatically persisted. New keys will be created when the application is restarted, and previously issued cookies will not be able to be decoded.

func (*SecureCookie) Decode

func (s *SecureCookie) Decode(name, value string, dst any) (int64, 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 encoded. 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 any) (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 used to authenticate the cookie. The value argument is the value to be encoded. It can be any value that can be encoded using the currently selected serializer.

It is the client's responsibility to ensure that value, when encoded using the current serialization/encryption settings on s and then base64-encoded, is shorter than the maximum permissible length.

type Serializer

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

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