Trait XOF 

pub trait XOF: Default {
    // Required methods
    fn hash_xof(self, data: &[u8], result_len: usize) -> Vec<u8> ;
    fn hash_xof_out(self, data: &[u8], output: &mut [u8]) -> usize;
    fn absorb(&mut self, data: &[u8]) -> Result<(), HashError>;
    fn absorb_last_partial_byte(
        &mut self,
        partial_byte: u8,
        num_partial_bits: usize,
    ) -> Result<(), HashError>;
    fn squeeze(&mut self, num_bytes: usize) -> Result<Vec<u8>, HashError>;
    fn squeeze_out(&mut self, output: &mut [u8]) -> Result<usize, HashError>;
    fn squeeze_partial_byte_final(
        self,
        num_bits: usize,
    ) -> Result<u8, HashError>;
    fn squeeze_partial_byte_final_out(
        self,
        num_bits: usize,
        output: &mut u8,
    ) -> Result<(), HashError>;
    fn max_security_strength(&self) -> SecurityStrength;
}

Extensible Output Functions (XOFs) are similar to hash functions, except that they can produce output of arbitrary length. The naming used for the functions of this trait are borrowed from the SHA3-style sponge constructions that split XOF operation into two phases: an absorb phase in which an arbitrary amount of input is provided to the XOF, and then a squeeze phase in which an arbitrary amount of output is extracted. Once squeezing begins, no more input can be absorbed.

XOFs are similar to hash functions, but are not hash functions for one technical but important reason: since the amount of output to produce is not provided to the XOF in advance, it cannot be used to diversify the XOF output streams. In other words, the overlapping parts of their outputs will be the same! For example, consider two XOFs that absorb the same input data, one that is squeezed to produce 32 bytes, and the other to produce 1 kb; both outputs will be identical in their first 32 bytes. This could lead to loss of security in a number of ways, for example distinguishing attacks where it is sufficient for the attacker to know that two values came from the same input, even if the attacker cannot learn what that input was. This is attack is often sufficient, for example, to break anonymity-preserving technology. Applications that require the arbitrary-length output of an XOF, but also care about these distinguishing attacks should consider adding a cryptographic salt to diversify the inputs.

Required Methods

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.

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

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

Switches to squeezing.

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

Can be called multiple times.

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

Can be called multiple times. Fills the provided output slice.

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 squeeze_partial_byte_final_out( self, num_bits: usize, output: &mut u8, ) -> Result<(), HashError>

fn max_security_strength(&self) -> SecurityStrength

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors