Lightweight Cryptography Primitives
 All Data Structures Files Functions Variables Typedefs Macros Pages
Macros | Typedefs | Functions
sparkle-kmac.h File Reference

Keyed Message Authentication Code (KMAC) based on XOEsch256. More...

#include "sparkle-hash.h"

Go to the source code of this file.

Macros

#define ESCH_256_KMAC_SIZE   ESCH_256_HASH_SIZE
 Default size of the output for XOEsch256-KMAC.
 
#define ESCH_384_KMAC_SIZE   ESCH_384_HASH_SIZE
 Default size of the output for XOEsch384-KMAC.
 

Typedefs

typedef esch_256_hash_state_t esch_256_kmac_state_t
 State information for the XOEsch256-KMAC incremental mode.
 
typedef esch_384_hash_state_t esch_384_kmac_state_t
 State information for the XOEsch384-KMAC incremental mode.
 

Functions

void esch_256_kmac (const unsigned char *key, size_t keylen, const unsigned char *in, size_t inlen, const unsigned char *custom, size_t customlen, unsigned char *out, size_t outlen)
 Computes a KMAC value using the XOEsch256 XOF mode. More...
 
void esch_256_kmac_init (esch_256_kmac_state_t *state, const unsigned char *key, size_t keylen, const unsigned char *custom, size_t customlen)
 Initializes an incremental KMAC state using the XOEsch256 XOF mode. More...
 
void esch_256_kmac_absorb (esch_256_kmac_state_t *state, const unsigned char *in, size_t inlen)
 Absorbs more input data into an incremental XOEsch256-KMAC state. More...
 
void esch_256_kmac_set_output_length (esch_256_kmac_state_t *state, size_t outlen)
 Sets the desired output length for an incremental XOEsch256-KMAC state. More...
 
void esch_256_kmac_squeeze (esch_256_kmac_state_t *state, unsigned char *out, size_t outlen)
 Squeezes output data from an incremental XOEsch256-KMAC state. More...
 
void esch_256_kmac_finalize (esch_256_kmac_state_t *state, unsigned char out[ESCH_256_KMAC_SIZE])
 Squeezes fixed-length data from an incremental XOEsch256-KMAC state and finalizes the KMAC process. More...
 
void esch_384_kmac (const unsigned char *key, size_t keylen, const unsigned char *in, size_t inlen, const unsigned char *custom, size_t customlen, unsigned char *out, size_t outlen)
 Computes a KMAC value using the XOEsch384 XOF mode. More...
 
void esch_384_kmac_init (esch_384_kmac_state_t *state, const unsigned char *key, size_t keylen, const unsigned char *custom, size_t customlen)
 Initializes an incremental KMAC state using the XOEsch384 XOF mode. More...
 
void esch_384_kmac_absorb (esch_384_kmac_state_t *state, const unsigned char *in, size_t inlen)
 Absorbs more input data into an incremental XOEsch384-KMAC state. More...
 
void esch_384_kmac_set_output_length (esch_384_kmac_state_t *state, size_t outlen)
 Sets the desired output length for an incremental XOEsch384-KMAC state. More...
 
void esch_384_kmac_squeeze (esch_384_kmac_state_t *state, unsigned char *out, size_t outlen)
 Squeezes output data from an incremental XOEsch384-KMAC state. More...
 
void esch_384_kmac_finalize (esch_384_kmac_state_t *state, unsigned char out[ESCH_384_KMAC_SIZE])
 Squeezes fixed-length data from an incremental XOEsch384-KMAC state and finalizes the KMAC process. More...
 

Detailed Description

Keyed Message Authentication Code (KMAC) based on XOEsch256.

The KMAC mode provides a method to authenticate a sequence of bytes using XOEsch256 or XOEsch384 in XOF mode. The output is essentially equivalent to hashing the key followed by the data.

NIST SP 800-185 is an extension of the XOF modes SHAKE128 and SHAKE256. The nearest equivalent for us is XOEsch256-XOF. We use the same encoding as NIST SP 800-185 to provide domain separation between the key and data.

References: NIST SP 800-185

Function Documentation

void esch_256_kmac ( const unsigned char *  key,
size_t  keylen,
const unsigned char *  in,
size_t  inlen,
const unsigned char *  custom,
size_t  customlen,
unsigned char *  out,
size_t  outlen 
)

Computes a KMAC value using the XOEsch256 XOF mode.

Parameters
keyPoints to the key.
keylenNumber of bytes in the key.
inPoints to the data to authenticate.
inlenNumber of bytes of data to authenticate.
customPoints to the customization string.
customlenNumber of bytes in the customization string.
outBuffer to receive the output KMAC value.
outlenLength of the output KMAC value.

The customization string allows the application to perform domain separation between different uses of the KMAC algorithm.

void esch_256_kmac_absorb ( esch_256_kmac_state_t state,
const unsigned char *  in,
size_t  inlen 
)

Absorbs more input data into an incremental XOEsch256-KMAC state.

Parameters
stateKMAC state to be updated.
inPoints to the input data to be absorbed into the state.
inlenLength of the input data to be absorbed into the state.
See Also
esch_256_kmac_init(), esch_256_kmac_squeeze()
void esch_256_kmac_finalize ( esch_256_kmac_state_t state,
unsigned char  out[ESCH_256_KMAC_SIZE] 
)

