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 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
- type OutputReader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BaoDecode ¶
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 ¶
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.
Note that dst is not written sequentially, and therefore must be initialized with sufficient capacity to hold the encoding; see BaoEncodedSize.
func BaoEncodeBuf ¶
BaoEncodeBuf returns the Bao encoding and root (i.e. BLAKE3 hash) for data.
func BaoEncodedSize ¶
BaoEncodedSize returns the size of a Bao encoding for the provided quantity of data.
func BaoVerifyBuf ¶
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 ¶
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.
Types ¶
type Hasher ¶
type Hasher struct {
// contains filtered or unexported fields
}
Hasher implements hash.Hash.
func New ¶
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) 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.
Source Files