gorilla/securecookie

To rotate keys without invalidating existing cookies, use securecookie.EncodeMulti and securecookie.DecodeMulti. This allows you to maintain a set of valid keys (e.g., a 'current' key and a 'previous' key).

1. Encoding: Use securecookie.EncodeMulti(name, value, currentInstance) to ensure new cookies are always signed/encrypted with the latest key.
2. Decoding: Use securecookie.DecodeMulti(name, encodedValue, &target, currentInstance, previousInstance...) to check the incoming cookie against all currently valid keys.
3. Rotation Strategy: When rotating, move the current instance to previous and set a new instance as current.

// 1. Setup multiple instances for rotation
var cookies = map[string]*securecookie.SecureCookie{
	"previous": securecookie.New(
		securecookie.GenerateRandomKey(64),
		securecookie.GenerateRandomKey(32),
	),
	"current": securecookie.New(
		securecookie.GenerateRandomKey(64),
		securecookie.GenerateRandomKey(32),
	),
}

// 2. Encode using the current key
// securecookie.EncodeMulti("cookie-name", value, cookies["current"])

// 3. Decode against all valid keys
// err = securecookie.DecodeMulti("cookie-name", cookie.Value, &value, cookies["current"], cookies["previous"])

// 4. Rotate
func Rotate(newCookie *securecookie.SecureCookie) {
	cookies["previous"] = cookies["current"]
	cookies["current"] = newCookie
}

To use securecookie, create a new instance using securecookie.New(hashKey, blockKey).

• hashKey: Required. Used to authenticate the cookie value using HMAC. It is recommended to use a key with 32 or 64 bytes.
• blockKey: Optional. Used to encrypt the cookie value. Set to nil to disable encryption. If provided, the length must correspond to the block size of the encryption algorithm (AES). For AES, valid lengths are 16, 24, or 32 bytes (for AES-128, AES-192, or AES-256 respectively).

You can use securecookie.GenerateRandomKey() to create strong keys, but note that these are not automatically persisted; restarting the application with new random keys will invalidate previously issued cookies.

// Hash keys should be at least 32 bytes long
var hashKey = []byte("very-secret")
// Block keys should be 16 bytes (AES-128) or 32 bytes (AES-256) long.
var blockKey = []byte("a-lot-secret")
var s = securecookie.New(hashKey, blockKey)

Once a SecureCookie instance is initialized, you can encode and decode values.

Encoding

Use s.Encode(name, value) to transform a value into an encoded string. The value must be compatible with encoding/gob. For custom types, you must register them using gob.Register() first. Basic types work out of the box.

Decoding

Use s.Decode(name, encodedValue, &target) to validate and decode an encoded string into a target variable. The target must be a pointer to the type used during encoding.

Note: An optional JSON encoder using encoding/json is available for types compatible with JSON.

// Encoding example
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:  "/",
			Secure: true,
			HttpOnly: true,
		}
		http.SetCookie(w, cookie)
	}
}

// Decoding example
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"])
		}
	}
}

To support key rotation (allowing old cookies to be decoded while issuing new ones with new keys), use EncodeMulti and DecodeMulti with a slice of Codec objects.

• EncodeMulti(name, value, codecs...): Tries codecs in order until one succeeds.
• DecodeMulti(name, value, dst, codecs...): Tries codecs in order until one succeeds.
• CodecsFromPairs(keyPairs...): A helper to create a slice of Codec instances from alternating hashKey and blockKey pairs. The last pair can be just a hashKey (no encryption).

// Create codecs for rotation
codecs := securecookie.CodecsFromPairs(
    []byte("new-hash-key"),
    []byte("new-block-key"),
    []byte("old-hash-key"),
    []byte("old-block-key"),
)

// Encode using the newest codec
encoded, err := securecookie.EncodeMulti("session", data, codecs...)

// Decode using all codecs (will try old ones if new ones fail)
err := securecookie.DecodeMulti("session", encoded, &dst, codecs...)