Squeezes fixed-length data from an incremental XOEsch256-KMAC state and finalizes the KMAC process.

Parameters
stateKMAC state to squeeze the output data from.
outPoints to the output buffer to receive the ESCH_256_KMAC_SIZE bytes of squeezed data.

This function combines the effect of esch_256_kmac_set_output_length() and esch_256_kmac_squeeze() for convenience.

See Also
esch_256_kmac_squeeze(), esch_256_kmac_set_output_length()
void esch_256_kmac_init ( esch_256_kmac_state_t state,
const unsigned char *  key,
size_t  keylen,
const unsigned char *  custom,
size_t  customlen 
)

Initializes an incremental KMAC state using the XOEsch256 XOF mode.

Parameters
statePoints to the state to be initialized.
keyPoints to the key.
keylenNumber of bytes in the key.
customPoints to the customization string.
customlenNumber of bytes in the customization string.
See Also
esch_256_kmac_update(), esch_256_kmac_squeeze()
void esch_256_kmac_set_output_length ( esch_256_kmac_state_t state,
size_t  outlen 
)

Sets the desired output length for an incremental XOEsch256-KMAC state.

Parameters
stateKMAC state to squeeze the output data from after the desired output length has been set.
outlenDesired output length, or zero for arbitrary-length output.
See Also
esch_256_kmac_squeeze()
void esch_256_kmac_squeeze ( esch_256_kmac_state_t state,
unsigned char *  out,
size_t  outlen 
)

Squeezes output data from an incremental XOEsch256-KMAC state.

Parameters
stateKMAC state to squeeze the output data from.
outPoints to the output buffer to receive the squeezed data.
outlenNumber of bytes of data to squeeze out of the state.

The application should call esch_256_kmac_set_output_length() before this function to set the desured output length. If that function has not been called, then this function will assume that the application wants arbitrary-length output.

See Also
esch_256_kmac_init(), esch_256_kmac_update(), esch_256_kmac_finalize()
void esch_384_kmac ( const unsigned char *  key,
size_t  keylen,
const unsigned char *  in,
size_t  inlen,
const unsigned char *  custom,
size_t  customlen,
unsigned char *  out,
size_t  outlen 
)

Computes a KMAC value using the XOEsch384 XOF mode.

Parameters
keyPoints to the key.
keylenNumber of bytes in the key.
inPoints to the data to authenticate.
inlenNumber of bytes of data to authenticate.
customPoints to the customization string.
customlenNumber of bytes in the customization string.
outBuffer to receive the output KMAC value.
outlenLength of the output KMAC value.

The customization string allows the application to perform domain separation between different uses of the KMAC algorithm.

void esch_384_kmac_absorb ( esch_384_kmac_state_t state,
const unsigned char *  in,
size_t  inlen 
)

Absorbs more input data into an incremental XOEsch384-KMAC state.

Parameters
stateKMAC state to be updated.
inPoints to the input data to be absorbed into the state.
inlenLength of the input data to be absorbed into the state.
See Also
esch_384_kmac_init(), esch_384_kmac_squeeze()
void esch_384_kmac_finalize ( esch_384_kmac_state_t state,
unsigned char  out[ESCH_384_KMAC_SIZE] 
)

Squeezes fixed-length data from an incremental XOEsch384-KMAC state and finalizes the KMAC process.

Parameters
stateKMAC state to squeeze the output data from.
outPoints to the output buffer to receive the ESCH_384_KMAC_SIZE bytes of squeezed data.

This function combines the effect of esch_384_kmac_set_output_length() and esch_384_kmac_squeeze() for convenience.

See Also
esch_384_kmac_squeeze(), esch_384_kmac_set_output_length()
void esch_384_kmac_init ( esch_384_kmac_state_t state,
const unsigned char *  key,
size_t  keylen,
const unsigned char *  custom,
size_t  customlen 
)

Initializes an incremental KMAC state using the XOEsch384 XOF mode.

Parameters
statePoints to the state to be initialized.
keyPoints to the key.
keylenNumber of bytes in the key.
customPoints to the customization string.
customlenNumber of bytes in the customization string.
See Also
esch_384_kmac_update(), esch_384_kmac_squeeze()
void esch_384_kmac_set_output_length ( esch_384_kmac_state_t state,
size_t  outlen 
)

Sets the desired output length for an incremental XOEsch384-KMAC state.

Parameters
stateKMAC state to squeeze the output data from after the desired output length has been set.
outlenDesired output length, or zero for arbitrary-length output.
See Also
esch_384_kmac_squeeze()
void esch_384_kmac_squeeze ( esch_384_kmac_state_t state,
unsigned char *  out,
size_t  outlen 
)

Squeezes output data from an incremental XOEsch384-KMAC state.

Parameters
stateKMAC state to squeeze the output data from.
outPoints to the output buffer to receive the squeezed data.
outlenNumber of bytes of data to squeeze out of the state.

The application should call esch_384_kmac_set_output_length() before this function to set the desured output length. If that function has not been called, then this function will assume that the application wants arbitrary-length output.

See Also
esch_384_kmac_init(), esch_384_kmac_update(), esch_384_kmac_finalize()