iron

README

iron-go

iron-go is an implementation of Iron cookies for Go. It's fully inter-operable with the Node version. Currently it supports sealing and unsealing using a single secret key, but it should be fairly trivial to implement rotation in the future. ^{[Citation Needed]}

v := iron.New(Options{Secret: password})

// encrypt your cookie:

cookie, err := v.Seal(yourData)

// Later....

payload, err := v.Unseal(cookie)

// Use your data!

CLI

iron-go includes a simple CLI to seal and unseal cookies. Install via:

go install github.com/WatchBeam/iron-go/cmd/iron

Usage example:

➜  iron-go git:(master) iron --help
usage: iron --secret=SECRET [<flags>] <command> [<args> ...]

Flags:
      --help           Show context-sensitive help (also try --help-long and --help-man).
  -s, --secret=SECRET  Cookie encryption password
  -v, --value=VALUE    Cookie contents. If not provided, reads from stdin.

Commands:
  help [<command>...]
    Show help.

  seal
    Encrypts the cookie

  unseal
    Decrypts the cookie


➜  iron-go git:(master) pbpaste | iron unseal --secret=somethingatleast32characterslong
{"hello":"world!"}

Documentation

Index

• Variables
• type CipherFactory
• type Encryption
• type Integrity
• type Options
• type UnsealError
  • func (u UnsealError) Error() string
• type Vault
  • func New(options Options) *Vault
  • func (v *Vault) Seal(b []byte) (string, error)
  • func (v *Vault) Unseal(str string) ([]byte, error)

Variables

var (
	// AES256 implements aes-256-cbc encryption.
	AES256 = CipherFactory(func(key, iv []byte) (cipher.BlockMode, cipher.BlockMode, error) {
		block, err := aes.NewCipher(key)
		if err != nil {
			return nil, nil, err
		}

		return cipher.NewCBCEncrypter(block, iv), cipher.NewCBCDecrypter(block, iv), nil
	})
)

Types

type CipherFactory

type CipherFactory func(key, iv []byte) (encrypt cipher.BlockMode, decrypt cipher.BlockMode, err error)

CipherFactory is a function that takes a key and iv and returns and encryption and decryption block mode.

type Encryption

type Encryption struct {
	// KeyBits defines how large the signing key should be.
	KeyBits uint

	// Iteracts is the number of iterations to derive a key from the
	// secret. Set to ` by default.
	Iterations uint

	// The size of the salt (random buffer used to ensure that two identical
	// objects will generate a different encrypted result. Ignored if salt
	// set explicitly.
	SaltBits uint

	// Cipher is the cipher used to encrypt and decrypt the cookie.
	Cipher CipherFactory

	// IVBits is the number of IV bits to generate, ignored if the the IV
	// property is set explicitly.
	IVBits uint
}

An Encryption struct is contained in the Options object and used to configure how cookies are encrypted.

type Integrity

type Integrity struct {
	// KeyBits defines how large the signing key should be.
	KeyBits uint

	// Iteracts is the number of iterations to derive a key from the
	// secret. Set to ` by default.
	Iterations uint

	// The size of the salt (random buffer used to ensure that two identical
	// objects will generate a different encrypted result. Ignored if salt
	// set explicitly.
	SaltBits uint

	// Hash returns a new hasher used to digest the cookie.
	Hash func() hash.Hash
}

An Integrity struct is contained in the Options struct and describes configuration for cookie integrity verification.

type Options

type Options struct {
	// Secret key to use for encrypting/decrypting data.
	Secret []byte
	// TTL is the sealed object lifetime, infinite if zero. Defaults to zero.
	TTL time.Duration
	// Permitted clock skew for incoming expirations. Defaults to 60 seconds.
	TimestampSkew time.Duration
	// Local clock offset, defaults to zero.
	LocalTimeOffset time.Duration

	Encryption *Encryption
	Integrity  *Integrity
}

Options is passed into New() to configure the cookie options.

type UnsealError

type UnsealError struct {
	// contains filtered or unexported fields
}

UnsealError is returned from Unseal() if the message is invalid.

func (UnsealError) Error

func (u UnsealError) Error() string

Error implements error.Error

type Vault

type Vault struct {
	// contains filtered or unexported fields
}

Vault is a structure capable is sealing and unsealing Iron cookies.

func New

func New(options Options) *Vault

New creates a new Vault which can seal and unseal Iron cookies.

func (*Vault) Seal

func (v *Vault) Seal(b []byte) (string, error)

Seal encrypts and signs the byte slice into an Iron cookie.

func (*Vault) Unseal

func (v *Vault) Unseal(str string) ([]byte, error)

Unseal attempts to extract the encrypted information from the message. It takes some options, or nil to use defaults. It returns an UnsealError if the message is invalid.