blake3

Crystal bindings for the official BLAKE3 hashing library.

BLAKE3 is a cryptographic hash function that is:

• Fast - Supports SIMD acceleration (SSE2, SSE4.1, AVX2, AVX-512) on *nix (UNIX, UNIX-Like, Linux, etc.) and Windows GNU targets.
• Secure - Designed as a successor to BLAKE2.
• Versatile - Provides regular hashing, keyed hashing, key derivation, and extendable output (XOF).

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     blake3:
       github: okavatti/blake3
   

2. Run shards install

This will automatically compile the included C library (in portable mode) as part of the installation.

Usage

require "blake3"

One-shot hashing

Blake3::Hasher.hexdigest("hello world")   # => "d74981efa70a..."
Blake3::Hasher.digest("data")             # => Bytes[32]

Streaming (incremental) hashing

hasher = Blake3::Hasher.new
hasher.update("hello ")
hasher.update("world")
hasher.hexdigest  # => "d74981efa70a..."

Keyed hashing

key = Blake3::Hasher.hexdigest("my secret key").to_slice[0, 32]
hasher = Blake3::Hasher.new(key)
hasher.update("data")
hasher.hexdigest  # => "..."

Key derivation (BLAKE3 context)

hasher = Blake3::Hasher.new(context: "my application v1")
hasher.update(key_material)
derived_key = hasher.finalize_hash  # 32-byte key

Extendable-output (XOF)

hasher = Blake3::Hasher.new
hasher.update("data")
long_hash = hasher.finalize_hash(64)   # 64-byte output

API Overview

Blake3::Hasher

Constructors

• new - unkeyed hashing.
• new(key : Bytes) - keyed hashing. Key must be exactly 32 bytes. Raises ArgumentError otherwise.
• new(context : String) - key derivation context.

Instance Methods

• update(data : Bytes | String) : self - feed data; chainable.
• finalize_hash : Bytes - returns 32-byte digest.
• finalize_hash(output_len : Int32) : Bytes - XOF output of arbitrary length.
• hexdigest : String - shortcut for finalize_hash.hexstring.
• digest : Bytes - alias for finalize_hash.

Calling update after finalize_hash raises Blake3::HasherAlreadyFinalized.

Class Convenience Methods

• Blake3::Hasher.digest(data) : Bytes - one-shot hash.
• Blake3::Hasher.hexdigest(data) : String - one-shot hex digest.
• Blake3::Hasher.keyed_digest(key, data) : Bytes - one-shot keyed hash.
• Blake3::Hasher.derive_key(context, key_material?) : Bytes - one-shot key derivation.

Performance

This binding uses the official BLAKE3 C library directly, giving you the same speed as the reference implementation.

By default, the library is compiled in portable mode - it works on any CPU without SIMD.
Hardware acceleration (SSE2, SSE4.1, AVX2, AVX-512) is optional and can be enabled as described below.

Development

Clone the repository and run:

make -C ext       # build the C library (portable mode)
crystal spec      # run tests

Enabling SIMD acceleration

To unlock the full speed of BLAKE3 on x86-64, you need the corresponding assembly files.

1. Download the required assembly files from the official BLAKE3 repository into the ext/ folder.

   On Linux / macOS:

   cd ext
   for ext in sse2 sse41 avx2 avx512; do
     wget "https://raw.githubusercontent.com/BLAKE3-team/BLAKE3/master/c/blake3_${ext}_x86-64_unix.S"
   done
   

   On Windows (MinGW):

   cd ext
   for ext in sse2 sse41 avx2 avx512; do
     wget "https://raw.githubusercontent.com/BLAKE3-team/BLAKE3/master/c/blake3_${ext}_x86-64_windows_gnu.S"
   done
   

2. Rebuild with the SIMD=1 flag:

   make -C ext clean
   make -C ext SIMD=1
   

The Makefile automatically detects your operating system and includes only the correct assembly files. At runtime, the library will select the best instruction set for your CPU.

License

The Crystal bindings are provided under the MIT License.
The BLAKE3 C library is available under the CC0 1.0 Universal and/or the Apache 2.0 licenses. The original license files are included in ext/.

Acknowledgements

This project wraps the excellent work of the BLAKE3 team:

• Jack O'Connor, Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O'Hearn.
• Official repository: https://github.com/BLAKE3-team/BLAKE3