Merge pull request #58 from gorilla/elithrar/generaterandomkey-docs
[docs] Clarify usage of GenerateRandomKey
This commit is contained in:
commit
bb1ab76598
2 changed files with 11 additions and 5 deletions
12
README.md
12
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)
|
[![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)
|
[![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.
|
cookie values.
|
||||||
|
|
||||||
Secure cookies can't be forged, because their values are validated using HMAC.
|
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
|
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.
|
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:
|
Once a SecureCookie instance is set, use it to encode a cookie value:
|
||||||
|
|
||||||
|
|
|
@ -506,6 +506,10 @@ func decode(value []byte) ([]byte, error) {
|
||||||
// GenerateRandomKey creates a random key with the given length in bytes.
|
// GenerateRandomKey creates a random key with the given length in bytes.
|
||||||
// On failure, returns nil.
|
// 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
|
// 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.
|
// it as a failure of the system random number generator, and not continue.
|
||||||
func GenerateRandomKey(length int) []byte {
|
func GenerateRandomKey(length int) []byte {
|
||||||
|
|
Loading…
Reference in a new issue