cookies

In general, cookies and other means of adding statefulness to HTTP requests is to be avoided. This because it causes problems with caching. If there the need for state cannot be avoided using for example GET parameters, we often find ourselves reaching for the Cookie mechanism. Surfer provides two means by which to set cookies.

Two levels of security should be used for keeping cookies. Public, where the cookies way be freely modified and changed by the user without any validation of any kind. Private the cookie value is trusted, that is we can be sure that it hasn't been changed. It is up to the user to choose systems for the two levels. Oftentimes plain HTTP cookies are enough for public data. For private data a signing and encryption scheme is used.

For settings coookies surfer provides two methods:

SetCookie(name string, value string, expires int64)

SetSecureCookie(name string, value string, expires int64) (error)

The set secure cookie method signs the cookie prior to setting it. Other than that the methods are functionally the same. Note however that the secure cookie variant may return an error value.

For getting the values of cookies the following methods are used:

GetCookie(name string) (string)

GetSecureCookie(name string) (string, error)

Once again, the methods are similar except that get secure cookie decodes the cookie. In addition, as with set secure cookie, the get secure cookie method also returns an error if unable to decode the cookie. In this case though an error may indicate that the client tried to spoof the cookie, that it was corrupted or a configuration problem. In this case always assume that data that fails validation is untrusted.

Initialization

To use the SecureCookie system you need to initialise Handler.SecCookie in your Prepare method. You need to provide a at least a signing key, and optionally a key for encrypting the key.