Struct Blake3 

pub struct Blake3 { /* private fields */ }

An incremental hash state that can accept any number of writes.

The rayon and mmap Cargo features enable additional methods on this type related to multithreading and memory-mapped IO.

When the traits-preview Cargo feature is enabled, this type implements several commonly used traits from the digest crate. However, those traits aren’t stable, and they’re expected to change in incompatible ways before that crate reaches 1.0. For that reason, this crate makes no SemVer guarantees for this feature, and callers who use it should expect breaking changes between patch versions.

Examples

// Hash an input incrementally.
let mut hasher = blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
assert_eq!(hasher.finalize(), blake3::hash(b"foobarbaz"));

// Extended output. OutputReader also implements Read and Seek.
let mut output = [0; 1000];
let mut output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(&output[..32], blake3::hash(b"foobarbaz").as_bytes());

Implementations

impl Hasher

pub fn new() -> Hasher

Construct a new Hasher for the regular hash function.

pub fn new_keyed(key: &[u8; 32]) -> Hasher

Construct a new Hasher for the keyed hash function. See keyed_hash.

pub fn new_derive_key(context: &str) -> Hasher

Construct a new Hasher for the key derivation function. See derive_key. The context string should be hardcoded, globally unique, and application-specific.

pub fn reset(&mut self) -> &mut Hasher

Reset the Hasher to its initial state.

This is functionally the same as overwriting the Hasher with a new one, using the same key or context string if any.

pub fn update(&mut self, input: &[u8]) -> &mut Hasher

Add input bytes to the hash state. You can call this any number of times.

This method is always single-threaded. For multithreading support, see update_rayon (enabled with the rayon Cargo feature).

Note that the degree of SIMD parallelism that update can use is limited by the size of this input buffer. See update_reader.

pub fn finalize(&self) -> Hash

Finalize the hash state and return the Hash of the input.

This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.

pub fn finalize_xof(&self) -> OutputReader

Finalize the hash state and return an OutputReader, which can supply any number of output bytes.

This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.

pub fn count(&self) -> u64

Return the total number of bytes hashed so far.

[hazmat::HasherExt::set_input_offset] does not affect this value. This only counts bytes passed to update.

pub fn update_reader(&mut self, reader: impl Read) -> Result<&mut Hasher, Error>

As update, but reading from a std::io::Read implementation.

Hasher implements std::io::Write, so it’s possible to use std::io::copy to update a Hasher from any reader. Unfortunately, this standard approach can limit performance, because copy currently uses an internal 8 KiB buffer that isn’t big enough to take advantage of all SIMD instruction sets. (In particular, AVX-512 needs a 16 KiB buffer.) update_reader avoids this performance problem and is slightly more convenient.

The internal buffer size this method uses may change at any time, and it may be different for different targets. The only guarantee is that it will be large enough for all of this crate’s SIMD implementations on the current platform.

The most common implementer of std::io::Read might be std::fs::File, but note that memory mapping can be faster than this method for hashing large files. See update_mmap and update_mmap_rayon, which require the mmap and (for the latter) rayon Cargo features.

This method requires the std Cargo feature, which is enabled by default.

Example

// Hash standard input.
let mut hasher = blake3::Hasher::new();
hasher.update_reader(std::io::stdin().lock())?;
println!("{}", hasher.finalize());

Trait Implementations

impl BlockSizeUser for Hasher

type BlockSize = UInt<UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>, B0>

Size of the block in bytes.

fn block_size() -> usize

Return block size in bytes.

impl Clone for Hasher

fn clone(&self) -> Hasher

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Hasher

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Hasher

fn default() -> Hasher

Returns the “default value” for a type.

impl ExtendableOutput for Hasher

type Reader = OutputReader

Reader

fn finalize_xof(self) -> <Hasher as ExtendableOutput>::Reader

Retrieve XOF reader and consume hasher instance.

fn finalize_xof_into(self, out: &mut [u8])

Finalize XOF and write result into out.

fn digest_xof(input: impl AsRef<[u8]>, output: &mut [u8])

where Self: Default,

Compute hash of data and write it into output.

fn finalize_boxed(self, output_size: usize) -> Box<[u8]>

Retrieve result into a boxed slice of the specified size and consume the hasher.

impl ExtendableOutputReset for Hasher

fn finalize_xof_reset(&mut self) -> <Hasher as ExtendableOutput>::Reader

Retrieve XOF reader and reset hasher instance state.

fn finalize_xof_reset_into(&mut self, out: &mut [u8])

Finalize XOF, write result into out, and reset the hasher state.

fn finalize_boxed_reset(&mut self, output_size: usize) -> Box<[u8]>

Retrieve result into a boxed slice of the specified size and reset the hasher state.

impl FixedOutput for Hasher

fn finalize_into( self, out: &mut GenericArray<u8, <Hasher as OutputSizeUser>::OutputSize>, )

Consume value and write result into provided array.

fn finalize_fixed(self) -> GenericArray<u8, Self::OutputSize>

Retrieve result and consume the hasher instance.

impl FixedOutputReset for Hasher

fn finalize_into_reset( &mut self, out: &mut GenericArray<u8, <Hasher as OutputSizeUser>::OutputSize>, )

Write result into provided array and reset the hasher state.

fn finalize_fixed_reset(&mut self) -> GenericArray<u8, Self::OutputSize>

Retrieve result and reset the hasher state.

impl HasherExt for Hasher

fn new_from_context_key(context_key: &[u8; 32]) -> Hasher

Similar to Hasher::new_derive_key but using a pre-hashed [ContextKey] from [hash_derive_key_context].

fn set_input_offset(&mut self, offset: u64) -> &mut Hasher

Configure the Hasher to process a chunk or subtree starting at offset bytes into the whole input.

fn finalize_non_root(&self) -> [u8; 32]

Finalize the non-root hash (“chaining value”) of the current chunk or subtree.

impl KeyInit for Hasher

fn new(key: &GenericArray<u8, <Hasher as KeySizeUser>::KeySize>) -> Hasher

Create new value from fixed size key.

fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength>

Create new value from variable size key.

fn generate_key( rng: impl CryptoRng + RngCore, ) -> GenericArray<u8, Self::KeySize>

Generate random key using the provided CryptoRng.

impl KeySizeUser for Hasher

type KeySize = UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>

Key size in bytes.

fn key_size() -> usize

Return key size in bytes.

impl OutputSizeUser for Hasher

type OutputSize = UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>

Size of the output in bytes.

fn output_size() -> usize

Return output size in bytes.

impl Reset for Hasher

fn reset(&mut self)

Reset state to its initial value.

impl Update for Hasher

fn update(&mut self, data: &[u8])

Update state using the provided data.

fn chain(self, data: impl AsRef<[u8]>) -> Self

where Self: Sized,

Digest input data in a chained manner.

impl Write for Hasher

Available on crate feature std only.

fn write(&mut self, input: &[u8]) -> Result<usize, Error>

This is equivalent to update.

fn flush(&mut self) -> Result<(), Error>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl HashMarker for Hasher

impl MacMarker for Hasher