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.

Requirements

Go 1.13+

Install

go get -u github.com/hako/branca

Example

package main

import (
	"fmt"
	"github.com/hako/branca"
)

func main() {
	b := branca.NewBranca("supersecretkeyyoushouldnotcommit") // This key must be exactly 32 bytes long.
	
	// Encode String to Branca Token.
	token, err := b.EncodeToString("Hello world!")
	if err != nil {
		fmt.Println(err)
	}
				
    //b.SetTTL(3600) // Uncomment this to set an expiration (or ttl) of the token (in seconds).
    //token = "87y8daMzSkn7PA7JsvrTT0JUq1OhCjw9K8w2eyY99DKru9FrVKMfeXWW8yB42C7u0I6jNhOdL5ZqL" // This token will be not allowed if a ttl is set.
	
	// Decode Branca Token.
	message, err := b.DecodeToString(token)
	if err != nil {
		fmt.Println(err) // token is expired.
		return
	}
	fmt.Println(token) // 87y8da....
	fmt.Println(message) // Hello world!
}

Todo

Here are a few things that need to be done:

• Remove cgo dependencies.
• Move to a pure XChaCha20 algorithm in Go.
• Add more tests than just acceptance tests.
• Increase test coverage.
• Additional Methods. (Encode, Decode []byte)
• Performance benchmarks.
• More comments, examples and documentation.

Contributing

Contributions are welcome! Fork this repo and add your changes and submit a PR.

If you would like to fix a bug, add a feature or provide feedback you can do so in the issues section.

You can run tests by runnning go test. Running go test; go vet; golint is recommended.

License

MIT

Documentation

Overview

Package branca implements the branca token specification.

Index

• Variables
• type Branca
  • func NewBranca(key string) (b *Branca)
  • func (b *Branca) DecodeToString(data string) (string, error)
  • func (b *Branca) EncodeToString(data string) (string, error)
  • func (b *Branca) SetTTL(ttl uint32)
• type ErrExpiredToken
  • func (e *ErrExpiredToken) Error() string

Variables

var (
	// ErrInvalidToken indicates an invalid token.
	ErrInvalidToken = errors.New("invalid base62 token")
	// ErrInvalidTokenVersion indicates an invalid token version.
	ErrInvalidTokenVersion = errors.New("invalid token version")
	// ErrBadKeyLength indicates a bad key length.
	ErrBadKeyLength = errors.New("bad key length")
)

Types

type Branca

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

Branca holds a key of exactly 32 bytes. The nonce and timestamp are used for acceptance tests.

func NewBranca

func NewBranca(key string) (b *Branca)

NewBranca creates a *Branca struct.

func (*Branca) DecodeToString

func (b *Branca) DecodeToString(data string) (string, error)

DecodeToString decodes the data.

func (*Branca) EncodeToString

func (b *Branca) EncodeToString(data string) (string, error)

EncodeToString encodes the data matching the format: Version (byte) || Timestamp ([4]byte) || Nonce ([24]byte) || Ciphertext ([]byte) || Tag ([16]byte)

func (*Branca) SetTTL

func (b *Branca) SetTTL(ttl uint32)

SetTTL sets a Time To Live on the token for valid tokens.

type ErrExpiredToken

type ErrExpiredToken struct {
	// Time is the token expiration time.
	Time time.Time
}

ErrExpiredToken indicates an expired token.

func (*ErrExpiredToken) Error

func (e *ErrExpiredToken) Error() string