md.h
mbedtls/private_access.h
stddef.h
mbedtls/build_info.h
mbedtls/platform_util.h
ecdsa.h
ecjpake.h
entropy.h
hkdf.h
hmac_drbg.h
oid.h
pk.h
pkcs12.h
pkcs5.h
rsa.h
ssl.h
ssl_ciphersuites.h
mbedtls/build_info.h
mbedtls/check_config.h
mbedtls/config_adjust_legacy_crypto.h
mbedtls/config_adjust_psa_from_legacy.h
mbedtls/config_adjust_psa_superset_legacy.h
mbedtls/config_adjust_ssl.h
mbedtls/config_adjust_x509.h
mbedtls/config_psa.h
mbedtls/mbedtls_config.h
md.h
mbedtls/platform_time.h
mbedtls/platform_util.h
mbedtls/private_access.h
psa/crypto_adjust_auto_enabled.h
psa/crypto_adjust_config_dependencies.h
psa/crypto_adjust_config_key_pair_types.h
psa/crypto_adjust_config_synonyms.h
psa/crypto_legacy.h
inttypes.h
limits.h
stddef.h
stdint.h
time.h
ctr_drbg.h
debug.h
ecdsa.h
ecjpake.h
entropy.h
hkdf.h
hmac_drbg.h
md.h
net_sockets.h
oid.h
pk.h
pkcs12.h
pkcs5.h
pkcs7.h
psa_util.h
rsa.h
ssl.h
ssl_cache.h
ssl_ciphersuites.h
ssl_cookie.h
ssl_ticket.h
x509.h
x509_crl.h
x509_crt.h
x509_csr.h
crypto.h
crypto_builtin_composites.h
crypto_driver_contexts_composites.h
crypto_struct.h
mbedtls_md_context_t
MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE
-0x5080

The selected feature is not available.

MBEDTLS_ERR_MD_BAD_INPUT_DATA
-0x5100

Bad input parameters to function.

MBEDTLS_ERR_MD_ALLOC_FAILED
-0x5180

Failed to allocate memory.

MBEDTLS_ERR_MD_FILE_IO_ERROR
-0x5200

Opening or reading of file failed.

MBEDTLS_MD_MAX_SIZE
64 /* longest known is SHA512 */
MBEDTLS_MD_MAX_BLOCK_SIZE
144 /* the longest known is SHA3-224 */
mbedtls_md_type_t
MBEDTLS_MD_NONE
=0

None.

MBEDTLS_MD_MD5
=0x03

The MD5 message digest.

MBEDTLS_MD_RIPEMD160
=0x04

The RIPEMD-160 message digest.

MBEDTLS_MD_SHA1
=0x05

The SHA-1 message digest.

MBEDTLS_MD_SHA224
=0x08

The SHA-224 message digest.

MBEDTLS_MD_SHA256
=0x09

The SHA-256 message digest.

MBEDTLS_MD_SHA384
=0x0a

The SHA-384 message digest.

MBEDTLS_MD_SHA512
=0x0b

The SHA-512 message digest.

MBEDTLS_MD_SHA3_224
=0x10

The SHA3-224 message digest.

MBEDTLS_MD_SHA3_256
=0x11

The SHA3-256 message digest.

MBEDTLS_MD_SHA3_384
=0x12

The SHA3-384 message digest.

MBEDTLS_MD_SHA3_512
=0x13

The SHA3-512 message digest.

Supported message digests.

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

mbedtls_md_engine_t
MBEDTLS_MD_ENGINE_LEGACY
= 0
MBEDTLS_MD_ENGINE_PSA

Used internally to indicate whether a context uses legacy or PSA.

Internal use only.

struct mbedtls_md_info_t typedef struct mbedtls_md_info_t mbedtls_md_info_t mbedtls_md_info_t

Opaque struct.

Constructed using either mbedtls_md_info_from_string or mbedtls_md_info_from_type.

Fields can be accessed with mbedtls_md_get_size, mbedtls_md_get_type and mbedtls_md_get_name.

struct mbedtls_md_context_t typedef struct mbedtls_md_context_t mbedtls_md_context_t mbedtls_md_context_t

The generic message-digest context.

