XOF Class Reference

Abstract base class for Extendable-Output Functions (XOFs). More...

#include <XOF.h>

Inheritance diagram for XOF:

Public Member Functions
	XOF ()
	Constructs a new XOF object.
virtual	~XOF ()
	Destroys this XOF object. More...
virtual size_t	blockSize () const =0
	Size of the internal block used by the XOF algorithm, in bytes. More...
virtual void	reset ()=0
	Resets the XOF ready for a new session. More...
virtual void	update (const void *data, size_t len)=0
	Updates the XOF with more data. More...
virtual void	extend (uint8_t *data, size_t len)=0
	Generates extendable output from this XOF. More...
virtual void	encrypt (uint8_t *output, const uint8_t *input, size_t len)=0
	Encrypts an input buffer with extendable output from this XOF. More...
void	decrypt (uint8_t *output, const uint8_t *input, size_t len)
	Decrypts an input buffer with extendable output from this XOF. More...
virtual void	clear ()=0
	Clears the hash state, removing all sensitive data, and then resets the XOF ready for a new session. More...

Detailed Description

Abstract base class for Extendable-Output Functions (XOFs).

Extendable-Output Functions, or XOFs, are a new class of cryptographic primitive that was defined by NIST during the SHA-3 standardization process. Essentially an XOF is a hash algorithm that has an arbitrary-length output instead of a fixed-length digest.

XOFs can be used for a variety of cryptographic tasks:

• Mask generation functions for RSA OAEP style padding.
• Key derivation functions for expanding key seed material into arbitrary amounts of keying material for a secure session.
• Stream ciphers based on a key and IV.

To use an XOF, it is first reset() and then data is added via multiple calls to update():

SHAKE256 xof;
xof.reset();
xof.update(data1, sizeof(data1));
xof.update(data2, sizeof(data2));
...

Once all input data has been added, the XOF switches into extend mode to generate the arbitrary-length output data:

xof.extend(output1, sizeof(output1));
xof.extend(output2, sizeof(output2));
...

Mask generation and key derivation is achieved as follows, where the key is unique for each invocation:

SHAKE256 xof;
xof.reset();
xof.update(key, sizeof(key));
xof.extend(output, sizeof(output));

Stream ciphers can be constructed as follows, using the special encrypt() function that XOR's the output of extend() with the input plaintext to generate the output ciphertext (or alternatively XOR's the output of extend() with the ciphertext to recover the plaintext):

SHAKE256 xof;
xof.reset();
xof.update(key, sizeof(key));
xof.update(iv, sizeof(iv));
xof.encrypt(output1, input1, sizeof(input1));
xof.encrypt(output2, input2, sizeof(input2));
...

If the key is reused, then the IV must be different for each session or the encryption scheme can be easily broken. It is better to generate a new key and IV combination for every session.

It may also be a good idea to include some tag information with the input data to distinguish different uses of the XOF. For example:

SHAKE256 xof;
xof.reset();
xof.update(key, sizeof(key));
xof.update(iv, sizeof(iv));
xof.update("MyCrypt", 7);
xof.encrypt(output, input, sizeof(input));

If the same key and IV was used with a different package, then it would not generate the same output as "MyCrypt".

NIST warns that XOFs should not be used in place of hash functions. This is because of related outputs: if the same input is provided to an XOF with different output lengths, then the shorter output will be a prefix of the larger. This breaks the expected collision-resistance of regular hash functions. There is typically no need to use an XOF for hashing because NIST has already defined SHA3_256 and SHA3_512 for that purpose.

Reference: http://en.wikipedia.org/wiki/SHA-3

See also

SHAKE256, SHAKE128, SHA3_256

Definition at line 29 of file XOF.h.

Constructor & Destructor Documentation

~XOF()

XOF::~XOF ( )

virtual

Destroys this XOF object.

Note

Subclasses are responsible for clearing any sensitive data that remains in the XOF object when it is destroyed.

See also

clear()

Definition at line 134 of file XOF.cpp.

Member Function Documentation

blockSize()

size_t XOF::blockSize ( ) const

pure virtual

Size of the internal block used by the XOF algorithm, in bytes.

See also

update()

Implemented in SHAKE.

clear()

void XOF::clear ( )

pure virtual

Clears the hash state, removing all sensitive data, and then resets the XOF ready for a new session.

See also

reset()

Implemented in SHAKE.

decrypt()

void XOF::decrypt ( uint8_t *  output, const uint8_t *  input, size_t  len  )

inline

Decrypts an input buffer with extendable output from this XOF.

Parameters

output	The output buffer to write to, which may be the same buffer as input. The output buffer must have at least as many bytes as the input buffer.
input	The input buffer to read from.
len	The number of bytes to encrypt.

This is a convenience function that merely calls encrypt().

See also

reset(), update(), extend(), encrypt()

Definition at line 43 of file XOF.h.

encrypt()

void XOF::encrypt ( uint8_t *  output, const uint8_t *  input, size_t  len  )

pure virtual

Encrypts an input buffer with extendable output from this XOF.

Parameters

output	The output buffer to write to, which may be the same buffer as input. The output buffer must have at least as many bytes as the input buffer.
input	The input buffer to read from.
len	The number of bytes to encrypt.

This function is a convenience that generates data with extend() and then XOR's it with the contents of input to generate the output. This function can also be used to decrypt.

The encrypt() function can be called multiple times with different regions of the plaintext data.

See also

reset(), update(), extend(), decrypt()

Implemented in SHAKE.

extend()

void XOF::extend ( uint8_t *  data, size_t  len  )

pure virtual

Generates extendable output from this XOF.

Parameters

data	The data buffer to be filled.
len	The number of bytes to write to data.

See also

reset(), update(), encrypt()

Implemented in SHAKE.

reset()

void XOF::reset ( )

pure virtual

Resets the XOF ready for a new session.

See also

update(), extend(), encrypt()

Implemented in SHAKE.

update()

void XOF::update ( const void *  data, size_t  len  )

pure virtual

Updates the XOF with more data.

Parameters

data	Data to be hashed.
len	Number of bytes of data to be added to the XOF.

If extend() or encrypt() has already been called, then the behavior of update() will be undefined. Call reset() first to start a new session.

See also

reset(), extend(), encrypt()

Implemented in SHAKE.

---

The documentation for this class was generated from the following files:

• XOF.h
• XOF.cpp