/go-alone

A simple to use, high-performance, Go (golang) MAC signer.

Primary LanguageGoBSD 2-Clause "Simplified" LicenseBSD-2-Clause

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

GoDoc Go report Build Status Coverage Discord Gophers

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