hash.h File Reference

(9b0647a)

Hash functions for the OpenTitan cryptography library. More...

#include "datatypes.h"

Go to the source code of this file.

Data Structures
struct	otcrypto_hash_context
	Generic opaque hash context. More...

Typedefs
typedef struct otcrypto_hash_context	otcrypto_hash_context_t
	Generic opaque hash context. More...

Enumerations
enum	{   kSha256DigestBits = 256,   kSha256DigestBytes = kSha256DigestBits / 8,   kSha256DigestWords = kSha256DigestBytes / sizeof(uint32_t),   kSha384DigestBits = 384,   kSha384DigestBytes = kSha384DigestBits / 8,   kSha384DigestWords = kSha384DigestBytes / sizeof(uint32_t),   kSha512DigestBits = 512,   kSha512DigestBytes = kSha512DigestBits / 8,   kSha512DigestWords = kSha512DigestBytes / sizeof(uint32_t),   kOtcryptoHashCtxStructWords = 92 }

Functions
otcrypto_status_t	otcrypto_hash (otcrypto_const_byte_buf_t input_message, otcrypto_hash_digest_t digest)
	Performs the required hash function on the input data. More...
otcrypto_status_t	otcrypto_xof_shake (otcrypto_const_byte_buf_t input_message, otcrypto_hash_digest_t digest)
	Performs the SHAKE extendable output function (XOF) on input data. More...
otcrypto_status_t	otcrypto_xof_cshake (otcrypto_const_byte_buf_t input_message, otcrypto_const_byte_buf_t function_name_string, otcrypto_const_byte_buf_t customization_string, otcrypto_hash_digest_t digest)
	Performs the CSHAKE extendable output function (XOF) on input data. More...
otcrypto_status_t	otcrypto_hash_init (otcrypto_hash_context_t *const ctx, otcrypto_hash_mode_t hash_mode)
	Performs the INIT operation for a cryptographic hash function. More...
otcrypto_status_t	otcrypto_hash_update (otcrypto_hash_context_t *const ctx, otcrypto_const_byte_buf_t input_message)
	Performs the UPDATE operation for a cryptographic hash function. More...
otcrypto_status_t	otcrypto_hash_final (otcrypto_hash_context_t *const ctx, otcrypto_hash_digest_t digest)
	Performs the FINAL operation for a cryptographic hash function. More...

Detailed Description

Hash functions for the OpenTitan cryptography library.

Supports both SHA2 and SHA3 hash functions, plus the additional Keccak-based hash functions SHAKE and cSHAKE.

Definition in file hash.h.

---

Data Structure Documentation

otcrypto_hash_context

struct otcrypto_hash_context

Generic opaque hash context.

Representation is internal to the hash implementation; initialize with otcrypto_hash_init.

Definition at line 50 of file hash.h.

Data Fields
uint32_t	data[kOtcryptoHashCtxStructWords]

Typedef Documentation

otcrypto_hash_context_t

typedef struct otcrypto_hash_context otcrypto_hash_context_t

Generic opaque hash context.

Representation is internal to the hash implementation; initialize with otcrypto_hash_init.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
kOtcryptoHashCtxStructWords	The size of the publicly exposed HMAC context in words. We assert that this value is large enough to host the internal HMAC driver struct.

Definition at line 22 of file hash.h.

Function Documentation

otcrypto_hash()

otcrypto_status_t otcrypto_hash	(	otcrypto_const_byte_buf_t	input_message,
		otcrypto_hash_digest_t	digest
	)

Performs the required hash function on the input data.

The caller should allocate space for the digest buffer and set the mode and len fields. If the length does not match the mode, an error message will be returned.

This function should only be used for fixed-length hash functions (SHA-2 and SHA-3 families). Use otcrypto_xof_shake and otcrypto_xof_cshake for extendable-output functions.

Parameters

	input_message	Input message to be hashed.
[out]	digest	Output digest after hashing the input message.

