blake3

README

blake3

go get lukechampine.com/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.

Contributions are greatly appreciated. All contributors are eligible to receive an Urbit planet.

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 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. It returns false if verification fails. If the content and tree data are interleaved, outboard should be nil.

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. If outboard is false, the contents of data are also written to dst, interleaved with the tree hashes. It also returns the tree root, i.e. the 256-bit BLAKE3 hash.

func BaoEncodeBuf

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

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

func BaoVerifyBuf

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

BaoVerifyBuf verifies the Bao encoding and root (i.e. BLAKE3 hash) for data. If the content and tree data are interleaved, outboard should be nil.

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.