const mbedtls_md_info_t * const mbedtls_md_info_t * mbedtls_md_info_from_type (mbedtls_md_type_t md_type) mbedtls_md_info_from_type mbedtls_md_type_t md_type

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

md_type

The type of digest to search for.

The message-digest information associated with `md_type`.

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

mbedtls_md_get_size_from_type
void void mbedtls_md_init (mbedtls_md_context_t *ctx) 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 void mbedtls_md_free (mbedtls_md_context_t *ctx) 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 int mbedtls_md_setup (mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac) 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.

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.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.

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

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

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.

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

dst

The destination context.

src

The context to be cloned.

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

unsigned char unsigned char mbedtls_md_get_size (const mbedtls_md_info_t *md_info) mbedtls_md_get_size const mbedtls_md_info_t * md_info

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

md_info

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

The size of the message-digest output in Bytes.

mbedtls_md_get_size_from_type
unsigned char static unsigned char mbedtls_md_get_size_from_type (mbedtls_md_type_t md_type) mbedtls_md_get_size_from_type mbedtls_md_type_t md_type

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

md_type

The message-digest type.

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

mbedtls_md_get_size
mbedtls_md_info_from_type
mbedtls_md_type_t mbedtls_md_type_t mbedtls_md_get_type (const mbedtls_md_info_t *md_info) mbedtls_md_get_type const mbedtls_md_info_t * md_info

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

md_info

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

The type of the message digest.

int int mbedtls_md_starts (mbedtls_md_context_t *ctx) 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(). ctx

The generic message-digest context.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int int mbedtls_md_update (mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen) 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().

ctx

The generic message-digest context.

input

The buffer holding the input data.

ilen

The length of the input data.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int int mbedtls_md_finish (mbedtls_md_context_t *ctx, unsigned char *output) 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.

ctx

The generic message-digest context.

output

The buffer for the generic message-digest checksum result.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int int mbedtls_md (const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output) 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).

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.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

const int * const int * mbedtls_md_list (void) mbedtls_md_list void

This function returns the list of digests supported by the generic digest module.

The list starts with the strongest available hashes.

A statically allocated array of digests. Each element in the returned list is an integer belonging to the message-digest enumeration mbedtls_md_type_t. The last entry is 0.

const mbedtls_md_info_t * const mbedtls_md_info_t * mbedtls_md_info_from_string (const char *md_name) mbedtls_md_info_from_string const char * md_name

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

md_name

The name of the digest to search for.

The message-digest information associated with `md_name`.

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

const char * const char * mbedtls_md_get_name (const mbedtls_md_info_t *md_info) mbedtls_md_get_name const mbedtls_md_info_t * md_info

This function returns the name of the message digest for the message-digest information structure given.

md_info

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

The name of the message digest.

const mbedtls_md_info_t * const mbedtls_md_info_t * mbedtls_md_info_from_ctx (const mbedtls_md_context_t *ctx) mbedtls_md_info_from_ctx const mbedtls_md_context_t * ctx

This function returns the message-digest information from the given context.

ctx

The context from which to extract the information. This must be initialized (or `NULL`).

The message-digest information associated with `ctx`.

`NULL` if `ctx` is `NULL`.

int int mbedtls_md_file (const mbedtls_md_info_t *md_info, const char *path, unsigned char *output) mbedtls_md_file const mbedtls_md_info_t * md_info const char * path unsigned char * output

This function calculates the message-digest checksum result of the contents of the provided file.

The result is calculated as Output = message_digest(file contents).

md_info

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

path

The input file name.

output

The generic message-digest checksum result.

`0` on success.

MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing the file pointed by `path`.

MBEDTLS_ERR_MD_BAD_INPUT_DATA if `md_info` was NULL.

int int mbedtls_md_hmac_starts (mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen) mbedtls_md_hmac_starts mbedtls_md_context_t * ctx const unsigned char * key size_t keylen

This function sets the HMAC key and prepares to authenticate a new message.

Call this function after mbedtls_md_setup(), to use the MD context for an HMAC calculation, then call mbedtls_md_hmac_update() to provide the input data, and mbedtls_md_hmac_finish() to get the HMAC value.

ctx

The message digest context containing an embedded HMAC context.

key

The HMAC secret key.

keylen

The length of the HMAC key in Bytes.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

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

