NCBI C++ ToolKit
Classes | Macros | Typedefs | Enumerations | Functions
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 "mbedtls/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.

Go to the SVN repository for this file.

Classes

struct  mbedtls_md_context_t
 The generic message-digest context. More...
 

Macros

#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080
 The selected feature is not available. More...
 
#define MBEDTLS_ERR_MD_BAD_INPUT_DATA   -0x5100
 Bad input parameters to function. More...
 
#define MBEDTLS_ERR_MD_ALLOC_FAILED   -0x5180
 Failed to allocate memory. More...
 
#define MBEDTLS_ERR_MD_FILE_IO_ERROR   -0x5200
 Opening or reading of file failed. More...
 
#define MBEDTLS_MD_MAX_SIZE
 
#define MBEDTLS_MD_MAX_BLOCK_SIZE   64
 

Typedefs

typedef struct mbedtls_md_info_t mbedtls_md_info_t
 Opaque struct. More...
 
typedef struct mbedtls_md_context_t mbedtls_md_context_t
 The generic message-digest context. More...
 

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 }
 Used internally to indicate whether a context uses legacy or PSA. More...
 

Functions

const mbedtls_md_info_tmbedtls_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...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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...
 
MBEDTLS_CHECK_RETURN_TYPICAL int mbedtls_md_starts (mbedtls_md_context_t *ctx)
 This function starts a message-digest computation. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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...
 
const intmbedtls_md_list (void)
 This function returns the list of digests supported by the generic digest module. More...
 
const mbedtls_md_info_tmbedtls_md_info_from_string (const char *md_name)
 This function returns the message-digest information associated with the given digest name. More...
 
const char * 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. More...
 
const mbedtls_md_info_tmbedtls_md_info_from_ctx (const mbedtls_md_context_t *ctx)
 This function returns the message-digest information from the given context. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL int 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. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL int 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. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL int 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. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL int 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. More...
 
MBEDTLS_CHECK_RETURN_TYPICAL 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)
 This function calculates the full generic HMAC on the input buffer with the provided key. 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

◆ MBEDTLS_ERR_MD_ALLOC_FAILED

#define MBEDTLS_ERR_MD_ALLOC_FAILED   -0x5180

Failed to allocate memory.

Definition at line 28 of file md.h.

◆ MBEDTLS_ERR_MD_BAD_INPUT_DATA

#define MBEDTLS_ERR_MD_BAD_INPUT_DATA   -0x5100

Bad input parameters to function.

Definition at line 26 of file md.h.

◆ MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE   -0x5080

The selected feature is not available.

Definition at line 24 of file md.h.

◆ MBEDTLS_ERR_MD_FILE_IO_ERROR

#define MBEDTLS_ERR_MD_FILE_IO_ERROR   -0x5200

Opening or reading of file failed.

Definition at line 30 of file md.h.

◆ MBEDTLS_MD_MAX_BLOCK_SIZE

#define MBEDTLS_MD_MAX_BLOCK_SIZE   64

Definition at line 93 of file md.h.

◆ MBEDTLS_MD_MAX_SIZE

#define MBEDTLS_MD_MAX_SIZE
Value:
20 /* longest known is SHA1 or RIPE MD-160
or smaller (MD5 and earlier) */

Definition at line 79 of file md.h.

Typedef Documentation

◆ mbedtls_md_context_t

The generic message-digest context.

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

Definition at line 1 of file md.h.

Enumeration Type Documentation

◆ mbedtls_md_engine_t

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

Internal use only.

Enumerator
MBEDTLS_MD_ENGINE_LEGACY 
MBEDTLS_MD_ENGINE_PSA 

Definition at line 113 of file md.h.

◆ 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 47 of file md.h.

Function Documentation

◆ mbedtls_md()

MBEDTLS_CHECK_RETURN_TYPICAL 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_infoThe information structure of the message-digest algorithm to use.
inputThe buffer holding the data.
ilenThe length of the input data.
outputThe generic message-digest checksum result.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_clone()

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
dstThe destination context.
srcThe 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().

◆ mbedtls_md_finish()

MBEDTLS_CHECK_RETURN_TYPICAL 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
ctxThe generic message-digest context.
outputThe buffer for the generic message-digest checksum result.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_free()

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

◆ mbedtls_md_get_name()

const char* 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.

Parameters
md_infoThe information structure of the message-digest algorithm to use.
Returns
The name of the message digest.

◆ mbedtls_md_get_size()

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

◆ 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_typeThe 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 245 of file md.h.

References mbedtls_md_get_size(), and mbedtls_md_info_from_type().

◆ mbedtls_md_get_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_infoThe information structure of the message-digest algorithm to use.
Returns
The type of the message digest.

◆ mbedtls_md_hmac()

MBEDTLS_CHECK_RETURN_TYPICAL 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 
)

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

Parameters
md_infoThe information structure of the message-digest algorithm to use.
keyThe HMAC secret key.
keylenThe length of the HMAC secret key in Bytes.
inputThe buffer holding the input data.
ilenThe length of the input data.
outputThe generic HMAC result.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_hmac_finish()

MBEDTLS_CHECK_RETURN_TYPICAL int 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.

Parameters
ctxThe message digest context containing an embedded HMAC context.
outputThe generic HMAC checksum result.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_hmac_reset()

MBEDTLS_CHECK_RETURN_TYPICAL int 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.

Parameters
ctxThe message digest context containing an embedded HMAC context.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_hmac_starts()

MBEDTLS_CHECK_RETURN_TYPICAL int 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.

Parameters
ctxThe message digest context containing an embedded HMAC context.
keyThe HMAC secret key.
keylenThe length of the HMAC key in Bytes.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_hmac_update()

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

Parameters
ctxThe message digest context containing an embedded HMAC context.
inputThe buffer holding the input data.
ilenThe length of the input data.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_info_from_ctx()

const mbedtls_md_info_t* mbedtls_md_info_from_ctx ( const mbedtls_md_context_t ctx)

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

Parameters
ctxThe context from which to extract the information. This must be initialized (or NULL).
Returns
The message-digest information associated with ctx.
NULL if ctx is NULL.

◆ mbedtls_md_info_from_string()

const mbedtls_md_info_t* mbedtls_md_info_from_string ( const char *  md_name)

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

Parameters
md_nameThe name of the digest to search for.
Returns
The message-digest information associated with md_name.
NULL if the associated message-digest information is not found.

◆ mbedtls_md_info_from_type()

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_typeThe 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(), and mbedtls_psa_drbg_seed().

◆ mbedtls_md_init()

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.

◆ mbedtls_md_list()

const int* mbedtls_md_list ( void  )

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

Note
The list starts with the strongest available hashes.
Returns
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.

◆ mbedtls_md_setup()

MBEDTLS_CHECK_RETURN_TYPICAL 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
ctxThe context to set up.
md_infoThe information structure of the message-digest algorithm to use.
hmacDefines 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.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.

◆ mbedtls_md_starts()

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
ctxThe generic message-digest context.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.

◆ mbedtls_md_update()

MBEDTLS_CHECK_RETURN_TYPICAL 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
ctxThe generic message-digest context.
inputThe buffer holding the input data.
ilenThe length of the input data.
Returns
0 on success.
MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
Modified on Sat Jun 22 10:43:06 2024 by modify_doxy.py rev. 669887