Struct SHAKEInternal 

pub struct SHAKEInternal<PARAMS: SHAKEParams> { /* private fields */ }

Internal struct for SHAKE. This uses a private bound so that you cannot instantiate it directly and have to use the provided and NIST-approved parameters.

Note that even though SHAKE is physically capable of acting as a hash function, and in fact is secure as such if the provided message includes the requested length, SHAKE does not implement the Hash trait. FIPS 202 section 7 states:

“SHAKE128 and SHAKE256 are approved XOFs, whose approved uses will be specified in NIST Special Publications. Although some of those uses may overlap with the uses of approved hash functions, the XOFs are not approved as hash functions, due to the property that is discussed in Sec. A.2.”

Section A.2 describes how SHAKE does not internally diversify its output based on the requested length. For example, the first 32 bytes of SHAKE128(“message”, 64) and SHAKE128(“message”, 128), will be identical and equal to SHAKE128(“message”, 32). Proper hash functions don’t do this, and NIST is concerned that this could lead to application vulnerabilities.

Implementations

impl<PARAMS: SHAKEParams> SHAKEInternal<PARAMS>

pub fn new() -> Self

Get a new SHA3 instance, ready for use.

Trait Implementations

impl<PARAMS: SHAKEParams> Algorithm for SHAKEInternal<PARAMS>

const ALG_NAME: &'static str = PARAMS::ALG_NAME

String name for the algorithm, used consistently across the library.

const MAX_SECURITY_STRENGTH: SecurityStrength = PARAMS::MAX_SECURITY_STRENGTH

Maximum security strength supported by the algorithm. In other words, this algorithm can produce outputs up to this security strength, but may produce outputs with lower security strength, for example, if asked to truncate.

impl<PARAMS: Clone + SHAKEParams> Clone for SHAKEInternal<PARAMS>

fn clone(&self) -> SHAKEInternal<PARAMS>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<PARAMS: SHAKEParams> Default for SHAKEInternal<PARAMS>

fn default() -> Self

Returns the “default value” for a type.

impl<PARAMS: SHAKEParams> KDF for SHAKEInternal<PARAMS>

fn derive_key( self, key: &impl KeyMaterialTrait, additional_input: &[u8], ) -> Result<Box<dyn KeyMaterialTrait>, KDFError>

Returns a KeyMaterial. For the KDF to be considered “fully-seeded” and be capable of outputting full-entropy KeyMaterials, it requires full-entropy input that is at least 2x the bit size (ie 256 bits for SHAKE128, and 512 bits for SHAKE256). Returns a 32 byte key for SHAKE128 and a 64 byte key for SHAKE256. To produce longer keys, use KDF::derive_key_out. To produce shorter keys, either use KDF::derive_key_out, truncate this result in place with KeyMaterial::set_key_len, or copy it into a smaller KeyMaterial with KeyMaterialTrait::truncate.

fn derive_key_from_multiple( self, keys: &[&impl KeyMaterialTrait], additional_input: &[u8], ) -> Result<Box<dyn KeyMaterialTrait>, KDFError>

Always returns a full KeyMaterial; ie that fills the internal buffer of the appropriately-sized key material for the underlying cryptographic hash function. This can be truncated down in place with KeyMaterial::set_key_len, or copied into a smaller KeyMaterial with KeyMaterialTrait::truncate. Returns a 32 byte key for SHAKE128 and a 64 byte key for SHAKE256. To produce longer keys, use KDF::derive_key_out. To produce shorter keys, either use KDF::derive_key_out, truncate this result in place with KeyMaterial::set_key_len, or copy it into a smaller KeyMaterial with KeyMaterialTrait::truncate.

fn derive_key_out( self, key: &impl KeyMaterialTrait, additional_input: &[u8], output_key: &mut impl KeyMaterialTrait, ) -> Result<usize, KDFError>

Same as KDF::derive_key, but fills the provided output KeyMaterial.

fn derive_key_from_multiple_out( self, keys: &[&impl KeyMaterialTrait], additional_input: &[u8], output_key: &mut impl KeyMaterialTrait, ) -> Result<usize, KDFError>

Same as KDF::derive_key, but fills the provided output KeyMaterial.

fn max_security_strength(&self) -> SecurityStrength

Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.

impl<PARAMS: SHAKEParams> Suspendable<SUSPENDED_SHA3_STATE_LEN> for SHAKEInternal<PARAMS>

fn suspend(self) -> [u8; 415]

Suspend operation by serializing out the state of the object.

fn from_suspended(serialized_state: [u8; 415]) -> Result<Self, SuspendableError>

Resume operation from a serialized state.

impl<PARAMS: SHAKEParams> XOF for SHAKEInternal<PARAMS>

fn absorb(&mut self, data: &[u8]) -> Result<(), HashError>

This can throw a HashError::InvalidState if called after squeezing has begun, but is safe to consider infallible otherwise – IE feel free to use .unwrap() or .expect() on the result if you are confident that your code cannot call absorb after squeezing.

A rejected call leaves the SHAKE object untouched so the output stream continues consistently. IE it is safe to attempt to feed in more input and do nothing if the absorb fails (“safe” in the sense that it won’t panic, but it may still produce an incorrect output which could be insecure in the sense of being predictable or low-entropy).

fn absorb_last_partial_byte( &mut self, partial_byte: u8, num_partial_bits: usize, ) -> Result<(), HashError>

Switches to squeezing.

fn squeeze_partial_byte_final_out( self, num_bits: usize, output: &mut u8, ) -> Result<(), HashError>

Result is the number of bits squezed into output.

fn hash_xof(self, data: &[u8], result_len: usize) -> Vec<u8>

A static one-shot API that digests the input data and produces result_len bytes of output.

fn hash_xof_out(self, data: &[u8], output: &mut [u8]) -> usize

A static one-shot API that digests the input data and produces result_len bytes of output. Fills the provided output slice. The entire output buffer is zeroized before the output is written.

fn squeeze(&mut self, num_bytes: usize) -> Vec<u8>

Can be called multiple times.

fn squeeze_out(&mut self, output: &mut [u8]) -> usize

Can be called multiple times. Fills the provided output slice. The entire output buffer is zeroized before the output is written.

fn squeeze_partial_byte_final(self, num_bits: usize) -> Result<u8, HashError>

Squeezes a partial byte from the XOF. Output will be in the top num_bits bits of the returned u8 (ie Big Endian). This is a final call and consumes self.

fn max_security_strength(&self) -> SecurityStrength

Returns the maximum security strength that this KDF is capable of supporting, based on the underlying primitives.