File md.h

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

Author: Adriaan de Jong dejong@fox-it.com

Defines

MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE: The selected feature is not available.

MBEDTLS_ERR_MD_BAD_INPUT_DATA: Bad input parameters to function.

MBEDTLS_ERR_MD_ALLOC_FAILED: Failed to allocate memory.

MBEDTLS_MD_MAX_SIZE

Typedefs

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.

typedef struct mbedtls_md_context_t mbedtls_md_context_t: The generic message-digest context.

Enums

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.

Values:

enumerator MBEDTLS_MD_NONE: None.

enumerator MBEDTLS_MD_MD5: The MD5 message digest.

enumerator MBEDTLS_MD_RIPEMD160: The RIPEMD-160 message digest.

enumerator MBEDTLS_MD_SHA1: The SHA-1 message digest.

enumerator MBEDTLS_MD_SHA224: The SHA-224 message digest.

enumerator MBEDTLS_MD_SHA256: The SHA-256 message digest.

enumerator MBEDTLS_MD_SHA384: The SHA-384 message digest.

enumerator MBEDTLS_MD_SHA512: The SHA-512 message digest.

enumerator MBEDTLS_MD_SHA3_224: The SHA3-224 message digest.

enumerator MBEDTLS_MD_SHA3_256: The SHA3-256 message digest.

enumerator MBEDTLS_MD_SHA3_384: The SHA3-384 message digest.

enumerator MBEDTLS_MD_SHA3_512: The SHA3-512 message digest.

enum mbedtls_md_engine_t

Values:

enumerator MBEDTLS_MD_ENGINE_LEGACY

enumerator 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.

Parameters:: md_type – The type of digest to search for.
Returns:: The message-digest information associated with md_type.
Returns:: NULL if the associated message-digest information is not found.

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.

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().

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.

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.

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.

Returns:

0 on success.

Returns:

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

Returns:

MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation 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.

Note

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.

Returns:

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

Returns:

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().

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.

static inline 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.

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.

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.

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.
Returns:: 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.

Returns:

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

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.

Returns:

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

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.

Returns:

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

struct mbedtls_md_context_t

#include <md.h>

The generic message-digest context.

Public Members

const mbedtls_md_info_t *private_md_info: Information about the associated message digest.

void *private_md_ctx: The digest-specific context (legacy) or the PSA operation.

void *private_hmac_ctx: The HMAC part of the context.