Returns

Result of the hash operation.

Definition at line 120 of file hash.c.

otcrypto_hash_final()

otcrypto_status_t otcrypto_hash_final	(	otcrypto_hash_context_t *const	ctx,
		otcrypto_hash_digest_t	digest
	)

Performs the FINAL operation for a cryptographic hash function.

The final operation processes the remaining partial blocks, computes the final hash and copies it to the digest parameter.

otcrypto_hash_update should be called before this function.

The caller should allocate space for the digest buffer and set the mode and len fields. If the mode doesn't match the mode of the hash context, the function will return an error.

Parameters

	ctx	Pointer to the generic hash context struct.
[out]	digest	Output digest after hashing the input blocks.

Returns

Result of the hash final operation.

Definition at line 268 of file hash.c.

otcrypto_hash_init()

otcrypto_status_t otcrypto_hash_init	(	otcrypto_hash_context_t *const	ctx,
		otcrypto_hash_mode_t	hash_mode
	)

Performs the INIT operation for a cryptographic hash function.

Initializes the generic hash context. The required hash mode is selected through the hash_mode parameter. Only kOtcryptoHashModeSha256, kOtcryptoHashModeSha384 and kOtcryptoHashModeSha512 are supported. Other modes are not supported and an error would be returned.

Populates the hash context with the selected hash mode and its digest and block sizes. The structure of hash context and how it populates the required fields are internal to the specific hash implementation.

Parameters

ctx	Pointer to the generic hash context struct.
hash_mode	Required hash mode.

Returns

Result of the hash init operation.

Definition at line 223 of file hash.c.

otcrypto_hash_update()

otcrypto_status_t otcrypto_hash_update	(	otcrypto_hash_context_t *const	ctx,
		otcrypto_const_byte_buf_t	input_message
	)

Performs the UPDATE operation for a cryptographic hash function.

The update operation processes the input_message using the selected hash compression function. The intermediate digest is stored in the context ctx. Any partial data is stored back in the context and combined with the subsequent bytes.

otcrypto_hash_init should be called before this function.

Parameters

ctx	Pointer to the generic hash context struct.
input_message	Input message to be hashed.

Returns

Result of the hash update operation.

Definition at line 255 of file hash.c.

otcrypto_xof_cshake()

otcrypto_status_t otcrypto_xof_cshake	(	otcrypto_const_byte_buf_t	input_message,
		otcrypto_const_byte_buf_t	function_name_string,
		otcrypto_const_byte_buf_t	customization_string,
		otcrypto_hash_digest_t	digest
	)

Performs the CSHAKE extendable output function (XOF) on input data.

The function_name_string is used by NIST to define functions based on cSHAKE. When no function other than cSHAKE is desired; it can be empty. The customization_string is used to define a variant of the cSHAKE function. If no customization is desired it can be empty.

The caller should allocate space for the digest buffer and set the mode and len fields. The mode parameter must be kOtcryptoHashXofModeCshake128 or kOtcryptoHashXofModeCshake256; other values will result in errors.

Parameters

	input_message	Input message for extendable output function.
	function_name_string	NIST Function name string.
	customization_string	Customization string for cSHAKE.
[out]	digest	Output from the extendable output function.

Returns

Result of the xof operation.

Definition at line 182 of file hash.c.

otcrypto_xof_shake()

otcrypto_status_t otcrypto_xof_shake	(	otcrypto_const_byte_buf_t	input_message,
		otcrypto_hash_digest_t	digest
	)

Performs the SHAKE extendable output function (XOF) on input data.

The caller should allocate space for the digest buffer and set the mode and len fields. The mode parameter must be kOtcryptoHashXofModeShake128 or kOtcryptoHashXofModeShake256; other values will result in errors.

Parameters

	input_message	Input message for extendable output function.
[out]	digest	Output from the extendable output function.

Returns

Result of the xof operation.

Definition at line 164 of file hash.c.