Repository files navigation

securecookie encodes and decodes authenticated and optionally encryptedcookie values.

Secure cookies can't be forged, because their values are validated using HMAC.When encrypted, the content is also inaccessible to malicious eyes. It is stillrecommended that sensitive data not be stored in cookies, and that HTTPS be usedto prevent cookiereplay attacks.

To use it, first create a new SecureCookie instance:

// Hash keys should be at least 32 bytes longvarhashKey= []byte("very-secret")// Block keys should be 16 bytes (AES-128) or 32 bytes (AES-256) long.// Shorter keys may weaken the encryption used.varblockKey= []byte("a-lot-secret")vars=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 nilto not use encryption. If set, the length must correspond to the block sizeof the encryption algorithm. For AES, used by default, valid lengths are16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

Strong keys can be created using the convenience functionGenerateRandomKey(). Note that keys created usingGenerateRandomKey() are notautomatically persisted. New keys will be created when the application isrestarted, and previously issued cookies will not be able to be decoded.

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

funcSetCookieHandler(w http.ResponseWriter,r*http.Request) {value:=map[string]string{"foo":"bar",}ifencoded,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)}}

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

funcReadCookieHandler(w http.ResponseWriter,r*http.Request) {ifcookie,err:=r.Cookie("cookie-name");err==nil {value:=make(map[string]string)iferr=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 thatcan be encoded usingencoding/gob. To store custom types, they must beregistered first using gob.Register(). For basic types this is not needed;it works out of the box. An optional JSON encoder that usesencoding/json isavailable for types compatible with JSON.

Rotating keys is an important part of any security strategy. TheEncodeMulti andDecodeMulti functions allow for multiple keys to be rotated in and out.For example, let's take a system that stores keys in a map:

// keys stored in a map will not be persisted between restarts// a more persistent storage should be considered for production applications.varcookies=map[string]*securecookie.SecureCookie{"previous":securecookie.New(securecookie.GenerateRandomKey(64),securecookie.GenerateRandomKey(32),),"current":securecookie.New(securecookie.GenerateRandomKey(64),securecookie.GenerateRandomKey(32),),}

Using the current key to encode new cookies:

funcSetCookieHandler(w http.ResponseWriter,r*http.Request) {value:=map[string]string{"foo":"bar",}ifencoded,err:=securecookie.EncodeMulti("cookie-name",value,cookies["current"]);err==nil {cookie:=&http.Cookie{Name:"cookie-name",Value:encoded,Path:"/",}http.SetCookie(w,cookie)}}

Later, decode cookies. Check against all valid keys:

funcReadCookieHandler(w http.ResponseWriter,r*http.Request) {ifcookie,err:=r.Cookie("cookie-name");err==nil {value:=make(map[string]string)err=securecookie.DecodeMulti("cookie-name",cookie.Value,&value,cookies["current"],cookies["previous"])iferr==nil {fmt.Fprintf(w,"The value of foo is %q",value["foo"])}}}

Rotate the keys. This strategy allows previously issued cookies to be valid until the next rotation:

funcRotate(newCookie*securecookie.SecureCookie) {cookies["previous"]=cookies["current"]cookies["current"]=newCookie}

BSD licensed. See the LICENSE file for details.