Struct Blake2s 

pub struct Blake2s<const C: usize> { /* private fields */ }

Available on crate feature allow-non-fips only.

The Blake2s hasher.

Soundness Note

In the underlying wolfcrypt source, the blake2s_final function includes a comment /* Is this correct? */, which may raise concern about its implementation. However, we have subjected this Rust API to extensive testing, including property tests against other trusted Blake2s implementations, and no failures have been observed.

Furthermore, this comment is not present in the public WolfSSL API, suggesting that they may have confidence in their own implementation despite the internal comment.

Const Generic

• C - The length of the Blake2s digest to implement, with a maximum length of 32.

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
assert!(hasher.try_update(input.as_slice()).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_eq!(finalized.len(), 32);

Implementations

impl<const C: usize> Blake2s<C>

pub fn new() -> Result<Self, Unspecified>

Create a new Blake2s instance.

Errors

• If the digest length is greater than 32 (const generic C)
• If the underling initialization function fails (wc_InitBlake2s)

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
assert!(hasher.try_update(input.as_slice()).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

// Maximum `C` is 32
assert!(Blake2s::<{32 * 2}>::new().is_err());

pub fn new_with_key(key: &[u8]) -> Result<Self, Unspecified>

Create a new Blake2s instance using a key.

The key is used to create a keyed Blake2s instance, which is suitable for message authentication (MAC) purposes. The output digest length is determined by the constant generic parameter C.

Errors

• If the digest length C is greater than 32.
• If the key length exceeds 32 bytes.
• If the key is of zero length.
• If the underlying initialization function (wc_InitBlake2s_WithKey) fails.

Arguments

• key - A secret key used to initialize the Blake2s instance. The length of the key must be less than or equal to 32 bytes.

Example

use wolf_crypto::hash::Blake2s;

let key = b"my-secret-key";
let mut hasher = Blake2s::<32>::new_with_key(key).unwrap();

let input = b"hello world";
assert!(hasher.try_update(input.as_slice()).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

// Key length must be less than or equal to 32 bytes.
let long_key = [0u8; 32 * 2];
assert!(Blake2s::<32>::new_with_key(&long_key).is_err());

pub fn new_with_sized_key<const K: usize>( key: &[u8; K], ) -> Result<Self, Unspecified>

Create a new Blake2s instance using a fixed-size key.

This function allows you to specify the key as a fixed-size array. It is similar to new_with_key but function preconditions are checked at compile time.

Errors

• If the digest length C is greater than 32.
• If the key length exceeds 32 bytes (compile-time check).
• If the key is of zero length.
• If the underlying initialization function (wc_InitBlake2s_WithKey) fails.

Arguments

• key: A fixed-size secret key (length K) used to initialize the Blake2s instance. The length of the key must be less than or equal to 32 bytes.

Example

use wolf_crypto::hash::Blake2s;

let key: [u8; 32] = [0x00; 32];
let mut hasher = Blake2s::<32>::new_with_sized_key(&key).unwrap();

let input = b"some data";
assert!(hasher.try_update(input.as_slice()).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_eq!(finalized.len(), 32);

// Key length must be less than or equal to 32 bytes.
let oversized_key = [0u8; 32 * 2];
assert!(Blake2s::<32>::new_with_sized_key(&oversized_key).is_err());

pub unsafe fn update_unchecked(&mut self, data: &[u8]) -> Res

Update the Blake2s instance with the provided data, without performing any safety checks.

Safety

The length of the data is cast to a 32-bit unsigned integer without checking for overflow. While this is unlikely to occur in most practical scenarios, it is not impossible, especially with very large slices. Therefore, this function is marked unsafe.

Arguments

• data - The slice to update the underlying hasher state with.

Returns

This function returns the result of the operation.

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
// SAFETY: The length of `hello world` is 11, which cannot overflow even an 8-bit integer.
let res = unsafe { hasher.update_unchecked(input.as_slice()) };
assert!(res.is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

pub fn try_update(&mut self, data: &[u8]) -> Res

Update the Blake2s instance with the provided data.

Arguments

• data - The slice to update the underlying hasher state with.

Returns

This function returns the result of the operation.

Errors

• If the length of data cannot be safely cast to a u32.
• If the underlying wc_Blake2sUpdate function fails.

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
assert!(hasher.try_update(input.as_slice()).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

pub fn update_sized<const OC: usize>(&mut self, data: &[u8; OC]) -> Res

Update the Blake2s instance with the provided data, using compile-time safety checks.

Arguments

• data - The slice to update the underlying hasher state with, where the size of the slice is known at compile time.

Returns

This function returns the result of the operation.

Errors

• If the length of data cannot be safely cast to a u32.
• If the underlying wc_Blake2sUpdate function fails.

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
assert!(hasher.update_sized(&input).is_ok());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

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

Available on crate feature can-panic only.

Update the Blake2s instance with the provided data, panicking on failure.

Arguments

• data - The slice to update the underlying hasher state with.

Panics

• If the length of data cannot be safely cast to a u32.
• If the underlying wc_Blake2sUpdate function fails.

If a panic is not acceptable for your use case, consider using try_update instead.

Example

use wolf_crypto::hash::Blake2s;

let mut hasher = Blake2s::<32>::new().unwrap();

let input = b"hello world";
hasher.update(input.as_slice());

let finalized = hasher.try_finalize().unwrap();
assert_ne!(finalized.as_slice(), input.as_slice());
assert_eq!(finalized.len(), 32);

pub unsafe fn finalize_unchecked(self, output: &mut [u8]) -> Res

Finalize the Blake2s hashing process, writing the output to the provided buffer, without performing safety checks.

Safety

The size of the output argument must be at least C (the size of the digest).

Arguments

• output - The buffer to store the output digest in.

Returns

This function returns the result of the operation.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

let mut output = [0u8; 32];
// SAFETY: The size of the output buffer is exactly 32 bytes (the size of the digest).
let res = unsafe { hasher.finalize_unchecked(&mut output) };
assert!(res.is_ok());

pub fn finalize_into(self, output: &mut [u8]) -> Res

Finalize the Blake2s hashing process, writing the output to the provided buffer.

Arguments

• output - The buffer to store the output digest in.

Errors

• If the size of output is less than C (the size of the digest).
• If the underlying finalize function fails.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

// use the hasher ...

let mut output = [0u8; 32];
assert!(hasher.finalize_into(&mut output).is_ok());

pub fn finalize_into_sized<const OC: usize>(self, output: &mut [u8; OC]) -> Res

Finalize the Blake2s hashing process, writing the output to a fixed-size buffer, and performing safety checks at compilation time.

Arguments

• output - The fixed-size buffer to store the output digest in.

Errors

• If the length of output is less than C (the size of the digest).
• If the underlying finalize function fails.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

// use the hasher ...

let mut output = [0u8; 32];
assert!(hasher.finalize_into_sized(&mut output).is_ok());

pub fn finalize_into_exact(self, output: &mut [u8; C]) -> Res

Finalize the Blake2s hashing process, writing the output to a buffer with an exact size.

This method is for cases where the size of the output buffer is exactly the same as the digest size (C). The buffer size is checked at compile time, so no runtime size checks are necessary, making this a highly optimized version of finalization.

Arguments

• output - The buffer to store the output digest in, with a size exactly equal to the digest size (C).

Returns

This function returns the result of the operation.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

// use the hasher ...

let mut output = [0u8; 32];
assert!(hasher.finalize_into_exact(&mut output).is_ok());

Note: If the size of the output buffer is not exactly C, see finalize_into for greater flexibility, or finalize_into_sized if the size is known at compile time but is not exactly C.

pub fn try_finalize(self) -> Result<[u8; C], Unspecified>

Finalize the Blake2s hashing process, returning the result as an array.

Returns

On success, this returns the output digest as an array.

Errors

If the underlying finalize function fails.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

// use the hasher ...

let res = hasher.try_finalize().unwrap();
assert_eq!(res.len(), 32);

pub fn finalize(self) -> [u8; C]

Available on crate feature can-panic only.

Finalize the Blake2s hashing process, returning the result as an array, panicking on failure.

Returns

On success, this returns the output digest as an array.

Panics

If the underlying finalize function fails.

If panicking is not acceptable for your use case, consider using try_finalize instead.

Example

use wolf_crypto::hash::Blake2s;
let mut hasher = Blake2s::<32>::new().unwrap();

// use the hasher ...

let res = hasher.finalize();
assert_eq!(res.len(), 32);

Trait Implementations

impl<const C: usize> Send for Blake2s<C>

impl<const C: usize> Sync for Blake2s<C>