From 1aeabd195284b0b9e2be63137c303377d84d7eb8 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Thu, 13 Sep 2018 10:58:55 -0700 Subject: [PATCH 1/2] [docs] Clarify usage of GenerateRandomKey --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index aa7bd1a..a914d4a 100644 --- a/README.md +++ b/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: From 11123820fba8bbc52739252fb69b5e421fcbea3a Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Thu, 13 Sep 2018 11:41:34 -0700 Subject: [PATCH 2/2] [docs] Add note RE: persistence to GenerateRandomKey --- securecookie.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/securecookie.go b/securecookie.go index 61af390..a34f851 100644 --- a/securecookie.go +++ b/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 {