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.

The pure-Go code is fairly well-optimized, achieving throughput of ~600 MB/s. There is a separate code path for small inputs (up to 64 bytes) that runs in ~100 ns. On CPUs with AVX2 support, larger inputs (>=2 KB) are handled by an avo-generated assembly routine that compresses 8 chunks in parallel, achieving throughput of ~2600 MB/s. Once AVX-512 support is added to avo, it will be possible to compress 16 chunks in parallel, which should roughly double throughput for sufficiently large inputs.

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

Benchmarks

Tested on an i5-7600K @ 3.80GHz.

BenchmarkSum256/64           105 ns/op       609.51 MB/s
BenchmarkSum256/1024        1778 ns/op       576.00 MB/s
BenchmarkSum256/65536      24785 ns/op      2644.15 MB/s
BenchmarkWrite               389 ns/op      2631.78 MB/s
BenchmarkXOF                1591 ns/op       643.80 MB/s

Documentation

Overview

Package blake3 implements the BLAKE3 cryptographic hash function.

Index

• 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 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 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.