md.h File Reference

This file contains the generic functions for message-digest (hashing) and HMAC. More...

#include "mbedtls/private_access.h"
#include <stddef.h>
#include "tf-psa-crypto/build_info.h"
#include "mbedtls/platform_util.h"

Include dependency graph for md.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	mbedtls_md_context_t

Macros
#define	MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080
#define	MBEDTLS_ERR_MD_BAD_INPUT_DATA   PSA_ERROR_INVALID_ARGUMENT
#define	MBEDTLS_ERR_MD_ALLOC_FAILED   PSA_ERROR_INSUFFICIENT_MEMORY
#define	MBEDTLS_MD_MAX_SIZE   64 /* longest known is SHA512 */

Typedefs
typedef struct mbedtls_md_info_t	mbedtls_md_info_t
typedef struct mbedtls_md_context_t	mbedtls_md_context_t

Enumerations
enum	mbedtls_md_type_t {   MBEDTLS_MD_NONE =0, MBEDTLS_MD_MD5 =0x03, MBEDTLS_MD_RIPEMD160 =0x04, MBEDTLS_MD_SHA1 =0x05,   MBEDTLS_MD_SHA224 =0x08, MBEDTLS_MD_SHA256 =0x09, MBEDTLS_MD_SHA384 =0x0a, MBEDTLS_MD_SHA512 =0x0b,   MBEDTLS_MD_SHA3_224 =0x10, MBEDTLS_MD_SHA3_256 =0x11, MBEDTLS_MD_SHA3_384 =0x12, MBEDTLS_MD_SHA3_512 =0x13 }
	Supported message digests. More...
enum	mbedtls_md_engine_t { MBEDTLS_MD_ENGINE_LEGACY = 0, MBEDTLS_MD_ENGINE_PSA }

Functions
const mbedtls_md_info_t *	mbedtls_md_info_from_type (mbedtls_md_type_t md_type)
	This function returns the message-digest information associated with the given digest type. More...
void	mbedtls_md_init (mbedtls_md_context_t *ctx)
	This function initializes a message-digest context without binding it to a particular message-digest algorithm. More...
void	mbedtls_md_free (mbedtls_md_context_t *ctx)
	This function clears the internal structure of ctx and frees any embedded internal structure, but does not free ctx itself. More...
int	mbedtls_md_setup (mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac)
	This function selects the message digest algorithm to use, and allocates internal structures. More...
int	mbedtls_md_clone (mbedtls_md_context_t *dst, const mbedtls_md_context_t *src)
	This function clones the state of a message-digest context. More...
unsigned char	mbedtls_md_get_size (const mbedtls_md_info_t *md_info)
	This function extracts the message-digest size from the message-digest information structure. More...
static unsigned char	mbedtls_md_get_size_from_type (mbedtls_md_type_t md_type)
	This function gives the message-digest size associated to message-digest type. More...
mbedtls_md_type_t	mbedtls_md_get_type (const mbedtls_md_info_t *md_info)
	This function extracts the message-digest type from the message-digest information structure. More...
int	mbedtls_md_starts (mbedtls_md_context_t *ctx)
	This function starts a message-digest computation. More...
int	mbedtls_md_update (mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen)
	This function feeds an input buffer into an ongoing message-digest computation. More...
int	mbedtls_md_finish (mbedtls_md_context_t *ctx, unsigned char *output)
	This function finishes the digest operation, and writes the result to the output buffer. More...
int	mbedtls_md (const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output)
	This function calculates the message-digest of a buffer, with respect to a configurable message-digest algorithm in a single call. More...

Detailed Description

This file contains the generic functions for message-digest (hashing) and HMAC.

Author

Adriaan de Jong dejon.nosp@m.g@fo.nosp@m.x-it..nosp@m.com

Definition in file md.h.

Macro Definition Documentation

#define MBEDTLS_ERR_MD_ALLOC_FAILED   PSA_ERROR_INSUFFICIENT_MEMORY

Failed to allocate memory.

Definition at line 28 of file md.h.

#define MBEDTLS_ERR_MD_BAD_INPUT_DATA   PSA_ERROR_INVALID_ARGUMENT

Bad input parameters to function.

Definition at line 26 of file md.h.

#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080

The selected feature is not available.

Definition at line 24 of file md.h.

#define MBEDTLS_MD_MAX_SIZE   64 /* longest known is SHA512 */

Definition at line 74 of file md.h.

Typedef Documentation

typedef struct mbedtls_md_context_t mbedtls_md_context_t

The generic message-digest context.

typedef struct mbedtls_md_info_t mbedtls_md_info_t

Opaque struct.

Constructed using mbedtls_md_info_from_type.

Fields can be accessed with mbedtls_md_get_size and mbedtls_md_get_type.

Definition at line 95 of file md.h.

Enumeration Type Documentation

enum mbedtls_md_engine_t

Enumerator
MBEDTLS_MD_ENGINE_LEGACY
MBEDTLS_MD_ENGINE_PSA

Definition at line 102 of file md.h.

enum mbedtls_md_type_t

Supported message digests.

Warning

MD5 and SHA-1 are considered weak message digests and their use constitutes a security risk. We recommend considering stronger message digests instead.

