Merge pull request #58 from gorilla/elithrar/generaterandomkey-docs

[docs] Clarify usage of GenerateRandomKey

README.md

@@ -1,10 +1,9 @@
-securecookie
-============
+# securecookie
+
 [![GoDoc](https://godoc.org/github.com/gorilla/securecookie?status.svg)](https://godoc.org/github.com/gorilla/securecookie) [![Build Status](https://travis-ci.org/gorilla/securecookie.png?branch=master)](https://travis-ci.org/gorilla/securecookie)
 [![Sourcegraph](https://sourcegraph.com/github.com/gorilla/securecookie/-/badge.svg)](https://sourcegraph.com/github.com/gorilla/securecookie?badge)
 
-
-securecookie encodes and decodes authenticated and optionally encrypted 
+securecookie encodes and decodes authenticated and optionally encrypted
 cookie values.
 
 Secure cookies can't be forged, because their values are validated using HMAC.
@@ -33,7 +32,10 @@ to not use encryption. If set, the length must correspond to the block size
 of the encryption algorithm. For AES, used by default, valid lengths are
 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.
 
-Strong keys can be created using the convenience function GenerateRandomKey().
+Strong keys can be created using the convenience function
+`GenerateRandomKey()`. Note that keys created using `GenerateRandomKey()` are not
+automatically persisted. New keys will be created when the application is
+restarted, and previously issued cookies will not be able to be decoded.
 
 Once a SecureCookie instance is set, use it to encode a cookie value:
 

securecookie.go

@@ -506,6 +506,10 @@ func decode(value []byte) ([]byte, error) {
 // GenerateRandomKey creates a random key with the given length in bytes.
 // On failure, returns nil.
 //
+// Note that keys created using `GenerateRandomKey()` are not automatically
+// persisted. New keys will be created when the application is restarted, and
+// previously issued cookies will not be able to be decoded.
+//
 // Callers should explicitly check for the possibility of a nil return, treat
 // it as a failure of the system random number generator, and not continue.
 func GenerateRandomKey(length int) []byte {