safecookie

README

safecookie

A Go library which provides simple, strong protection for cookies.

For documentation, check godoc.

Documentation

Overview

Package safecookie provides secure encoding and decoding for cookies which provides both confidentiality and authenticity against both active and passive attackers.

It does so by sealing a cookie's value with an AEAD using the cookie's name as the authenticated data. If the cookie's name or value change at all, the opening process will fail.

This provides some important guarantees:

• No one who does not have the secret key can read the cookie's plaintext value.
• No one who does not have the secret key can create a cookie which will be considered valid.
• Any cookie which has had its name or value changed will be considered invalid.

Example

package main

import (
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/codahale/safecookie"
)

func main() {
	// Create a new SafeCookie instance.
	sc, _ := safecookie.NewGCM([]byte("yellow submarine"))

	http.HandleFunc("/things", func(w http.ResponseWriter, r *http.Request) {
		// The data in the cookie.
		var data []byte

		// Extract the cookie.
		c, err := r.Cookie("session")
		if err != http.ErrNoCookie {
			// Open the cookie, if it exists.
			if data, err = sc.Open(c); err != nil {
				panic(err)
			}
		}

		// Use the cookie contents.
		log.Println(data)

		// Create a new cookie.
		c = &http.Cookie{
			Name:     "session",
			Domain:   "example.com",
			Path:     "/",
			Expires:  time.Now().AddDate(0, 0, 30),
			Secure:   true,
			HttpOnly: true,
		}

		// Seal the cookie.
		if err := sc.Seal([]byte("this is secret"), c); err != nil {
			panic(err)
		}

		// Set the cookie.
		http.SetCookie(w, c)

		// And we're done!
		fmt.Fprintln(w, "Hello, world!")
	})
}

Index

• Variables
• type SafeCookie
  • func NewGCM(key []byte) (*SafeCookie, error)
  • func (sc *SafeCookie) Open(c *http.Cookie) ([]byte, error)
  • func (sc *SafeCookie) Seal(data []byte, c *http.Cookie) error

Examples

• Package

Variables

var (
	// ErrInvalidCookie is returned if the cookie is invalid.
	ErrInvalidCookie = errors.New("invalid cookie")
)

Types

type SafeCookie

type SafeCookie struct {
	// AEAD is the Authenticated Encryption And Data algorithm to use for
	// encrypting and decrypting cookie values.
	AEAD cipher.AEAD
}

SafeCookie seals cookies and opens them.

func NewGCM

func NewGCM(key []byte) (*SafeCookie, error)

NewGCM returns a new AES-GCM-based SafeCookie instance given a 128-, 192-, or 256-bit key.

func (*SafeCookie) Open

func (sc *SafeCookie) Open(c *http.Cookie) ([]byte, error)

Open decodes the cookie's value as Base64, decrypts it (authenticating the cookie name), and returns the decrypted value. If the cookie is invalid, it returns ErrInvalidCookie.

func (*SafeCookie) Seal

func (sc *SafeCookie) Seal(data []byte, c *http.Cookie) error

Seal encrypts the data using the cookie's name as authenticated data, and sets the cookie's value to the Base64-encoded ciphertext.