blake3

README

blake3

go get github.com/pingooio/stdx/crypto/blake3

blake3 implements the BLAKE3 cryptographic hash function. This implementation aims to be performant without sacrificing (too much) readability, in the hopes of eventually landing in x/crypto.

In addition to the pure-Go implementation, this package also contains AVX-512 and AVX2 routines (generated by avo) that greatly increase performance for large inputs and outputs.

Benchmarks

Tested on a 2020 MacBook Air (i5-7600K @ 3.80GHz). Benchmarks will improve as soon as I get access to a beefier AVX-512 machine. 😉

AVX-512

BenchmarkSum256/64           120 ns/op       533.00 MB/s
BenchmarkSum256/1024        2229 ns/op       459.36 MB/s
BenchmarkSum256/65536      16245 ns/op      4034.11 MB/s
BenchmarkWrite               245 ns/op      4177.38 MB/s
BenchmarkXOF                 246 ns/op      4159.30 MB/s

AVX2

BenchmarkSum256/64           120 ns/op       533.00 MB/s
BenchmarkSum256/1024        2229 ns/op       459.36 MB/s
BenchmarkSum256/65536      31137 ns/op      2104.76 MB/s
BenchmarkWrite               487 ns/op      2103.12 MB/s
BenchmarkXOF                 329 ns/op      3111.27 MB/s

Pure Go

BenchmarkSum256/64           120 ns/op       533.00 MB/s
BenchmarkSum256/1024        2229 ns/op       459.36 MB/s
BenchmarkSum256/65536     133505 ns/op       490.89 MB/s
BenchmarkWrite              2022 ns/op       506.36 MB/s
BenchmarkXOF                1914 ns/op       534.98 MB/s

Shortcomings

There is no assembly routine for single-block compressions. This is most noticeable for ~1KB inputs.

Each assembly routine inlines all 7 rounds, causing thousands of lines of duplicated code. Ideally the routines could be merged such that only a single routine is generated for AVX-512 and AVX2, without sacrificing too much performance.

Documentation

Overview

Package blake3 implements the BLAKE3 cryptographic hash function.

Index

• func BaoDecode(dst io.Writer, data, outboard io.Reader, root [32]byte) (bool, error)
• func BaoEncode(dst io.WriterAt, data io.Reader, dataLen int64, outboard bool) ([32]byte, error)
• func BaoEncodeBuf(data []byte, outboard bool) ([]byte, [32]byte)
• func BaoEncodedSize(dataLen int, outboard bool) int
• func BaoVerifyBuf(data, outboard []byte, root [32]byte) bool
• func DeriveKey(subKey []byte, ctx string, srcKey []byte)
• func Sum256(b []byte) (out [32]byte)
• func Sum512(b []byte) (out [64]byte)
• type Hasher
  • func New(size int, key []byte) *Hasher
  • func (h *Hasher) BlockSize() int
  • func (h *Hasher) Reset()
  • func (h *Hasher) Size() int
  • func (h *Hasher) Sum(b []byte) (sum []byte)
  • func (h *Hasher) Write(p []byte) (int, error)
  • func (h *Hasher) XOF() *OutputReader
• type OutputReader
  • func (or *OutputReader) Read(p []byte) (int, error)
  • func (or *OutputReader) Seek(offset int64, whence int) (int64, error)

Functions

func BaoDecode

func BaoDecode(dst io.Writer, data, outboard io.Reader, root [32]byte) (bool, error)

BaoDecode reads content and tree data from the provided reader(s), and streams the verified content to dst.

Deprecated: Use bao.Decode instead.

func BaoEncode

func BaoEncode(dst io.WriterAt, data io.Reader, dataLen int64, outboard bool) ([32]byte, error)

BaoEncode computes the intermediate BLAKE3 tree hashes of data and writes them to dst.

Deprecated: Use bao.Encode instead.

func BaoEncodeBuf

func BaoEncodeBuf(data []byte, outboard bool) ([]byte, [32]byte)

BaoEncodeBuf returns the Bao encoding and root (i.e. BLAKE3 hash) for data.

Deprecated: Use bao.EncodeBuf instead.

func BaoEncodedSize

func BaoEncodedSize(dataLen int, outboard bool) int

EncodedSize returns the size of a Bao encoding for the provided quantity of data.

Deprecated: Use bao.EncodedSize instead.

func BaoVerifyBuf

func BaoVerifyBuf(data, outboard []byte, root [32]byte) bool

BaoVerifyBuf verifies the Bao encoding and root (i.e. BLAKE3 hash) for data.

Deprecated: Use bao.VerifyBuf instead.

func DeriveKey

func DeriveKey(subKey []byte, ctx string, srcKey []byte)

DeriveKey derives a subkey from ctx and srcKey. ctx should be hardcoded, globally unique, and application-specific. A good format for ctx strings is:

[application] [commit timestamp] [purpose]

e.g.:

example.com 2019-12-25 16:18:03 session tokens v1

The purpose of these requirements is to ensure that an attacker cannot trick two different applications into using the same context string.

func Sum256

func Sum256(b []byte) (out [32]byte)

Sum256 returns the unkeyed BLAKE3 hash of b, truncated to 256 bits.

func Sum512

func Sum512(b []byte) (out [64]byte)

Sum512 returns the unkeyed BLAKE3 hash of b, truncated to 512 bits.

Types

type Hasher

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

Hasher implements hash.Hash.

func New

func New(size int, key []byte) *Hasher

New returns a Hasher for the specified digest size and key. If key is nil, the hash is unkeyed. Otherwise, len(key) must be 32.

func (*Hasher) BlockSize

func (h *Hasher) BlockSize() int

BlockSize implements hash.Hash.

func (*Hasher) Reset

func (h *Hasher) Reset()

Reset implements hash.Hash.

func (*Hasher) Size

func (h *Hasher) Size() int

Size implements hash.Hash.

func (*Hasher) Sum

func (h *Hasher) Sum(b []byte) (sum []byte)

Sum implements hash.Hash.

func (*Hasher) Write

func (h *Hasher) Write(p []byte) (int, error)

Write implements hash.Hash.

func (*Hasher) XOF

func (h *Hasher) XOF() *OutputReader

XOF returns an OutputReader initialized with the current hash state.

type OutputReader

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

An OutputReader produces an seekable stream of 2^64 - 1 pseudorandom output bytes.

func (*OutputReader) Read

func (or *OutputReader) Read(p []byte) (int, error)

Read implements io.Reader. Callers may assume that Read returns len(p), nil unless the read would extend beyond the end of the stream.

func (*OutputReader) Seek

func (or *OutputReader) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker.