package module
Version: v0.0.0-...-6052ac7 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Aug 7, 2020 License: MIT Imports: 9 Imported by: 8



Build Status Go Report Card GoDoc

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


Go 1.13+


go get -u


package main

import (

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 {
    //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.
	fmt.Println(token) // 87y8da....
	fmt.Println(message) // Hello world!


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.


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.





Package branca implements the branca token specification.



This section is empty.


View Source
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")


This section is empty.


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

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL