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.