goalone

README

It's dangerous to go-alone! Take this.

go-alone is a Go package that provides

• Methods to create and verify MAC signatures of data
• Ability to add timestamps to signed tokens and use custom epoch if needed.
• BLAKE2b signatures and Base58 time encoding provides outstanding performance and security.
• A very simple to use API with good documentation and 100% test coverage.
• Various helper methods for parsing tokens

For more information, please read the wiki

For help with this package or general Go discussion, please join the Discord Gophers chat server.

For a fast and easy to use snowflake ID library, check out this

Getting Started

This assumes you already have a working Go environment, if not please see this page first.

Installing

go get github.com/bwmarrin/go-alone

Usage

Here's a basic example below. There is also an example program in the example folder that demonstrates a few more ways of using Go-Alone. You can read the API documentation on GoDoc.

package main

import (
	"github.com/bwmarrin/go-alone"
)

func main() {

	// This secret is used as the hash key for the signer.
	var secret = []byte("It's a secret to everybody")

	// This data is what we will be signing below.
	var data = []byte("It's dangerous to go alone! Take this.")

	// Create a new Signer using our secret
	s := goalone.New(secret)

	// Sign and return a token in the form of `data.signature`
	token := s.Sign(data)

	// Unsign the token to verify it - if successful the data portion of the
	// token is returned.  If unsuccessful then d will be nil, and an error
	// is returned.
	d, err := s.Unsign(token)
	if err != nil {
		// signature is not valid. Token was tampered with, forged, or maybe it's
		// not even a token at all! Either way, it's not safe to use it.
	} else {
		// signature is valid, it is safe to use the data
		println(string(d))
	}
}

Performance / Testing

To run the tests and benchmarks, use the following command.

go test -bench=. -v

Documentation

Index

• Variables
• func Epoch(e int64) func(*Sword)
• func Timestamp(s *Sword)
• type Sword
  • func New(key []byte, options ...func(*Sword)) *Sword
  • func (s *Sword) Parse(t []byte) Token
  • func (s *Sword) Sign(data []byte) []byte
  • func (s *Sword) Unsign(token []byte) ([]byte, error)
• type Token

Variables

var ErrInvalidSignature = errors.New("invalid signature")

ErrInvalidSignature is returned by Unsign when the provided token's signatuire is not valid.

var ErrShortToken = errors.New("token is too small to be valid")

ErrShortToken is returned by Unsign when the provided token's length is too short to be a vlaid token.

Functions

func Epoch

func Epoch(e int64) func(*Sword)

Epoch is a functional option that can be passed to New() to set the Epoch to be used.

func Timestamp

func Timestamp(s *Sword)

Timestamp is a functional option that can be passed to New() to add a timestamp to signatures.

Types

type Sword

type Sword struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Sword is a magical Wooden Sword to be used for protection, because it's dangerous out there... Also, it is the main struct used to sign and unsign data using this package.

func New

func New(key []byte, options ...func(*Sword)) *Sword

New takes a secret key and returns a new Sword. If no Options are provided then minimal defaults will be used. NOTE: The key must be 64 bytes or less in size. If a larger key is provided it will be truncated to 64 bytes. func New(key []byte, o *Options) *Sword {

func (*Sword) Parse

func (s *Sword) Parse(t []byte) Token

Parse will parse the []byte token returned from Sign based on the Sword Options into a Token struct. For this to work corectly the Sword Options need to match that of what was used when the token was initially created.

func (*Sword) Sign

func (s *Sword) Sign(data []byte) []byte

Sign signs data and returns []byte in the format `data.signature`. Optionally add a timestamp and return in the format `data.timestamp.signature`

func (*Sword) Unsign

func (s *Sword) Unsign(token []byte) ([]byte, error)

Unsign validates a signature and if successful returns the data portion of the []byte. If unsuccessful it will return an error and nil for the data.

type Token

type Token struct {
	Payload   []byte
	Timestamp time.Time
}

Token is used to parse out a []byte token provided by Sign()