This function feeds an input buffer into an ongoing HMAC computation.

Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() before calling this function. You may call this function multiple times to pass the input piecewise. Afterwards, call mbedtls_md_hmac_finish().

ctx

The message digest context containing an embedded HMAC context.

input

The buffer holding the input data.

ilen

The length of the input data.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

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

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

Call this function after mbedtls_md_hmac_starts() and mbedtls_md_hmac_update() to get the HMAC value. Afterwards you may either call mbedtls_md_free() to clear the context, or call mbedtls_md_hmac_reset() to reuse the context with the same HMAC key.

ctx

The message digest context containing an embedded HMAC context.

output

The generic HMAC checksum result.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int int mbedtls_md_hmac_reset (mbedtls_md_context_t *ctx) mbedtls_md_hmac_reset mbedtls_md_context_t * ctx

This function prepares to authenticate a new message with the same key as the previous HMAC operation.

You may call this function after mbedtls_md_hmac_finish(). Afterwards call mbedtls_md_hmac_update() to pass the new input.

ctx

The message digest context containing an embedded HMAC context.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

int int mbedtls_md_hmac (const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen, unsigned char *output) mbedtls_md_hmac const mbedtls_md_info_t * md_info const unsigned char * key size_t keylen const unsigned char * input size_t ilen unsigned char * output

This function calculates the full generic HMAC on the input buffer with the provided key.

The function allocates the context, performs the calculation, and frees the context.

The HMAC result is calculated as output = generic HMAC(hmac key, input buffer).

md_info

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

key

The HMAC secret key.

keylen

The length of the HMAC secret key in Bytes.

input

The buffer holding the input data.

ilen

The length of the input data.

output

The generic HMAC result.

`0` on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

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

