branca

README

branca

Branca is a secure alternative to JWT, This implementation is written in pure Go (no cgo dependencies) and implements the branca token specification.

It was originally forked from github.com/hako/branca and the API and implementation fairly extensively modified. Specifically:

• the token payload is now []byte not string.
• the client is responsible for checking timestamp expiry, which simplifies the API and makes it possible to use a different expiry duration based on the payload contents.
• it's possible for external code to choose the nonce and timestamp, which is useful for tests.
• the external basex dependency has been removed.
• encoding a token no longer returns an error.
• the base62 wrapping is now optional, making it efficient to fold a token into some other binary format without incurring double-encoding cost.
• less work is done for each encoding and decoding (the encrypter and the base62 encoder are created only once)

Requirements

Go 1.10 and beyond.

Install

go get -u github.com/CanonicalLtd/branca

See the godoc for examples and more information on the API.

Documentation

Overview

Package branca implements the branca token specification.

See https://github.com/tuupola/branca-spec for details.

Although the standard specifies that tokens are base62-encoded, this package also provides access to the underlying data bytes so that they can be efficiently included in other byte-oriented formats.

Index

• func Base62(data []byte) string
• type Branca
  • func New(key [32]byte) *Branca
  • func (b *Branca) Decode(token string) ([]byte, time.Time, error)
  • func (b *Branca) DecodeRaw(data []byte) ([]byte, time.Time, error)
  • func (b *Branca) Encode(payload []byte) string
  • func (b *Branca) EncodeToRaw(payload []byte) []byte
  • func (b *Branca) EncodeToRawAtTime(payload []byte, nonce [24]byte, t time.Time) []byte

Functions

func Base62

func Base62(data []byte) string

Base62 returns the base62 encoding of the given data, as specified by the Branca standard.

By default, nonce values are generated

Types

type Branca

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

Branca encodes and decodes Branca tokens.

func New

func New(key [32]byte) *Branca

New returns a new Codec that encodes and decodes Branca tokens with the given 256-bit key.

func (*Branca) Decode

func (b *Branca) Decode(token string) ([]byte, time.Time, error)

Decode decodes a Branca token. It returns the decrypted payload and the associated timestamp of the token.

func (*Branca) DecodeRaw

func (b *Branca) DecodeRaw(data []byte) ([]byte, time.Time, error)

DecodeRaw is like Decode except that it decodes a Branca token that is not base62 encoded.

func (*Branca) Encode

func (b *Branca) Encode(payload []byte) string

Encode encodes the given payload with the key that b was created with.

func (*Branca) EncodeToRaw

func (b *Branca) EncodeToRaw(payload []byte) []byte

EncodeToRaw is like Encode except that it returns the underlying encoded token instead of returning it base62-encoded.

func (*Branca) EncodeToRawAtTime

func (b *Branca) EncodeToRawAtTime(payload []byte, nonce [24]byte, t time.Time) []byte

EncodeToRawAtTime is like EncodeToRaw except that the created token will use the given timestamp and nonce.

Note that the Base62 function can be used to convert the returned value to a valid Branca token.