codec

Documentation

Overview

Package codec provides a codec for encrypting and decrypting secure cookies. The secret keying material used for creating the codec hash and encryption keys is randomly generated, persisted to storage, and rotated regularly.

The codec storage and rotation mechanism is designed to be shared across multiple processes running on multiple hosts.

Index

• Constants
• type Codec
  • func (c *Codec) Decode(name, value string, dst interface{}) error
  • func (c *Codec) Encode(name string, value interface{}) (string, error)
  • func (c *Codec) Refresh(ctx context.Context) error
• type Serializer

Constants

const (
	// DefaultMaxAge is the default maximum age for cookies, and is used
	// if zero is provided as the maximum age.
	DefaultMaxAge = 30 * 24 * time.Hour

	// MinimumRotationPeriod is the minimum time duration between rotating secrets.
	MinimumRotationPeriod = 15 * time.Minute
)

Types

type Codec

type Codec struct {
	DB             storage.Provider
	MaxAge         time.Duration
	RotationPeriod time.Duration
	Serializer     Serializer
	SecretID       string
	// contains filtered or unexported fields
}

Codec implements the securecookie.Codec interface and can encrypt and decrypt secure cookies.

It also generates, persists and rotates the secret key material used for verifying and encrypting the secure cookies. For this reason, the storage provider (DB) field must be set.

The MaxAge field specifies the maximum age for a cookie. Any cookie older than this is invalid. If zero is passed as the maximum age, then the default maximum age is used.

The rotation period is the time duration between key rotation. If zero is passed as the rotation period, then the rotation period is deemed to be the same as the maximum age. If the rotation period is significantly smaller than the maximum age, there will be more overhead decrypting cookies, so unless there is good reason to do so, leave the rotation period at its default value.

The serializer is used to serialize the cookie contents. If not specified then the default (GOB) encoder is used.

The secret ID is used as the primary key for persisting the secret keying material to the db storage. If a blank string is supplied then a default value ("secret") is used.

func (*Codec) Decode

func (c *Codec) Decode(name, value string, dst interface{}) error

Decode implements the securecookie.Codec interface.

func (*Codec) Encode

func (c *Codec) Encode(name string, value interface{}) (string, error)

Encode implements the securecookie.Codec interface.

func (*Codec) Refresh

func (c *Codec) Refresh(ctx context.Context) error

Refresh ensures that the hash and encryption keys are up to date, rotating if necessary.

It is not mandatory to call Refresh, as the codec will update itself if necessary during each call to Encode or Decode. The difference is Refresh accepts a context and will return immediately if the context is canceled.

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. It is compatible with the securecookie.Serializer interface.