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-godoes 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 ¶
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 ¶
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.
Source Files