README.md (2901B)
1 securecookie 2 ============ 3 [](https://godoc.org/github.com/gorilla/securecookie) [](https://travis-ci.org/gorilla/securecookie) 4 [](https://sourcegraph.com/github.com/gorilla/securecookie?badge) 5 6 7 securecookie encodes and decodes authenticated and optionally encrypted 8 cookie values. 9 10 Secure cookies can't be forged, because their values are validated using HMAC. 11 When encrypted, the content is also inaccessible to malicious eyes. It is still 12 recommended that sensitive data not be stored in cookies, and that HTTPS be used 13 to prevent cookie [replay attacks](https://en.wikipedia.org/wiki/Replay_attack). 14 15 ## Examples 16 17 To use it, first create a new SecureCookie instance: 18 19 ```go 20 // Hash keys should be at least 32 bytes long 21 var hashKey = []byte("very-secret") 22 // Block keys should be 16 bytes (AES-128) or 32 bytes (AES-256) long. 23 // Shorter keys may weaken the encryption used. 24 var blockKey = []byte("a-lot-secret") 25 var s = securecookie.New(hashKey, blockKey) 26 ``` 27 28 The hashKey is required, used to authenticate the cookie value using HMAC. 29 It is recommended to use a key with 32 or 64 bytes. 30 31 The blockKey is optional, used to encrypt the cookie value -- set it to nil 32 to not use encryption. If set, the length must correspond to the block size 33 of the encryption algorithm. For AES, used by default, valid lengths are 34 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256. 35 36 Strong keys can be created using the convenience function GenerateRandomKey(). 37 38 Once a SecureCookie instance is set, use it to encode a cookie value: 39 40 ```go 41 func SetCookieHandler(w http.ResponseWriter, r *http.Request) { 42 value := map[string]string{ 43 "foo": "bar", 44 } 45 if encoded, err := s.Encode("cookie-name", value); err == nil { 46 cookie := &http.Cookie{ 47 Name: "cookie-name", 48 Value: encoded, 49 Path: "/", 50 Secure: true, 51 HttpOnly: true, 52 } 53 http.SetCookie(w, cookie) 54 } 55 } 56 ``` 57 58 Later, use the same SecureCookie instance to decode and validate a cookie 59 value: 60 61 ```go 62 func ReadCookieHandler(w http.ResponseWriter, r *http.Request) { 63 if cookie, err := r.Cookie("cookie-name"); err == nil { 64 value := make(map[string]string) 65 if err = s2.Decode("cookie-name", cookie.Value, &value); err == nil { 66 fmt.Fprintf(w, "The value of foo is %q", value["foo"]) 67 } 68 } 69 } 70 ``` 71 72 We stored a map[string]string, but secure cookies can hold any value that 73 can be encoded using `encoding/gob`. To store custom types, they must be 74 registered first using gob.Register(). For basic types this is not needed; 75 it works out of the box. An optional JSON encoder that uses `encoding/json` is 76 available for types compatible with JSON. 77 78 ## License 79 80 BSD licensed. See the LICENSE file for details.