branca

package module
v2.0.3 Latest Latest
Warning

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

 Go to latest Published: Jan 9, 2024 License: MIT Imports: 7 Imported by: 1

README

PkgGoDev GoReportCard Code Climate Maintainability Codebeat badge
Coverage Status 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.18+.

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.18+ workspace (instructions), then:

go get -u github.com/essentialkaos/branca/v2

Usage example

package main

import (
  "fmt"
  
  "github.com/essentialkaos/branca/v2"
)

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 benchmark command.

BrancaSuite.BenchmarkBase62Decoding             1000000   1097 ns/op   408 B/op    7 allocs/op
BrancaSuite.BenchmarkBase62Encoding             1000000   1745 ns/op   512 B/op    6 allocs/op
BrancaSuite.BenchmarkBrancaDecoding             5000000    375 ns/op    48 B/op    2 allocs/op
BrancaSuite.BenchmarkBrancaDecodingFromString   1000000   1523 ns/op   456 B/op    9 allocs/op
BrancaSuite.BenchmarkBrancaEncoding             1000000   1781 ns/op   152 B/op    4 allocs/op
BrancaSuite.BenchmarkBrancaEncodingToString      500000   4072 ns/op   664 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 which 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 Base62 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 []byte

Branca is byte slice with key data

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:

type Token 

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

Token is branca token

func (*Token) IsExpired 

func (t *Token) IsExpired(ttl uint32) 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", token.IsExpired(0))

Output:

Token expired: true

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.