goalone

package module
v0.0.0-...-742bb55 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2019 License: BSD-2-Clause Imports: 7 Imported by: 98

README

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

Documentation

Index

Constants

This section is empty.

Variables

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

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

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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