mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-03-27 23:37:08 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve message digest documentation

Browse Source 
- Rephrase file/function/parameter/enum/define/error descriptions into full
  and clear sentences.
- Make sure to adhere to the Arm writing guidelines.
- Fix missing/incorrect Doxygen tags.
- Standardize terminology used within the file.

GitHub PR: #1319
This commit is contained in:
Rose Zadik 2018-01-25 22:01:10 +00:00 committed by Jaeden Amero
parent 2f8163d3cd
commit 64feefb4a2
1 changed files with 216 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

349
include/mbedtls/md.h
View File

@ -1,12 +1,12 @@
/** /**
* \file md.h * \file md.h
* *
* \brief Generic message digest wrapper * \brief The generic message-digest wrapper.
* *
* \author Adriaan de Jong <dejong@fox-it.com> * \author Adriaan de Jong <dejong@fox-it.com>
*/ */
/* /*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -21,8 +21,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_MD_H #ifndef MBEDTLS_MD_H
#define MBEDTLS_MD_H #define MBEDTLS_MD_H
@ -64,65 +65,79 @@ typedef enum {
#endif #endif
/** /**
* Opaque struct defined in md_internal.h * Opaque struct defined in md_internal.h.
*/ */
typedef struct mbedtls_md_info_t mbedtls_md_info_t; typedef struct mbedtls_md_info_t mbedtls_md_info_t;
/** /**
* Generic message digest context. * The generic message-digest context.
*/ */
typedef struct { typedef struct {
/** Information about the associated message digest */ /** Information about the associated message digest. */
const mbedtls_md_info_t *md_info; const mbedtls_md_info_t *md_info;
/** Digest-specific context */ /** The digest-specific context. */
void *md_ctx; void *md_ctx;
/** HMAC part of the context */ /** The HMAC part of the context. */
void *hmac_ctx; void *hmac_ctx;
} mbedtls_md_context_t; } mbedtls_md_context_t;
/** /**
* \brief Returns the list of digests supported by the generic digest module. * \brief This function returns the list of digests supported by the
* generic digest module.
* *
* \return a statically allocated array of digests, the last entry * \return A statically allocated array of digests. Each element
* is 0. * in the returned list is an integer belonging to the
* message-digest enumeration #mbedtls_md_type_t.
* The last entry is 0.
*/ */
const int *mbedtls_md_list( void ); const int *mbedtls_md_list( void );
/** /**
* \brief Returns the message digest information associated with the * \brief This function returns the message-digest information
* given digest name. * associated with the given digest name.
* *
* \param md_name Name of the digest to search for. * \param md_name The name of the digest to search for.
* *
* \return The message digest information associated with md_name or * \return The message-digest information associated with \p md_name,
* NULL if not found. * or NULL if not found.
*/ */
const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
/** /**
* \brief Returns the message digest information associated with the * \brief This function returns the message-digest information
* given digest type. * associated with the given digest type.
* *
* \param md_type type of digest to search for. * \param md_type The type of digest to search for.
* *
* \return The message digest information associated with md_type or * \return The message-digest information associated with \p md_type,
* NULL if not found. * or NULL if not found.
*/ */
const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
/** /**
* \brief Initialize a md_context (as NONE) * \brief This function initializes a message-digest context without
* This should always be called first. * binding it to a particular message-digest algorithm.
* Prepares the context for mbedtls_md_setup() or mbedtls_md_free(). *
* 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_init( mbedtls_md_context_t *ctx ); void mbedtls_md_init( mbedtls_md_context_t *ctx );
/** /**
* \brief Free and clear the internal structures of ctx. * \brief This function clears the internal structure of \p ctx and
* Can be called at any time after mbedtls_md_init(). * frees any embedded internal structure, but does not free
* Mandatory once mbedtls_md_setup() has been called. * \p ctx itself.
*
* If you have called mbedtls_md_setup() on \p 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().
*/ */
void mbedtls_md_free( mbedtls_md_context_t *ctx ); void mbedtls_md_free( mbedtls_md_context_t *ctx );
@ -133,220 +148,288 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx );
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Select MD to use and allocate internal structures. * \brief This function selects the message digest algorithm to use,
* Should be called after mbedtls_md_init() or mbedtls_md_free(). * 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. * Makes it necessary to call mbedtls_md_free() later.
* *
* \deprecated Superseded by mbedtls_md_setup() in 2.0.0 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0
* *
* \param ctx Context to set up. * \param ctx The context to set up.
* \param md_info Message digest to use. * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \returns \c 0 on success, * \returns \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
* \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
*/ */
int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* MBEDTLS_DEPRECATED_REMOVED */ #endif /* MBEDTLS_DEPRECATED_REMOVED */
/** /**
* \brief Select MD to use and allocate internal structures. * \brief This function selects the message digest algorithm to use,
* Should be called after mbedtls_md_init() or mbedtls_md_free(). * and allocates internal structures.
* Makes it necessary to call mbedtls_md_free() later.
* *
* \param ctx Context to set up. * It should be called after mbedtls_md_init() or
* \param md_info Message digest to use. * mbedtls_md_free(). Makes it necessary to call
* \param hmac 0 to save some memory if HMAC will not be used, * mbedtls_md_free() later.
* non-zero is HMAC is going to be used with this context. *
* \param ctx The context to set up.
* \param md_info The information structure of the message-digest algorithm
* to use.
* \param hmac <ul><li>0: HMAC is not used. Saves some memory.</li>
* <li>non-zero: HMAC is used with this context.</li></ul>
* *
* \returns \c 0 on success, * \returns \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
* \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
*/ */
int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
/** /**
* \brief Clone the state of an MD context * \brief This function clones the state of an message-digest
* context.
* *
* \note The two contexts must have been setup to the same type * \note You must call mbedtls_md_setup() on \c dst before calling
* (cloning from SHA-256 to SHA-512 make no sense). * this function.
* *
* \warning Only clones the MD state, not the HMAC state! (for now) * \note The two contexts must have the same type,
* for example, both are SHA-256.
* *
* \param dst The destination context * \warning This function clones the message-digest state, not the
* \param src The context to be cloned * HMAC state.
*
* \param dst The destination context.
* \param src The context to be cloned.
* *
* \return \c 0 on success, * \return \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
*/ */
int mbedtls_md_clone( mbedtls_md_context_t *dst, int mbedtls_md_clone( mbedtls_md_context_t *dst,
const mbedtls_md_context_t *src ); const mbedtls_md_context_t *src );
/** /**
* \brief Returns the size of the message digest output. * \brief This function extracts the message-digest size from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return size of the message digest output in bytes. * \return The size of the message-digest output in Bytes.
*/ */
unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info ); unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );
/** /**
* \brief Returns the type of the message digest output. * \brief This function extracts the message-digest type from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return type of the message digest output. * \return The type of the message digest.
*/ */
mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info ); mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );
/** /**
* \brief Returns the name of the message digest output. * \brief This function extracts the message-digest name from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return name of the message digest output. * \return The name of the message digest.
*/ */
const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
/** /**
* \brief Prepare the context to digest a new message. * \brief This function starts a message-digest computation.
* Generally called after mbedtls_md_setup() or mbedtls_md_finish().
* Followed by mbedtls_md_update().
* *
* \param ctx generic message digest context. * You must call this function after setting up the context
* with mbedtls_md_setup(), and before passing data with
* mbedtls_md_update().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. *
* \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_starts( mbedtls_md_context_t *ctx ); int mbedtls_md_starts( mbedtls_md_context_t *ctx );
/** /**
* \brief Generic message digest process buffer * \brief This function feeds an input buffer into an ongoing
* Called between mbedtls_md_starts() and mbedtls_md_finish(). * message-digest computation.
* May be called repeatedly.
* *
* \param ctx Generic message digest context * You must call mbedtls_md_starts() before calling this
* \param input buffer holding the datal * function. You may call this function multiple times.
* \param ilen length of the input data * Afterwards, call mbedtls_md_finish().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. * \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
/** /**
* \brief Generic message digest final digest * \brief This function finishes the digest operation,
* Called after mbedtls_md_update(). * and writes the result to the output buffer.
* Usually followed by mbedtls_md_free() or mbedtls_md_starts().
* *
* \param ctx Generic message digest context * Call this function after a call to mbedtls_md_starts(),
* \param output Generic message digest checksum result * 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.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. * \param output The buffer for the generic message-digest checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
/** /**
* \brief Output = message_digest( input buffer ) * \brief This function calculates the message-digest of a buffer,
* with respect to a configurable message-digest algorithm
* in a single call.
* *
* \param md_info message digest info * The result is calculated as
* \param input buffer holding the data * Output = message_digest(input buffer).
* \param ilen length of the input data
* \param output Generic message digest checksum result
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param md_info The information structure of the message-digest algorithm
* verification fails. * to use.
* \param input The buffer holding the data.
* \param ilen The length of the input data.
* \param output The generic message-digest checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
unsigned char *output ); unsigned char *output );
#if defined(MBEDTLS_FS_IO) #if defined(MBEDTLS_FS_IO)
/** /**
* \brief Output = message_digest( file contents ) * \brief This function calculates the message-digest checksum
* result of the contents of the provided file.
* *
* \param md_info message digest info * The result is calculated as
* \param path input file name * Output = message_digest(file contents).
* \param output generic message digest checksum result
* *
* \return 0 if successful, * \param md_info The information structure of the message-digest algorithm
* MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, * to use.
* MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL. * \param path The input file name.
* \param output The generic message-digest checksum result.
*
* \return \c 0 on success,
* #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
* #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
*/ */
int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
unsigned char *output ); unsigned char *output );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
/** /**
* \brief Set HMAC key and prepare to authenticate a new message. * \brief This function sets the HMAC key and prepares to
* Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish(). * authenticate a new message.
* *
* \param ctx HMAC context * Call this function after mbedtls_md_setup(), to use
* \param key HMAC secret key * the MD context for an HMAC calculation, then call
* \param keylen length of the HMAC key in bytes * mbedtls_md_hmac_update() to provide the input data, and
* mbedtls_md_hmac_finish() to get the HMAC value.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param key The HMAC secret key.
* \param keylen The length of the HMAC key in Bytes.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
size_t keylen ); size_t keylen );
/** /**
* \brief Generic HMAC process buffer. * \brief This function feeds an input buffer into an ongoing HMAC
* Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() * computation.
* and mbedtls_md_hmac_finish().
* May be called repeatedly.
* *
* \param ctx HMAC context * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
* \param input buffer holding the data * before calling this function.
* \param ilen length of the input data * You may call this function multiple times to pass the
* input piecewise.
* Afterwards, call mbedtls_md_hmac_finish().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief Output HMAC. * \brief This function finishes the HMAC operation, and writes
* Called after mbedtls_md_hmac_update(). * the result to the output buffer.
* Usually followed by mbedtls_md_hmac_reset(),
* mbedtls_md_hmac_starts(), or mbedtls_md_free().
* *
* \param ctx HMAC context * Call this function after mbedtls_md_hmac_starts() and
* \param output Generic HMAC checksum result * 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.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param output The generic HMAC checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
/** /**
* \brief Prepare to authenticate a new message with the same key. * \brief This function prepares to authenticate a new message with
* Called after mbedtls_md_hmac_finish() and before * the same key as the previous HMAC operation.
* mbedtls_md_hmac_update().
* *
* \param ctx HMAC context to be reset * You may call this function after mbedtls_md_hmac_finish().
* Afterwards call mbedtls_md_hmac_update() to pass the new
* input.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
/** /**
* \brief Output = Generic_HMAC( hmac key, input buffer ) * \brief This function calculates the full generic HMAC
* on the input buffer with the provided key.
* *
* \param md_info message digest info * The function allocates the context, performs the
* \param key HMAC secret key * calculation, and frees the context.
* \param keylen length of the HMAC key in bytes
* \param input buffer holding the data
* \param ilen length of the input data
* \param output Generic HMAC-result
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * The HMAC result is calculated as
* verification fails. * output = generic HMAC(hmac key, input buffer).
*
* \param md_info The information structure of the message-digest algorithm
* to use.
* \param key The HMAC secret key.
* \param keylen The length of the HMAC secret key in Bytes.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The generic HMAC result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, 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, const unsigned char *input, size_t ilen,