docs: Include an example for using DecodeMulti in the Readme (#69)
* Include an example for using DecodeMulti in the Readme * Put warning in as code comment
This commit is contained in:
parent
86450627d8
commit
61b4ad17eb
1 changed files with 58 additions and 0 deletions
58
README.md
58
README.md
|
@ -77,6 +77,64 @@ registered first using gob.Register(). For basic types this is not needed;
|
|||
it works out of the box. An optional JSON encoder that uses `encoding/json` is
|
||||
available for types compatible with JSON.
|
||||
|
||||
### Key Rotation
|
||||
Rotating keys is an important part of any security strategy. The `EncodeMulti` and
|
||||
`DecodeMulti` functions allow for multiple keys to be rotated in and out.
|
||||
For example, let's take a system that stores keys in a map:
|
||||
|
||||
```go
|
||||
// keys stored in a map will not be persisted between restarts
|
||||
// a more persistent storage should be considered for production applications.
|
||||
var cookies = 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:
|
||||
```go
|
||||
func SetCookieHandler(w http.ResponseWriter, r *http.Request) {
|
||||
value := map[string]string{
|
||||
"foo": "bar",
|
||||
}
|
||||
if encoded, 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:
|
||||
```go
|
||||
func ReadCookieHandler(w http.ResponseWriter, r *http.Request) {
|
||||
if cookie, err := r.Cookie("cookie-name"); err == nil {
|
||||
value := make(map[string]string)
|
||||
err = securecookie.DecodeMulti("cookie-name", cookie.Value, &value, cookies["current"], cookies["previous"])
|
||||
if err == 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:
|
||||
```go
|
||||
func Rotate(newCookie *securecookie.SecureCookie) {
|
||||
cookies["previous"] = cookies["current"]
|
||||
cookies["current"] = newCookie
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
BSD licensed. See the LICENSE file for details.
|
||||
|
|
Loading…
Reference in a new issue