branca

package module
v1.3.1 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2021 License: MIT Imports: 7 Imported by: 0

README

PkgGoDev GoReportCard Coverage Status Codebeat badge GitHub Actions CI Status GitHub Actions CodeQL Status

Installation • Usage example • Benchmarks • Build Status • License


branca.go is branca token specification implementation for Golang 1.15+.

Features and benefits:

  • Pure Go implementation;
  • No third-party dependencies at all;
  • 100% code coverage;
  • Fuzz tests.

Installation

Make sure you have a working Go 1.15+ workspace (instructions), then:

go get pkg.re/essentialkaos/branca.v1

For update to latest stable release, do:

go get -u pkg.re/essentialkaos/branca.v1

Usage example

package main

import (
  "fmt"
  
  "pkg.re/essentialkaos/branca.v1"
)

func main() {
  key := "abcd1234abcd1234abcd1234abcd1234"
  brc, err := branca.NewBranca([]byte(key))

  if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  payload := "MySuperSecretData"
  token, err := brc.EncodeToString([]byte(payload))

   if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
  }

  fmt.Printf("Token: %s\n", token)
}

Benchmarks

You can run benchmarks by yourself using make bench command.

BrancaSuite.BenchmarkBase62Decoding            1000000     1046 ns/op      384 B/op      6 allocs/op
BrancaSuite.BenchmarkBase62Encoding            1000000     1913 ns/op      512 B/op      6 allocs/op
BrancaSuite.BenchmarkBrancaDecoding            5000000      373 ns/op       48 B/op      2 allocs/op
BrancaSuite.BenchmarkBrancaDecodingFromString  1000000     1463 ns/op      432 B/op      8 allocs/op
BrancaSuite.BenchmarkBrancaEncoding            1000000     1677 ns/op      208 B/op      4 allocs/op
BrancaSuite.BenchmarkBrancaEncodingToString     500000     3977 ns/op      720 B/op     10 allocs/op

Build Status

Branch Status
master CI
develop CI

License

MIT

Documentation

Overview

Package branca implements branca token specification

Index

Examples

Constants

View Source 
const (
	// KEY_SIZE is Branca key is always 32 bytes (i.e 256 bit)
	KEY_SIZE = 32

	// MIN_TOKEN_SIZE is minimal token size is 45 bytes (with empty payload)
	MIN_TOKEN_SIZE = 45
)
View Source 
const (
	// VERSION_SIZE is Branca version size (1B)
	VERSION_SIZE = 1

	// TIMESTAMP_SIZE is Branca timestamp size (4B)
	TIMESTAMP_SIZE = 4

	// NONCE_SIZE is Branca nonce size (24B)
	NONCE_SIZE = 24

	// HEADER_SIZE is Branca header size (29B)
	HEADER_SIZE = VERSION_SIZE + TIMESTAMP_SIZE + NONCE_SIZE
)

Variables

View Source 
var (
	// ErrInvalidToken means that given data doesn't look like branca token
	ErrInvalidToken = errors.New("Token is invalid")

	// ErrInvalidVersion means that token has an unsupported version
	ErrInvalidVersion = errors.New("Token has invalid version")

	// ErrBadKeyLength is returned if key not equal to 32 bytes
	ErrBadKeyLength = errors.New("Key must be 32 bytes long")
)
View Source 
var ErrNonBase62Char = errors.New("Got non Base62 character")

ErrNonBase62Char means that given string contains symbol which is not a part of the Base62 alphabet

Functions

func DecodeBase62 

func DecodeBase62(src string) ([]byte, error)

DecodeBase62 decodes bases62 encoded string to byte slice

func EncodeBase62 

func EncodeBase62(src []byte) string

EncodeBase62 encodes bytes slice to base62 encoded string

Types

type Branca 

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

Branca is branca struct

func NewBranca 

func NewBranca(key []byte) (*Branca, error)

NewBranca creates new branca struct

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

payload := "MySecretData"
token, err := brc.EncodeToString([]byte(payload))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Token: %s\n", token)

Output:

func (*Branca) Decode 

func (b *Branca) Decode(token []byte) (Token, error)

Decode extract payload from branca token

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

data := []byte{186, 92, 40, 2, 172, 169, 93, 187, 60, 216, 139, 79, 89,
	25, 68, 191, 235, 113, 237, 55, 133, 168, 158, 255, 160, 36, 98, 222,
	110, 242, 182, 153, 143, 206, 44, 141, 59, 46, 81, 124, 114, 25, 117,
	85, 156, 170, 204, 175, 164, 57, 5, 235, 56, 1, 115, 5, 222}

token, err := brc.Decode(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Payload: %s\n", string(token.Payload()))

Output:

Payload: MySecretData

func (*Branca) DecodeString 

func (b *Branca) DecodeString(token string) (Token, error)

DecodeString extract payload from Base62 encoded token

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

data := "87yoI2tNmtPGYxQMYExUw6Yn0zRJccwIiMZxAQ7OBNoLl2P2stmAfD1BLvHOIdwmjGIWxnLrNmHLG"
token, err := brc.DecodeString(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Payload: %s\n", string(token.Payload()))

Output:

Payload: MySecretData

func (*Branca) Encode 

func (b *Branca) Encode(payload []byte) ([]byte, error)

Encode encodes payload to branca token

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

payload := "MySecretData"
token, err := brc.Encode([]byte(payload))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Token: %v\n", token)

Output:

func (*Branca) EncodeToString 

func (b *Branca) EncodeToString(payload []byte) (string, error)

EncodeToString create Base62 encoded token with given payload

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

payload := "MySecretData"
token, err := brc.EncodeToString([]byte(payload))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Token: %s\n", token)

Output:

func (*Branca) IsExpired 

func (b *Branca) IsExpired(t Token) bool

IsExpired returns true if given token is expired

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

data := "87yoI2tNmtPGYxQMYExUw6Yn0zRJccwIiMZxAQ7OBNoLl2P2stmAfD1BLvHOIdwmjGIWxnLrNmHLG"
token, err := brc.DecodeString(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Token expired: %t", brc.IsExpired(token))

Output:

Token expired: true

func (*Branca) SetTTL 

func (b *Branca) SetTTL(ttl uint32)

SetTTL sets Time To Live

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

// Set TTL for 1 minute
brc.SetTTL(60)

Output:

type Token 

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

Token is branca token

func (*Token) Payload 

func (t *Token) Payload() []byte

Payload returns token payload

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

data := "87yoI2tNmtPGYxQMYExUw6Yn0zRJccwIiMZxAQ7OBNoLl2P2stmAfD1BLvHOIdwmjGIWxnLrNmHLG"
token, err := brc.DecodeString(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Payload: %s\n", string(token.Payload()))

Output:

Payload: MySecretData

func (*Token) Timestamp 

func (t *Token) Timestamp() time.Time

Timestamp returns token timestamp

Example 
key := "mysupppadupppasecretkeyforbranca"
brc, err := NewBranca([]byte(key))

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

data := "87yoI2tNmtPGYxQMYExUw6Yn0zRJccwIiMZxAQ7OBNoLl2P2stmAfD1BLvHOIdwmjGIWxnLrNmHLG"
token, err := brc.DecodeString(data)

if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Timestamp: %v\n", token.Timestamp())

Output:

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.