iron

README

iron-go

iron-go is a Go implementation of the Iron library. Iron generates encapsulated tokens suitable for embedding in cookies, query parameters, and HTTP headers.

$ go get github.com/kitcambridge/iron-go

Please consult the Iron security considerations before using this library.

Differences from Iron

iron-go supports the token format generated by Iron 2.1, with the following exceptions:

• The payload encryption algorithm is restricted to AES-256-CBC. iron-go does not currently support AES-128-CTR.
• Named passwords (e.g., { "id": 1, "secret": "named-password" }) are not supported. Unseal() will return an error if the encapsulated token contains a non-empty password name field.
• Separate encryption and signature passwords (e.g., { "id": 1, "encryption": "...", "integrity": "..." }) are not supported.

Usage

package main

import (
	"encoding/json"
	"github.com/kitcambridge/iron-go"
	"time"
)

type User struct {
	ID         string    `json:"id"`
	Name       string    `json:"name"`
	LastAccess time.Time `json:"lastAccess"`
}

func main() {
	alice := User{
		ID:         "1",
		Name:       "Alice",
		LastAccess: time.Now(),
	}
	password := []byte("correct horse battery staple")
	toEncrypt, err := json.Marshal(&alice)
	if err != nil {
		panic(err)
	}
	sealed, err := iron.Seal(toEncrypt, password, iron.Defaults)
	if err != nil {
		panic(err)
	}
	// `sealed` can be embedded in a cookie, query parameter, header, etc.
	unsealed, err := iron.Unseal(sealed, password, iron.Defaults)
	if err != nil {
		panic(err)
	}
	user := User{}
	if err = json.Unmarshal(unsealed, &user); err != nil {
		panic(err)
	}
	// `user == alice`.
}

API Docs

Defaults

iron.Defaults is an Options struct that specifies the default encryption and signature generation options.

Seal(data, password []byte, options Options) (sealed string, err error)

Seals an opaque data block with the specified password and options. The password is used to derive the encryption and HMAC keys, and is never included in the token. If an error is returned, sealed will always be "".

Unseal(sealed string, password []byte, options Options) (data []byte, err error)

Unseals a sealed encapsulated token with the specified password and options. If an error is returned, data will always be nil.

License

MIT.

Documentation

Overview

Package iron is a Go implementation of the Iron library.

Index

• Constants
• Variables
• func Seal(data, password []byte, options Options) (string, error)
• func Unseal(sealed string, password []byte, options Options) ([]byte, error)
• type Algorithm
• type Options

Constants

const (
	MacFormatVersion = "2"                        // The signature base string version.
	MacPrefix        = "Fe26." + MacFormatVersion // The Iron ticket prefix.
)

Ticket format constants.

const (
	AES256KeyBits    = 256 // The AES-256 encryption key size.
	IVBits           = 128 // The AES-256 IV size.
	IntegrityKeyBits = 256 // The HMAC-SHA256 key size.
)

Key and IV sizes.

Variables

var DefaultAlgorithm = Algorithm{
	SaltBits:   256,
	Iterations: 1,
}

Default algorithm options.

var Defaults = Options{
	Encryption:   DefaultAlgorithm,
	Integrity:    DefaultAlgorithm,
	ExpireIn:     0,
	AcceptWithin: 1 * time.Minute,
	LocalOffset:  0,
}

Default options.

var DefaultsIntegrity = Algorithm{
	SaltBits:   256,
	Iterations: 1,
}

Default integrity algorithm options.

Functions

func Seal

func Seal(data, password []byte, options Options) (string, error)

Seal seals a data block with the specified password and options. The password is used to derive the encryption and HMAC keys. The resulting string can be embedded in a cookie, query parameter, or header.

func Unseal

func Unseal(sealed string, password []byte, options Options) ([]byte, error)

Unseal unseals a sealed string with the specified password and options.

Types

type Algorithm

type Algorithm struct {
	SaltBits   int // The salt size. Defaults to 256 bits.
	Iterations int // The number of PBKDF2 iterations. Defaults to 1.
}

Algorithm specifies encryption and integrity algorithm options.

type Options

type Options struct {
	Encryption   Algorithm     // Payload encryption options.
	Integrity    Algorithm     // Signature generation options.
	ExpireIn     time.Duration // Ticket lifetime. If omitted or 0, the ticket will never expire.
	AcceptWithin time.Duration // The window for accepting expired tickets. Defaults to 1 minute.
	LocalOffset  time.Duration // The local clock time offset. Defaults to 0.
}

Options specifies encryption and decryption options.