git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/md.h

   1  /**\r
   2  * \file md.h\r
   3  *\r
   4  * \brief This file contains the generic message-digest wrapper.\r
   5  *\r
   6  * \author Adriaan de Jong <dejong@fox-it.com>\r
   7  */\r
   8 /*\r
   9  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved\r
  10  *  SPDX-License-Identifier: Apache-2.0\r
  11  *\r
  12  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  13  *  not use this file except in compliance with the License.\r
  14  *  You may obtain a copy of the License at\r
  15  *\r
  16  *  http://www.apache.org/licenses/LICENSE-2.0\r
  17  *\r
  18  *  Unless required by applicable law or agreed to in writing, software\r
  19  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  20  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  21  *  See the License for the specific language governing permissions and\r
  22  *  limitations under the License.\r
  23  *\r
  24  *  This file is part of Mbed TLS (https://tls.mbed.org)\r
  25  */\r
  26 \r
  27 #ifndef MBEDTLS_MD_H\r
  28 #define MBEDTLS_MD_H\r
  29 \r
  30 #include <stddef.h>\r
  31 \r
  32 #if !defined(MBEDTLS_CONFIG_FILE)\r
  33 #include "config.h"\r
  34 #else\r
  35 #include MBEDTLS_CONFIG_FILE\r
  36 #endif\r
  37 \r
  38 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE                -0x5080  /**< The selected feature is not available. */\r
  39 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA                     -0x5100  /**< Bad input parameters to function. */\r
  40 #define MBEDTLS_ERR_MD_ALLOC_FAILED                       -0x5180  /**< Failed to allocate memory. */\r
  41 #define MBEDTLS_ERR_MD_FILE_IO_ERROR                      -0x5200  /**< Opening or reading of file failed. */\r
  42 \r
  43 /* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */\r
  44 #define MBEDTLS_ERR_MD_HW_ACCEL_FAILED                    -0x5280  /**< MD hardware accelerator failed. */\r
  45 \r
  46 #ifdef __cplusplus\r
  47 extern "C" {\r
  48 #endif\r
  49 \r
  50 /**\r
  51  * \brief     Supported message digests.\r
  52  *\r
  53  * \warning   MD2, MD4, MD5 and SHA-1 are considered weak message digests and\r
  54  *            their use constitutes a security risk. We recommend considering\r
  55  *            stronger message digests instead.\r
  56  *\r
  57  */\r
  58 typedef enum {\r
  59     MBEDTLS_MD_NONE=0,    /**< None. */\r
  60     MBEDTLS_MD_MD2,       /**< The MD2 message digest. */\r
  61     MBEDTLS_MD_MD4,       /**< The MD4 message digest. */\r
  62     MBEDTLS_MD_MD5,       /**< The MD5 message digest. */\r
  63     MBEDTLS_MD_SHA1,      /**< The SHA-1 message digest. */\r
  64     MBEDTLS_MD_SHA224,    /**< The SHA-224 message digest. */\r
  65     MBEDTLS_MD_SHA256,    /**< The SHA-256 message digest. */\r
  66     MBEDTLS_MD_SHA384,    /**< The SHA-384 message digest. */\r
  67     MBEDTLS_MD_SHA512,    /**< The SHA-512 message digest. */\r
  68     MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */\r
  69 } mbedtls_md_type_t;\r
  70 \r
  71 #if defined(MBEDTLS_SHA512_C)\r
  72 #define MBEDTLS_MD_MAX_SIZE         64  /* longest known is SHA512 */\r
  73 #else\r
  74 #define MBEDTLS_MD_MAX_SIZE         32  /* longest known is SHA256 or less */\r
  75 #endif\r
  76 \r
  77 #if defined(MBEDTLS_SHA512_C)\r
  78 #define MBEDTLS_MD_MAX_BLOCK_SIZE         128\r
  79 #else\r
  80 #define MBEDTLS_MD_MAX_BLOCK_SIZE         64\r
  81 #endif\r
  82 \r
  83 /**\r
  84  * Opaque struct defined in md_internal.h.\r
  85  */\r
  86 typedef struct mbedtls_md_info_t mbedtls_md_info_t;\r
  87 \r
  88 /**\r
  89  * The generic message-digest context.\r
  90  */\r
  91 typedef struct mbedtls_md_context_t\r
  92 {\r
  93     /** Information about the associated message digest. */\r
  94     const mbedtls_md_info_t *md_info;\r
  95 \r
  96     /** The digest-specific context. */\r
  97     void *md_ctx;\r
  98 \r
  99     /** The HMAC part of the context. */\r
 100     void *hmac_ctx;\r
 101 } mbedtls_md_context_t;\r
 102 \r
 103 /**\r
 104  * \brief           This function returns the list of digests supported by the\r
 105  *                  generic digest module.\r
 106  *\r
 107  * \return          A statically allocated array of digests. Each element\r
 108  *                  in the returned list is an integer belonging to the\r
 109  *                  message-digest enumeration #mbedtls_md_type_t.\r
 110  *                  The last entry is 0.\r
 111  */\r
 112 const int *mbedtls_md_list( void );\r
 113 \r
 114 /**\r
 115  * \brief           This function returns the message-digest information\r
 116  *                  associated with the given digest name.\r
 117  *\r
 118  * \param md_name   The name of the digest to search for.\r
 119  *\r
 120  * \return          The message-digest information associated with \p md_name.\r
 121  * \return          NULL if the associated message-digest information is not found.\r
 122  */\r
 123 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );\r
 124 \r
 125 /**\r
 126  * \brief           This function returns the message-digest information\r
 127  *                  associated with the given digest type.\r
 128  *\r
 129  * \param md_type   The type of digest to search for.\r
 130  *\r
 131  * \return          The message-digest information associated with \p md_type.\r
 132  * \return          NULL if the associated message-digest information is not found.\r
 133  */\r
 134 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );\r
 135 \r
 136 /**\r
 137  * \brief           This function initializes a message-digest context without\r
 138  *                  binding it to a particular message-digest algorithm.\r
 139  *\r
 140  *                  This function should always be called first. It prepares the\r
 141  *                  context for mbedtls_md_setup() for binding it to a\r
 142  *                  message-digest algorithm.\r
 143  */\r
 144 void mbedtls_md_init( mbedtls_md_context_t *ctx );\r
 145 \r
 146 /**\r
 147  * \brief           This function clears the internal structure of \p ctx and\r
 148  *                  frees any embedded internal structure, but does not free\r
 149  *                  \p ctx itself.\r
 150  *\r
 151  *                  If you have called mbedtls_md_setup() on \p ctx, you must\r
 152  *                  call mbedtls_md_free() when you are no longer using the\r
 153  *                  context.\r
 154  *                  Calling this function if you have previously\r
 155  *                  called mbedtls_md_init() and nothing else is optional.\r
 156  *                  You must not call this function if you have not called\r
 157  *                  mbedtls_md_init().\r
 158  */\r
 159 void mbedtls_md_free( mbedtls_md_context_t *ctx );\r
 160 \r
 161 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)\r
 162 #if defined(MBEDTLS_DEPRECATED_WARNING)\r
 163 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))\r
 164 #else\r
 165 #define MBEDTLS_DEPRECATED\r
 166 #endif\r
 167 /**\r
 168  * \brief           This function selects the message digest algorithm to use,\r
 169  *                  and allocates internal structures.\r
 170  *\r
 171  *                  It should be called after mbedtls_md_init() or mbedtls_md_free().\r
 172  *                  Makes it necessary to call mbedtls_md_free() later.\r
 173  *\r
 174  * \deprecated      Superseded by mbedtls_md_setup() in 2.0.0\r
 175  *\r
 176  * \param ctx       The context to set up.\r
 177  * \param md_info   The information structure of the message-digest algorithm\r
 178  *                  to use.\r
 179  *\r
 180  * \return          \c 0 on success.\r
 181  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 182  *                  failure.\r
 183  * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.\r
 184  */\r
 185 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;\r
 186 #undef MBEDTLS_DEPRECATED\r
 187 #endif /* MBEDTLS_DEPRECATED_REMOVED */\r
 188 \r
 189 /**\r
 190  * \brief           This function selects the message digest algorithm to use,\r
 191  *                  and allocates internal structures.\r
 192  *\r
 193  *                  It should be called after mbedtls_md_init() or\r
 194  *                  mbedtls_md_free(). Makes it necessary to call\r
 195  *                  mbedtls_md_free() later.\r
 196  *\r
 197  * \param ctx       The context to set up.\r
 198  * \param md_info   The information structure of the message-digest algorithm\r
 199  *                  to use.\r
 200  * \param hmac      Defines if HMAC is used. 0: HMAC is not used (saves some memory),\r
 201  *                  or non-zero: HMAC is used with this context.\r
 202  *\r
 203  * \return          \c 0 on success.\r
 204  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 205  *                  failure.\r
 206  * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.\r
 207  */\r
 208 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );\r
 209 \r
 210 /**\r
 211  * \brief           This function clones the state of an message-digest\r
 212  *                  context.\r
 213  *\r
 214  * \note            You must call mbedtls_md_setup() on \c dst before calling\r
 215  *                  this function.\r
 216  *\r
 217  * \note            The two contexts must have the same type,\r
 218  *                  for example, both are SHA-256.\r
 219  *\r
 220  * \warning         This function clones the message-digest state, not the\r
 221  *                  HMAC state.\r
 222  *\r
 223  * \param dst       The destination context.\r
 224  * \param src       The context to be cloned.\r
 225  *\r
 226  * \return          \c 0 on success.\r
 227  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.\r
 228  */\r
 229 int mbedtls_md_clone( mbedtls_md_context_t *dst,\r
 230                       const mbedtls_md_context_t *src );\r
 231 \r
 232 /**\r
 233  * \brief           This function extracts the message-digest size from the\r
 234  *                  message-digest information structure.\r
 235  *\r
 236  * \param md_info   The information structure of the message-digest algorithm\r
 237  *                  to use.\r
 238  *\r
 239  * \return          The size of the message-digest output in Bytes.\r
 240  */\r
 241 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );\r
 242 \r
 243 /**\r
 244  * \brief           This function extracts the message-digest type from the\r
 245  *                  message-digest information structure.\r
 246  *\r
 247  * \param md_info   The information structure of the message-digest algorithm\r
 248  *                  to use.\r
 249  *\r
 250  * \return          The type of the message digest.\r
 251  */\r
 252 mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );\r
 253 \r
 254 /**\r
 255  * \brief           This function extracts the message-digest name from the\r
 256  *                  message-digest information structure.\r
 257  *\r
 258  * \param md_info   The information structure of the message-digest algorithm\r
 259  *                  to use.\r
 260  *\r
 261  * \return          The name of the message digest.\r
 262  */\r
 263 const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );\r
 264 \r
 265 /**\r
 266  * \brief           This function starts a message-digest computation.\r
 267  *\r
 268  *                  You must call this function after setting up the context\r
 269  *                  with mbedtls_md_setup(), and before passing data with\r
 270  *                  mbedtls_md_update().\r
 271  *\r
 272  * \param ctx       The generic message-digest context.\r
 273  *\r
 274  * \return          \c 0 on success.\r
 275  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 276  *                  failure.\r
 277  */\r
 278 int mbedtls_md_starts( mbedtls_md_context_t *ctx );\r
 279 \r
 280 /**\r
 281  * \brief           This function feeds an input buffer into an ongoing\r
 282  *                  message-digest computation.\r
 283  *\r
 284  *                  You must call mbedtls_md_starts() before calling this\r
 285  *                  function. You may call this function multiple times.\r
 286  *                  Afterwards, call mbedtls_md_finish().\r
 287  *\r
 288  * \param ctx       The generic message-digest context.\r
 289  * \param input     The buffer holding the input data.\r
 290  * \param ilen      The length of the input data.\r
 291  *\r
 292  * \return          \c 0 on success.\r
 293  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 294  *                  failure.\r
 295  */\r
 296 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );\r
 297 \r
 298 /**\r
 299  * \brief           This function finishes the digest operation,\r
 300  *                  and writes the result to the output buffer.\r
 301  *\r
 302  *                  Call this function after a call to mbedtls_md_starts(),\r
 303  *                  followed by any number of calls to mbedtls_md_update().\r
 304  *                  Afterwards, you may either clear the context with\r
 305  *                  mbedtls_md_free(), or call mbedtls_md_starts() to reuse\r
 306  *                  the context for another digest operation with the same\r
 307  *                  algorithm.\r
 308  *\r
 309  * \param ctx       The generic message-digest context.\r
 310  * \param output    The buffer for the generic message-digest checksum result.\r
 311  *\r
 312  * \return          \c 0 on success.\r
 313  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 314  *                  failure.\r
 315  */\r
 316 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );\r
 317 \r
 318 /**\r
 319  * \brief          This function calculates the message-digest of a buffer,\r
 320  *                 with respect to a configurable message-digest algorithm\r
 321  *                 in a single call.\r
 322  *\r
 323  *                 The result is calculated as\r
 324  *                 Output = message_digest(input buffer).\r
 325  *\r
 326  * \param md_info  The information structure of the message-digest algorithm\r
 327  *                 to use.\r
 328  * \param input    The buffer holding the data.\r
 329  * \param ilen     The length of the input data.\r
 330  * \param output   The generic message-digest checksum result.\r
 331  *\r
 332  * \return         \c 0 on success.\r
 333  * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 334  *                 failure.\r
 335  */\r
 336 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,\r
 337         unsigned char *output );\r
 338 \r
 339 #if defined(MBEDTLS_FS_IO)\r
 340 /**\r
 341  * \brief          This function calculates the message-digest checksum\r
 342  *                 result of the contents of the provided file.\r
 343  *\r
 344  *                 The result is calculated as\r
 345  *                 Output = message_digest(file contents).\r
 346  *\r
 347  * \param md_info  The information structure of the message-digest algorithm\r
 348  *                 to use.\r
 349  * \param path     The input file name.\r
 350  * \param output   The generic message-digest checksum result.\r
 351  *\r
 352  * \return         \c 0 on success.\r
 353  * \return         #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing\r
 354  *                 the file pointed by \p path.\r
 355  * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.\r
 356  */\r
 357 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,\r
 358                      unsigned char *output );\r
 359 #endif /* MBEDTLS_FS_IO */\r
 360 \r
 361 /**\r
 362  * \brief           This function sets the HMAC key and prepares to\r
 363  *                  authenticate a new message.\r
 364  *\r
 365  *                  Call this function after mbedtls_md_setup(), to use\r
 366  *                  the MD context for an HMAC calculation, then call\r
 367  *                  mbedtls_md_hmac_update() to provide the input data, and\r
 368  *                  mbedtls_md_hmac_finish() to get the HMAC value.\r
 369  *\r
 370  * \param ctx       The message digest context containing an embedded HMAC\r
 371  *                  context.\r
 372  * \param key       The HMAC secret key.\r
 373  * \param keylen    The length of the HMAC key in Bytes.\r
 374  *\r
 375  * \return          \c 0 on success.\r
 376  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 377  *                  failure.\r
 378  */\r
 379 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,\r
 380                     size_t keylen );\r
 381 \r
 382 /**\r
 383  * \brief           This function feeds an input buffer into an ongoing HMAC\r
 384  *                  computation.\r
 385  *\r
 386  *                  Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()\r
 387  *                  before calling this function.\r
 388  *                  You may call this function multiple times to pass the\r
 389  *                  input piecewise.\r
 390  *                  Afterwards, call mbedtls_md_hmac_finish().\r
 391  *\r
 392  * \param ctx       The message digest context containing an embedded HMAC\r
 393  *                  context.\r
 394  * \param input     The buffer holding the input data.\r
 395  * \param ilen      The length of the input data.\r
 396  *\r
 397  * \return          \c 0 on success.\r
 398  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 399  *                  failure.\r
 400  */\r
 401 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,\r
 402                     size_t ilen );\r
 403 \r
 404 /**\r
 405  * \brief           This function finishes the HMAC operation, and writes\r
 406  *                  the result to the output buffer.\r
 407  *\r
 408  *                  Call this function after mbedtls_md_hmac_starts() and\r
 409  *                  mbedtls_md_hmac_update() to get the HMAC value. Afterwards\r
 410  *                  you may either call mbedtls_md_free() to clear the context,\r
 411  *                  or call mbedtls_md_hmac_reset() to reuse the context with\r
 412  *                  the same HMAC key.\r
 413  *\r
 414  * \param ctx       The message digest context containing an embedded HMAC\r
 415  *                  context.\r
 416  * \param output    The generic HMAC checksum result.\r
 417  *\r
 418  * \return          \c 0 on success.\r
 419  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 420  *                  failure.\r
 421  */\r
 422 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);\r
 423 \r
 424 /**\r
 425  * \brief           This function prepares to authenticate a new message with\r
 426  *                  the same key as the previous HMAC operation.\r
 427  *\r
 428  *                  You may call this function after mbedtls_md_hmac_finish().\r
 429  *                  Afterwards call mbedtls_md_hmac_update() to pass the new\r
 430  *                  input.\r
 431  *\r
 432  * \param ctx       The message digest context containing an embedded HMAC\r
 433  *                  context.\r
 434  *\r
 435  * \return          \c 0 on success.\r
 436  * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 437  *                  failure.\r
 438  */\r
 439 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );\r
 440 \r
 441 /**\r
 442  * \brief          This function calculates the full generic HMAC\r
 443  *                 on the input buffer with the provided key.\r
 444  *\r
 445  *                 The function allocates the context, performs the\r
 446  *                 calculation, and frees the context.\r
 447  *\r
 448  *                 The HMAC result is calculated as\r
 449  *                 output = generic HMAC(hmac key, input buffer).\r
 450  *\r
 451  * \param md_info  The information structure of the message-digest algorithm\r
 452  *                 to use.\r
 453  * \param key      The HMAC secret key.\r
 454  * \param keylen   The length of the HMAC secret key in Bytes.\r
 455  * \param input    The buffer holding the input data.\r
 456  * \param ilen     The length of the input data.\r
 457  * \param output   The generic HMAC result.\r
 458  *\r
 459  * \return         \c 0 on success.\r
 460  * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification\r
 461  *                 failure.\r
 462  */\r
 463 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,\r
 464                 const unsigned char *input, size_t ilen,\r
 465                 unsigned char *output );\r
 466 \r
 467 /* Internal use */\r
 468 int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data );\r
 469 \r
 470 #ifdef __cplusplus\r
 471 }\r
 472 #endif\r
 473 \r
 474 #endif /* MBEDTLS_MD_H */\r