Struct blake3::Hasher

pub struct Hasher { /* fields omitted */ }

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

In addition to its inherent methods, this type implements several commonly used traits from the digest and crypto_mac crates.

Performance note: The update and update_with_join methods perform poorly when the caller’s input buffer is small. See their method docs below. A 16 KiB buffer is large enough to leverage all currently supported SIMD instruction sets.

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() -> Self

Construct a new Hasher for the regular hash function.

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

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

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

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 Self

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. However, depending on how much inlining the optimizer does, moving a Hasher might copy its entire CV stack, most of which is useless uninitialized bytes. This methods avoids that copy.

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

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

This method is always single-threaded. For multi-threading support, see update_with_join below.

Note that the degree of SIMD parallelism that update can use is limited by the size of this input buffer. The 8 KiB buffer currently used by std::io::copy is enough to leverage AVX2, for example, but not enough to leverage AVX-512. A 16 KiB buffer is large enough to leverage all currently supported SIMD instruction sets.

pub fn update_with_join<J: Join>(&mut self, input: &[u8]) -> &mut Self

Add input bytes to the hash state, as with update, but potentially using multi-threading. See the example below, and the join module for a more detailed explanation.

To get any performance benefit from multi-threading, the input buffer size needs to be very large. As a rule of thumb on x86_64, there is no benefit to multi-threading inputs less than 128 KiB. Other platforms have different thresholds, and in general you need to benchmark your specific use case. Where possible, memory mapping an entire input file is recommended, to take maximum advantage of multi-threading without needing to tune a specific buffer size. Where memory mapping is not possible, good multi-threading performance requires doing IO on a background thread, to avoid sleeping all your worker threads while the input buffer is (serially) refilled. This is quite complicated compared to memory mapping.

Example

// Hash a large input using multi-threading. Note that multi-threading
// comes with some overhead, and it can actually hurt performance for small
// inputs. The meaning of "small" varies, however, depending on the
// platform and the number of threads. (On x86_64, the cutoff tends to be
// around 128 KiB.) You should benchmark your own use case to see whether
// multi-threading helps.
let input: &[u8] = some_large_input();
let mut hasher = blake3::Hasher::new();
hasher.update_with_join::<blake3::join::RayonJoin>(input);
let hash = hasher.finalize();

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.

Trait Implementations

impl BlockInput for Hasher

type BlockSize = U64

Block size

impl Clone for Hasher

fn clone(&self) -> Hasher

Returns a copy 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

Formats the value using the given formatter.

impl Default for Hasher

fn default() -> Self

Returns the “default value” for a type.

impl ExtendableOutput for Hasher

type Reader = OutputReader

Reader

fn finalize_xof(self) -> Self::Reader

Retrieve XOF reader and consume hasher instance.

fn finalize_xof_reset(&mut self) -> Self::Reader

Retrieve XOF reader and reset hasher instance state.

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

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

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

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

impl FixedOutput for Hasher

type OutputSize = U32

Output size for fixed output digest

fn finalize_into(self, out: &mut GenericArray<u8, Self::OutputSize>)

Write result into provided array and consume the hasher instance.

fn finalize_into_reset(&mut self, out: &mut GenericArray<u8, Self::OutputSize>)

Write result into provided array and reset the hasher instance.

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

Retrieve result and consume the hasher instance.

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

Retrieve result and reset the hasher instance.

impl Mac for Hasher

type OutputSize = U32

Output size of the [Mac]

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

Update MAC state with the given data.

fn reset(&mut self)

Reset Mac instance.

fn finalize(self) -> Output<Self>

Obtain the result of a Mac computation as a Output and consume Mac instance.

fn finalize_reset(&mut self) -> Output<Self>

Obtain the result of a Mac computation as a Output and reset Mac instance.

fn verify(self, tag: &[u8]) -> Result<(), MacError>

Check if tag/code value is correct for the processed input.

impl NewMac for Hasher

type KeySize = U32

Key size in bytes with which cipher guaranteed to be initialized.

fn new(key: &Key<Self>) -> Self

Initialize new MAC instance from key with fixed size.

fn new_varkey(key: &[u8]) -> Result<Self, InvalidKeyLength>

Initialize new MAC instance from key with variable size.

impl Reset for Hasher

fn reset(&mut self)

Reset hasher instance to its initial state and return current state.

impl Update for Hasher

fn update(&mut self, data: impl AsRef<[u8]>)

Digest input data.

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

Digest input data in a chained manner.

impl Write for Hasher

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

This is equivalent to update.

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

Flush 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, fmt: Arguments<'_>) -> Result<(), Error>

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

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

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