gopow

README

Go - Proof of work

Small package implementing a sha256 based proof of work.

Install

go get github.com/jeongY-Cho/go-pow

Usage

Not Interesting Use

import "github.com/jeongY-Cho/go-pow"

func main() {

  // make an instance with default config
  pow := gopow.New(&Pow{})
  // defaults:
  // 	Secret      ""
  // 	NonceLength 10
  // 	Check       false
  // 	Difficulty  0

  // generate a nonce
  nonceArr, err := pow.GenerateNonce()
  // nonceArr is an array of two strings
  // first element is the nonce
  // second element is a nonce checksum generated when check is true
  nonce := nonceArr[0]


  // some data
  data := getSomeData()

  // make data a string concat with nonce then hash
  hash := SHA256HashFunc(string(data) + nonce)

  // use gopow to verify hash
  ok, err := pow.VerifyHash(nonce, string(data), hash, "")
  // ok will be true on good verify
  // ok will be false and return an error on bad verify
}

Interesting Use

import github.com/jeongY-Cho/go-pow

func main() {

  // make an instance with a config
  pow := gopow.New(&Pow{
    Secret: "thisisasecret",
    NonceLength: 100,
    Check: true,
    Difficulty: 2
  })

  // generate a nonce
  nonceArr, err := pow.GenerateNonce()
  // nonceArr is an array of two strings
  // first element is the nonce
  // second element is a nonce checksum generated when check is true
  nonce := nonceArr[0]
  nonceChecksum := nonceArr[1]

  // some data
  data := getSomeData()

  // make data a string concat with nonce then hash
  hash := SHA256HashFunc(string(data) + nonce[0])

  // use gopow to verify hash
  ok, err := pow.VerifyHashAtDifficulty(nonce, string(data), hash, nonceChecksum)
  // if the hash doesn't have two leading `0` (ie difficulty == 2) then verify
  // will fail
  // if the nonceChecksum is not hash of `nonce + secret` then verify will fail
}

Application: login throttling

1. Client requests a nonce, nonceChecksum and difficulty from server
2. Client calculates a hash with the username + password + randomBits + nonce that fulfills difficulty.
3. Client sends username, password, nonce, nonceChecksum, calculated hash, and the randomBits.
4. Server validates nonce against nonceChecksum, and hash against received data, then proceeds on valid hash.

(alternatively a server could cache nonces instead of calculating checksums)

q.v. https://www.fastly.com/blog/defend-against-credential-stuffing-attacks-proof-of-work

Documentation

Index

• type HashFunction
• type NonceGenerator
• type Pow
  • func New(config *Pow) *Pow
  • func (p *Pow) GenerateNonce() (nonce []byte, checksum []byte, err error)
  • func (p *Pow) VerifyDifficulty(hash []byte) bool
  • func (p *Pow) VerifyHash(nonce []byte, data []byte, hash []byte, nonceSig []byte) (bool, error)
  • func (p *Pow) VerifyHashAtDifficulty(nonce []byte, data []byte, hash []byte, nonceSig []byte) (bool, error)

Types

type HashFunction

type HashFunction func([]byte) []byte

HashFunction type.

type NonceGenerator

type NonceGenerator func(int) ([]byte, error)

NonceGenerator function type. takes a length parameter and returns a string.

The length parameter is optional; the returned string need not be
as long as the length parameter

type Pow

type Pow struct {
	Secret      []byte
	NonceLength int
	Check       bool
	Difficulty  int
	// NonceGenerator method returns a nonce. Takes an integer parameter
	// which is `Pow.NonceLength`. Defaults to `gonanoid.Nanoid`
	NonceGenerator NonceGenerator
	// Hash is a method that hashes a slice of bytes and returns a new slice which is a hash of the slice.
	//   Defaults to `sha256.Sum256`
	Hash HashFunction
}

Pow ...

func New

func New(config *Pow) *Pow

New helper function to return new pow object with defaults

func (*Pow) GenerateNonce

func (p *Pow) GenerateNonce() (nonce []byte, checksum []byte, err error)

GenerateNonce generates a new nonce, also generates signature if verify enabled

func (*Pow) VerifyDifficulty

func (p *Pow) VerifyDifficulty(hash []byte) bool

VerifyDifficulty verifies hash fulfils difficulty requirement

func (*Pow) VerifyHash

func (p *Pow) VerifyHash(nonce []byte, data []byte, hash []byte, nonceSig []byte) (bool, error)

VerifyHash verifies the hash given the nonce and data

func (*Pow) VerifyHashAtDifficulty

func (p *Pow) VerifyHashAtDifficulty(nonce []byte, data []byte, hash []byte, nonceSig []byte) (bool, error)

VerifyHashAtDifficulty verifies hash and difficulty