Struct Sha 

pub struct Sha { /* private fields */ }

Available on crate feature allow-non-fips only.

The Sha-1 hasher.

Security Warning

The SHA-1 algorithm is included in this library for legacy reasons only. It is cryptographically broken and should not be used for any security-critical applications, especially digital signatures or certificate validation.

The U.S. National Institute of Standards and Technology (NIST) has officially deprecated SHA-1 for all digital signature uses as of 2011. As of 2022, NIST recommends transitioning all applications to use SHA-2, Keccak (SHA-3) family hash functions.

For more information, refer to NIST’s policy on hash functions.

Use this algorithm only if absolutely necessary for backwards compatibility with legacy systems. For all other purposes, please use more secure alternatives such as the SHA-2, SHA-3, and Blake2 family hash functions.

Example

use wolf_crypto::hash::Sha;

let mut hasher = Sha::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(), 20);

Implementations

impl Sha

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

Security Warning

The SHA-1 algorithm is included in this library for legacy reasons only. It is cryptographically broken and should not be used for any security-critical applications, especially digital signatures or certificate validation.

The U.S. National Institute of Standards and Technology (NIST) has officially deprecated SHA-1 for all digital signature uses as of 2011. As of 2022, NIST recommends transitioning all applications to use SHA-2, Keccak (SHA-3) family hash functions.

For more information, refer to NIST’s policy on hash functions.

Use this algorithm only if absolutely necessary for backwards compatibility with legacy systems. For all other purposes, please use more secure alternatives such as the SHA-2, SHA-3, and Blake2 family hash functions.

Create a new Sha instance.

Errors

If the underlying initialization function fails (wc_InitSha)

Example

use wolf_crypto::hash::Sha;

let mut hasher = Sha::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(), 20);

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

Update the underlying wc_Sha instance, without performing any safety checks.

Safety

The length of data is casted to a 32 bit unsigned integer without checking for overflows. While it is incredibly unlikely that this overflow will ever take place, it is not impossible. Thus 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::Sha;

let mut hasher = Sha::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(), 20);

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

Update the underlying wc_Sha instance.

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 casted to a u32.
• If the underlying wc_ShaUpdate function fails.

Example

use wolf_crypto::hash::Sha;

let mut hasher = Sha::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(), 20);

Note: if the size of the data is known at compile time, see update_sized for a slight optimization as the safety checks are done at compilation time.

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

Update the underlying wc_Sha instance, with the safety checks performed at compilation time.

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 casted to a u32.
• If the underlying wc_ShaUpdate function fails.

Example

use wolf_crypto::hash::Sha;

let mut hasher = Sha::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(), 20);

Note: if the size of the data is not known at compile time, see try_update for more flexibility.

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

Available on crate feature can-panic only.

Update the underlying wc_Sha, panicking under any failure.

Arguments

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

Panics

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

If a panic under any failure is not acceptable for your use case, which generally is true, please consider using try_update.

Example

use wolf_crypto::hash::Sha;

let mut hasher = Sha::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(), 20);

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

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state, without performing any safety checks.

Safety

The size of the output argument must have a size of at least 20 (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::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

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

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

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state.

Arguments

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

Errors

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

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

let mut output = [0u8; 20];
let res = hasher.finalize_into(output.as_mut_slice());
assert!(res.is_ok());

Note: if the size of the output slice is known at compile time, see finalize_into_sized for a slight optimization as the safety checks are done at compilation time. There is also finalize_into_exact if this size is exactly 20 bytes, moving all checks to the type system.

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

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state, with the safety checks performed at compilation time.

Arguments

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

Errors

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

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

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

Note: If the size of the output buffer is not known at compilation time see finalize_into for greater flexibility. There is also finalize_into_exact if this size is exactly 20 bytes, moving all checks to the type system.

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

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state, with the safety checks moved to the type system.

Arguments

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

Errors

If the underlying finalize function fails.

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

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

Note: If the size of the output buffer is not known at compilation time see finalize_into for greater flexibility. If the size is known at compilation time, but not exactly 20 bytes, see finalize_into_sized.

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

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state.

Returns

On success, this returns the output digest.

Errors

If the underlying finalize function fails.

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

let res = hasher.try_finalize().unwrap();
assert_ne!(res.as_slice(), input.as_slice());

pub fn finalize(&mut self) -> [u8; 20]

Available on crate feature can-panic only.

Calls the wc_ShaFinal function, finalizing the hashing of data and resetting the underlying wc_Sha instance’s state.

Returns

On success, this returns the output digest.

Panics

If the underlying finalize function fails. If panicking is not acceptable for your use case, which generally is true, see try_finalize.

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

// Use the hasher ...

let res = hasher.try_finalize().unwrap();
assert_ne!(res.as_slice(), input.as_slice());

Trait Implementations

impl Clone for Sha

fn clone(&self) -> Self

Copy the state of the hash (calls the wc_ShaCopy function)

Returns

A distinct new instance of Sha, with the same state as the hasher that was cloned.

Example

use wolf_crypto::hash::Sha;
let mut hasher = Sha::new().unwrap();

assert!(hasher.update_sized(b"hello world").is_ok());

let mut cloned = hasher.clone();
assert_eq!(
    cloned.try_finalize().unwrap(),
    hasher.try_finalize().unwrap(),
    "The two hashers should have the same output"
);

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

Performs copy-assignment from source.

impl Drop for Sha

fn drop(&mut self)

Calls the wc_ShaFree function, cleaning up after itself.

impl Hash for Sha

fn write_alg_name(f: &mut Formatter<'_>) -> Result

Writes “Sha” to f.

type Digest = [u8; 20]

Represents the output digest of the hash function.

type KeyLen = U20

The associated key length for this hashing function.

impl Send for Sha

impl Sync for Sha