Documentation
¶
Overview ¶
Package cookies contains helper functions for setting and retrieving cookies, including signed and encrypted ones.
Cookie values are encoded and decoded using encoding/gob, so you must register any non-basic type that you want to store in a cookie, using encoding/gob.Register.
Signed cookies are signed using HMAC-SHA1. Encrypted cookies are encrypted with AES and then signed with HMAC-SHA1.
Index ¶
- Constants
- Variables
- func SetDefaults(defaults *Options)
- type Cookies
- func (c *Cookies) Delete(name string)
- func (c *Cookies) Get(name string, out interface{}) error
- func (c *Cookies) GetCookie(name string) (*http.Cookie, error)
- func (c *Cookies) GetEncrypted(name string, out interface{}) error
- func (c *Cookies) GetSecure(name string, out interface{}) error
- func (c *Cookies) Has(name string) bool
- func (c *Cookies) Set(name string, value interface{}) error
- func (c *Cookies) SetCookie(cookie *http.Cookie)
- func (c *Cookies) SetEncrypted(name string, value interface{}) error
- func (c *Cookies) SetEncryptedOpts(name string, value interface{}, o *Options) error
- func (c *Cookies) SetOpts(name string, value interface{}, o *Options) error
- func (c *Cookies) SetSecure(name string, value interface{}) error
- func (c *Cookies) SetSecureOpts(name string, value interface{}, o *Options) error
- type Options
Constants ¶
const (
// Maximum cookie size. See section 6.3 at http://www.ietf.org/rfc/rfc2109.txt.
MaxSize = 4096
)
Variables ¶
var ( // Cookie is too big. See MaxSize. ErrCookieTooBig = errors.New("cookie is too big (maximum size is 4096 bytes)") // Tried to use signed or encrypted cookies without a Signer. ErrNoSigner = errors.New("no signer specified") // Tried to use encrypted cookies without an Encrypter. ErrNoEncrypter = errors.New("no encrypter specified") // Maximum representable UNIX time with a signed 32 bit integer. This // means that cookies won't be really permanent, but they will expire // on January 19th 2038. I don't know about you, but I hope to be around // by that time, so hopefully I'll find a solution for this issue in the // next few years. See http://en.wikipedia.org/wiki/Year_2038_problem for // more information. Permanent = time.Unix(2147483647, 0).UTC() )
Functions ¶
func SetDefaults ¶
func SetDefaults(defaults *Options)
SetDefaults changes the default cookie options.
Types ¶
type Cookies ¶
type Cookies struct {
// contains filtered or unexported fields
}
Cookies includes conveniency functions for setting and retrieving cookies. Use New() or gondola/app.Context.Cookies to create a Cookies instance.
func New ¶
func New(r *http.Request, w http.ResponseWriter, c *codec.Codec, signer *cryptoutil.Signer, encrypter *cryptoutil.Encrypter, defaults *Options) *Cookies
New returns a new *Cookies object, which will read cookies from the given http.Request, and write them to the given http.ResponseWriter. Note that users will probably want to use gondola/app.Context.Cookies rather than this function to create a Cookies instance.
The signer parameter is used for secure (signed) cookies, while encrypter is also used for encrypted cookies. If you don't use secure nor encrypted cookies, you might pass nil both parameters. If you only need signed cookies, you might pass nil for encrypter.
The default parameter specifies the default Options for the funcions which only take a name and a value. If you pass nil, Defaults will be used.
func (*Cookies) Get ¶
Get uses the cookie value with the given name to populate the out argument. If the types don't match (e.g. the cookie was set to a string and you try to get an int), an error will be returned.
func (*Cookies) GetEncrypted ¶
GetEncrypted works like Get, but for cookies set with SetEncrypted(). See SetEncrypted() for the guarantees made about the cookie value.
func (*Cookies) GetSecure ¶
GetSecure works like Get, but for cookies set with SetSecure(). See SetSecure() for the guarantees made about the cookie value.
func (*Cookies) Set ¶
Set sets the cookie with the given name and encodes the given value using the codec provided in New. If the cookie size if bigger than 4096 bytes, it returns ErrCookieTooBig.
The options used for the cookie are the default ones provided in New(), which will usually come from gondola/app.App.CookieOptions. If you need to specify different options, use SetOpts().
func (*Cookies) SetEncrypted ¶
SetEncrypted sets a tamper-proof and encrypted cookie. The value is first encrypted using *cryptoutil.Encrypter and the signed using *cryptoutil.Signer. By default, these use AES and HMAC-SHA1 respectivelly. The user will not be able to tamper with the cookie value nor reveal its contents.
If you haven't set a Signer (usually set automatically for you, derived from the gondola/app.App.Secret field) and an Encrypter (usually set automatically too, from gondola/app.App.EncryptionKey), this function will return an error.
The options used for the cookie are the default ones provided in New(), which will usually come from gondola/app.App.CookieOptions. If you need to specify different options, use SetEncryptedOpts().
func (*Cookies) SetEncryptedOpts ¶
SetEncryptedOpts works like SetEncrypted(), but accepts and Options parameter.
func (*Cookies) SetSecure ¶
SetSecure sets a tamper-proof cookie, using the a *cryptoutil.Signer to sign its value. By default, it uses HMAC-SHA1. The user will be able to see the value of the cookie, but he will not be able to manipulate it. If you also require the value to be protected from being revealed to the user, use SetEncrypted().
If you haven't set a Signer (usually set automatically for you, derived from the gondola/app.App.Secret field), this function will return an error.
The options used for the cookie are the default ones provided in New(), which will usually come from gondola/app.App.CookieOptions. If you need to specify different options, use SetSecureOpts().
type Options ¶
type Options struct {
Path string
Domain string
Expires time.Time
MaxAge int
Secure bool
HttpOnly bool
}
Options specify the default cookie Options used when setting a Cookie only by its name and value, like in Cookies.Set(), Cookies.SetSecure(), and Cookies.SetEncrypted().
For more information about the cookie fields, see net/http.Cookie.
Source Files