Enumerator
MBEDTLS_MD_NONE	None.
MBEDTLS_MD_MD5	The MD5 message digest.
MBEDTLS_MD_RIPEMD160	The RIPEMD-160 message digest.
MBEDTLS_MD_SHA1	The SHA-1 message digest.
MBEDTLS_MD_SHA224	The SHA-224 message digest.
MBEDTLS_MD_SHA256	The SHA-256 message digest.
MBEDTLS_MD_SHA384	The SHA-384 message digest.
MBEDTLS_MD_SHA512	The SHA-512 message digest.
MBEDTLS_MD_SHA3_224	The SHA3-224 message digest.
MBEDTLS_MD_SHA3_256	The SHA3-256 message digest.
MBEDTLS_MD_SHA3_384	The SHA3-384 message digest.
MBEDTLS_MD_SHA3_512	The SHA3-512 message digest.

Definition at line 50 of file md.h.

Function Documentation

int mbedtls_md	(	const mbedtls_md_info_t *	md_info,
		const unsigned char *	input,
		size_t	ilen,
		unsigned char *	output
	)

This function calculates the message-digest of a buffer, with respect to a configurable message-digest algorithm in a single call.

The result is calculated as Output = message_digest(input buffer).

Parameters

md_info	The information structure of the message-digest algorithm to use.
input	The buffer holding the data.
ilen	The length of the input data.
output	The generic message-digest checksum result.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int mbedtls_md_clone	(	mbedtls_md_context_t *	dst,
		const mbedtls_md_context_t *	src
	)

This function clones the state of a message-digest context.

Note

You must call mbedtls_md_setup() on dst before calling this function.

The two contexts must have the same type, for example, both are SHA-256.

Warning

This function clones the message-digest state, not the HMAC state.

Parameters

dst	The destination context.
src	The context to be cloned.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE if both contexts are not using the same engine. This can be avoided by moving the call to psa_crypto_init() before the first call to mbedtls_md_setup().

int mbedtls_md_finish	(	mbedtls_md_context_t *	ctx,
		unsigned char *	output
	)

This function finishes the digest operation, and writes the result to the output buffer.

Call this function after a call to mbedtls_md_starts(), followed by any number of calls to mbedtls_md_update(). Afterwards, you may either clear the context with mbedtls_md_free(), or call mbedtls_md_starts() to reuse the context for another digest operation with the same algorithm.

Parameters

ctx	The generic message-digest context.
output	The buffer for the generic message-digest checksum result.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

void mbedtls_md_free

(

mbedtls_md_context_t *

ctx

)

This function clears the internal structure of ctx and frees any embedded internal structure, but does not free ctx itself.

If you have called mbedtls_md_setup() on ctx, you must call mbedtls_md_free() when you are no longer using the context. Calling this function if you have previously called mbedtls_md_init() and nothing else is optional. You must not call this function if you have not called mbedtls_md_init().

unsigned char mbedtls_md_get_size

(

const mbedtls_md_info_t *

md_info

)

This function extracts the message-digest size from the message-digest information structure.

Parameters

md_info

The information structure of the message-digest algorithm to use.

Returns

The size of the message-digest output in Bytes.

Referenced by mbedtls_md_get_size_from_type().

static unsigned char mbedtls_md_get_size_from_type ( mbedtls_md_type_t  md_type )

inlinestatic

This function gives the message-digest size associated to message-digest type.

Parameters

md_type

The message-digest type.

Returns

The size of the message-digest output in Bytes, or 0 if the message-digest type is not known.

Definition at line 237 of file md.h.

References mbedtls_md_get_size(), and mbedtls_md_info_from_type().

mbedtls_md_type_t mbedtls_md_get_type

(

const mbedtls_md_info_t *

md_info

)

This function extracts the message-digest type from the message-digest information structure.

Parameters

md_info

The information structure of the message-digest algorithm to use.

Returns

The type of the message digest.

const mbedtls_md_info_t* mbedtls_md_info_from_type

(

mbedtls_md_type_t

md_type

)

This function returns the message-digest information associated with the given digest type.

Parameters

md_type

The type of digest to search for.

Returns

The message-digest information associated with md_type.

NULL if the associated message-digest information is not found.

Referenced by mbedtls_md_get_size_from_type().

void mbedtls_md_init

(

mbedtls_md_context_t *

ctx

)

This function initializes a message-digest context without binding it to a particular message-digest algorithm.

This function should always be called first. It prepares the context for mbedtls_md_setup() for binding it to a message-digest algorithm.

int mbedtls_md_setup	(	mbedtls_md_context_t *	ctx,
		const mbedtls_md_info_t *	md_info,
		int	hmac
	)

This function selects the message digest algorithm to use, and allocates internal structures.

It should be called after mbedtls_md_init() or mbedtls_md_free(). Makes it necessary to call mbedtls_md_free() later.

Parameters

ctx	The context to set up.
md_info	The information structure of the message-digest algorithm to use.
hmac	Defines if HMAC is used. 0: HMAC is not used (saves some memory), or non-zero: HMAC is used with this context.

Note

From TF-PSA-Crypto 1.0 and Mbed TLS 4.0 onwards, hmac MUST be set to 0. HMAC operations are no longer supported via MD and may only be performed via the psa_mac_ API.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.

int mbedtls_md_starts

(

mbedtls_md_context_t *

ctx

)

This function starts a message-digest computation.

You must call this function after setting up the context with mbedtls_md_setup(), and before passing data with mbedtls_md_update().

Parameters

ctx	The generic message-digest context.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int mbedtls_md_update	(	mbedtls_md_context_t *	ctx,
		const unsigned char *	input,
		size_t	ilen
	)

This function feeds an input buffer into an ongoing message-digest computation.

You must call mbedtls_md_starts() before calling this function. You may call this function multiple times. Afterwards, call mbedtls_md_finish().

Parameters

ctx	The generic message-digest context.
input	The buffer holding the input data.
ilen	The length of the input data.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.