Adriaan de Jong dejong@fox-it.com

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */

    #ifndefMBEDTLS_MD_H
    #defineMBEDTLS_MD_H
    #include"mbedtls/private_access.h"

    #include<stddef.h>

    #include"mbedtls/build_info.h"
    #include"mbedtls/platform_util.h"

    #defineMBEDTLS_ERR_MD_FEATURE_UNAVAILABLE-0x5080
    #defineMBEDTLS_ERR_MD_BAD_INPUT_DATA-0x5100
    #defineMBEDTLS_ERR_MD_ALLOC_FAILED-0x5180
    #defineMBEDTLS_ERR_MD_FILE_IO_ERROR-0x5200

    #ifdef__cplusplus
    extern"C"{
    #endif

    /*Note:thesearealignedwiththedefinitionsofPSA_ALG_macrosforhashes,
    *inordertoenableanefficientimplementationofconversionfunctions.
    *Thisistestedbymd_to_from_psa()intest_suite_md.*/
    typedefenum{
    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,
    }mbedtls_md_type_t;

    /*Note:thisshouldalwaysbe>=PSA_HASH_MAX_SIZE
    *inallbuildswithbothCRYPTO_CandMD_LIGHT.
    *
    *ThisistomakethingseasierformodulessuchasTLSthatmaydefinea
    *buffersizeusingMD_MAX_SIZEinapartofthecodethat'scommontoPSA
    *andlegacy,thenassumethebuffer'ssizeisPSA_HASH_MAX_SIZEinanother
    *partofthecodebasedonPSA.
    */
    #ifdefined(MBEDTLS_MD_CAN_SHA512)||defined(MBEDTLS_MD_CAN_SHA3_512)
    #defineMBEDTLS_MD_MAX_SIZE64/*longestknownisSHA512*/
    #elifdefined(MBEDTLS_MD_CAN_SHA384)||defined(MBEDTLS_MD_CAN_SHA3_384)
    #defineMBEDTLS_MD_MAX_SIZE48/*longestknownisSHA384*/
    #elifdefined(MBEDTLS_MD_CAN_SHA256)||defined(MBEDTLS_MD_CAN_SHA3_256)
    #defineMBEDTLS_MD_MAX_SIZE32/*longestknownisSHA256*/
    #elifdefined(MBEDTLS_MD_CAN_SHA224)||defined(MBEDTLS_MD_CAN_SHA3_224)
    #defineMBEDTLS_MD_MAX_SIZE28/*longestknownisSHA224*/
    #else
    #defineMBEDTLS_MD_MAX_SIZE20/*longestknownisSHA1orRIPEMD-160
    orsmaller(MD5andearlier)*/
    #endif

    #ifdefined(MBEDTLS_MD_CAN_SHA3_224)
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE144/*thelongestknownisSHA3-224*/
    #elifdefined(MBEDTLS_MD_CAN_SHA3_256)
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE136
    #elifdefined(MBEDTLS_MD_CAN_SHA512)||defined(MBEDTLS_MD_CAN_SHA384)
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE128
    #elifdefined(MBEDTLS_MD_CAN_SHA3_384)
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE104
    #elifdefined(MBEDTLS_MD_CAN_SHA3_512)
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE72
    #else
    #defineMBEDTLS_MD_MAX_BLOCK_SIZE64
    #endif

    /*Definedinternallyinlibrary/md_wrap.h.*/
    typedefstructmbedtls_md_info_tmbedtls_md_info_t;

    typedefenum{
    MBEDTLS_MD_ENGINE_LEGACY=0,
    MBEDTLS_MD_ENGINE_PSA,
    }mbedtls_md_engine_t;

    typedefstructmbedtls_md_context_t{
    constmbedtls_md_info_t*MBEDTLS_PRIVATE(md_info);

    #ifdefined(MBEDTLS_MD_SOME_PSA)
    mbedtls_md_engine_tMBEDTLS_PRIVATE(engine);
    #endif

    void*MBEDTLS_PRIVATE(md_ctx);

    #ifdefined(MBEDTLS_MD_C)
    void*MBEDTLS_PRIVATE(hmac_ctx);
    #endif
    }mbedtls_md_context_t;

    constmbedtls_md_info_t*mbedtls_md_info_from_type(mbedtls_md_type_tmd_type);

    voidmbedtls_md_init(mbedtls_md_context_t*ctx);

    voidmbedtls_md_free(mbedtls_md_context_t*ctx);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_setup(mbedtls_md_context_t*ctx,constmbedtls_md_info_t*md_info,inthmac);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_clone(mbedtls_md_context_t*dst,
    constmbedtls_md_context_t*src);

    unsignedcharmbedtls_md_get_size(constmbedtls_md_info_t*md_info);

    staticinlineunsignedcharmbedtls_md_get_size_from_type(mbedtls_md_type_tmd_type)
    {
    returnmbedtls_md_get_size(mbedtls_md_info_from_type(md_type));
    }

    mbedtls_md_type_tmbedtls_md_get_type(constmbedtls_md_info_t*md_info);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_starts(mbedtls_md_context_t*ctx);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_update(mbedtls_md_context_t*ctx,constunsignedchar*input,size_tilen);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_finish(mbedtls_md_context_t*ctx,unsignedchar*output);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md(constmbedtls_md_info_t*md_info,constunsignedchar*input,size_tilen,
    unsignedchar*output);

    constint*mbedtls_md_list(void);

    constmbedtls_md_info_t*mbedtls_md_info_from_string(constchar*md_name);

    constchar*mbedtls_md_get_name(constmbedtls_md_info_t*md_info);

    constmbedtls_md_info_t*mbedtls_md_info_from_ctx(
    constmbedtls_md_context_t*ctx);

    #ifdefined(MBEDTLS_FS_IO)
    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_file(constmbedtls_md_info_t*md_info,constchar*path,
    unsignedchar*output);
    #endif/*MBEDTLS_FS_IO*/

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_hmac_starts(mbedtls_md_context_t*ctx,constunsignedchar*key,
    size_tkeylen);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_hmac_update(mbedtls_md_context_t*ctx,constunsignedchar*input,
    size_tilen);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_hmac_finish(mbedtls_md_context_t*ctx,unsignedchar*output);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_hmac_reset(mbedtls_md_context_t*ctx);

    MBEDTLS_CHECK_RETURN_TYPICAL
    intmbedtls_md_hmac(constmbedtls_md_info_t*md_info,constunsignedchar*key,size_tkeylen,
    constunsignedchar*input,size_tilen,
    unsignedchar*output);

    #ifdef__cplusplus
    }
    #endif

    #endif/*MBEDTLS_MD_H*/