sdk/include/reactos/libs/mbedtls/md.h

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