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

   1 /**\r
   2  * \file sha512.h\r
   3  * \brief This file contains SHA-384 and SHA-512 definitions and functions.\r
   4  *\r
   5  * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic\r
   6  * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.\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 #ifndef MBEDTLS_SHA512_H\r
  27 #define MBEDTLS_SHA512_H\r
  28 \r
  29 #if !defined(MBEDTLS_CONFIG_FILE)\r
  30 #include "config.h"\r
  31 #else\r
  32 #include MBEDTLS_CONFIG_FILE\r
  33 #endif\r
  34 \r
  35 #include <stddef.h>\r
  36 #include <stdint.h>\r
  37 \r
  38 /* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */\r
  39 #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */\r
  40 #define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA                 -0x0075  /**< SHA-512 input data was malformed. */\r
  41 \r
  42 #ifdef __cplusplus\r
  43 extern "C" {\r
  44 #endif\r
  45 \r
  46 #if !defined(MBEDTLS_SHA512_ALT)\r
  47 // Regular implementation\r
  48 //\r
  49 \r
  50 /**\r
  51  * \brief          The SHA-512 context structure.\r
  52  *\r
  53  *                 The structure is used both for SHA-384 and for SHA-512\r
  54  *                 checksum calculations. The choice between these two is\r
  55  *                 made in the call to mbedtls_sha512_starts_ret().\r
  56  */\r
  57 typedef struct mbedtls_sha512_context\r
  58 {\r
  59     uint64_t total[2];          /*!< The number of Bytes processed. */\r
  60     uint64_t state[8];          /*!< The intermediate digest state. */\r
  61     unsigned char buffer[128];  /*!< The data block being processed. */\r
  62     int is384;                  /*!< Determines which function to use:\r
  63                                      0: Use SHA-512, or 1: Use SHA-384. */\r
  64 }\r
  65 mbedtls_sha512_context;\r
  66 \r
  67 #else  /* MBEDTLS_SHA512_ALT */\r
  68 #include "sha512_alt.h"\r
  69 #endif /* MBEDTLS_SHA512_ALT */\r
  70 \r
  71 /**\r
  72  * \brief          This function initializes a SHA-512 context.\r
  73  *\r
  74  * \param ctx      The SHA-512 context to initialize. This must\r
  75  *                 not be \c NULL.\r
  76  */\r
  77 void mbedtls_sha512_init( mbedtls_sha512_context *ctx );\r
  78 \r
  79 /**\r
  80  * \brief          This function clears a SHA-512 context.\r
  81  *\r
  82  * \param ctx      The SHA-512 context to clear. This may be \c NULL,\r
  83  *                 in which case this function does nothing. If it\r
  84  *                 is not \c NULL, it must point to an initialized\r
  85  *                 SHA-512 context.\r
  86  */\r
  87 void mbedtls_sha512_free( mbedtls_sha512_context *ctx );\r
  88 \r
  89 /**\r
  90  * \brief          This function clones the state of a SHA-512 context.\r
  91  *\r
  92  * \param dst      The destination context. This must be initialized.\r
  93  * \param src      The context to clone. This must be initialized.\r
  94  */\r
  95 void mbedtls_sha512_clone( mbedtls_sha512_context *dst,\r
  96                            const mbedtls_sha512_context *src );\r
  97 \r
  98 /**\r
  99  * \brief          This function starts a SHA-384 or SHA-512 checksum\r
 100  *                 calculation.\r
 101  *\r
 102  * \param ctx      The SHA-512 context to use. This must be initialized.\r
 103  * \param is384    Determines which function to use. This must be\r
 104  *                 either \c for SHA-512, or \c 1 for SHA-384.\r
 105  *\r
 106  * \return         \c 0 on success.\r
 107  * \return         A negative error code on failure.\r
 108  */\r
 109 int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );\r
 110 \r
 111 /**\r
 112  * \brief          This function feeds an input buffer into an ongoing\r
 113  *                 SHA-512 checksum calculation.\r
 114  *\r
 115  * \param ctx      The SHA-512 context. This must be initialized\r
 116  *                 and have a hash operation started.\r
 117  * \param input    The buffer holding the input data. This must\r
 118  *                 be a readable buffer of length \p ilen Bytes.\r
 119  * \param ilen     The length of the input data in Bytes.\r
 120  *\r
 121  * \return         \c 0 on success.\r
 122  * \return         A negative error code on failure.\r
 123  */\r
 124 int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,\r
 125                     const unsigned char *input,\r
 126                     size_t ilen );\r
 127 \r
 128 /**\r
 129  * \brief          This function finishes the SHA-512 operation, and writes\r
 130  *                 the result to the output buffer. This function is for\r
 131  *                 internal use only.\r
 132  *\r
 133  * \param ctx      The SHA-512 context. This must be initialized\r
 134  *                 and have a hash operation started.\r
 135  * \param output   The SHA-384 or SHA-512 checksum result.\r
 136  *                 This must be a writable buffer of length \c 64 Bytes.\r
 137  *\r
 138  * \return         \c 0 on success.\r
 139  * \return         A negative error code on failure.\r
 140  */\r
 141 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,\r
 142                                unsigned char output[64] );\r
 143 \r
 144 /**\r
 145  * \brief          This function processes a single data block within\r
 146  *                 the ongoing SHA-512 computation.\r
 147  *\r
 148  * \param ctx      The SHA-512 context. This must be initialized.\r
 149  * \param data     The buffer holding one block of data. This\r
 150  *                 must be a readable buffer of length \c 128 Bytes.\r
 151  *\r
 152  * \return         \c 0 on success.\r
 153  * \return         A negative error code on failure.\r
 154  */\r
 155 int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,\r
 156                                      const unsigned char data[128] );\r
 157 #if !defined(MBEDTLS_DEPRECATED_REMOVED)\r
 158 #if defined(MBEDTLS_DEPRECATED_WARNING)\r
 159 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))\r
 160 #else\r
 161 #define MBEDTLS_DEPRECATED\r
 162 #endif\r
 163 /**\r
 164  * \brief          This function starts a SHA-384 or SHA-512 checksum\r
 165  *                 calculation.\r
 166  *\r
 167  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0\r
 168  *\r
 169  * \param ctx      The SHA-512 context to use. This must be initialized.\r
 170  * \param is384    Determines which function to use. This must be either\r
 171  *                 \c 0 for SHA-512 or \c 1 for SHA-384.\r
 172  */\r
 173 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,\r
 174                                                int is384 );\r
 175 \r
 176 /**\r
 177  * \brief          This function feeds an input buffer into an ongoing\r
 178  *                 SHA-512 checksum calculation.\r
 179  *\r
 180  * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.\r
 181  *\r
 182  * \param ctx      The SHA-512 context. This must be initialized\r
 183  *                 and have a hash operation started.\r
 184  * \param input    The buffer holding the data. This must be a readable\r
 185  *                 buffer of length \p ilen Bytes.\r
 186  * \param ilen     The length of the input data in Bytes.\r
 187  */\r
 188 MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,\r
 189                                                const unsigned char *input,\r
 190                                                size_t ilen );\r
 191 \r
 192 /**\r
 193  * \brief          This function finishes the SHA-512 operation, and writes\r
 194  *                 the result to the output buffer.\r
 195  *\r
 196  * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0.\r
 197  *\r
 198  * \param ctx      The SHA-512 context. This must be initialized\r
 199  *                 and have a hash operation started.\r
 200  * \param output   The SHA-384 or SHA-512 checksum result. This must\r
 201  *                 be a writable buffer of size \c 64 Bytes.\r
 202  */\r
 203 MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,\r
 204                                                unsigned char output[64] );\r
 205 \r
 206 /**\r
 207  * \brief          This function processes a single data block within\r
 208  *                 the ongoing SHA-512 computation. This function is for\r
 209  *                 internal use only.\r
 210  *\r
 211  * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0.\r
 212  *\r
 213  * \param ctx      The SHA-512 context. This must be initialized.\r
 214  * \param data     The buffer holding one block of data. This must be\r
 215  *                 a readable buffer of length \c 128 Bytes.\r
 216  */\r
 217 MBEDTLS_DEPRECATED void mbedtls_sha512_process(\r
 218                                             mbedtls_sha512_context *ctx,\r
 219                                             const unsigned char data[128] );\r
 220 \r
 221 #undef MBEDTLS_DEPRECATED\r
 222 #endif /* !MBEDTLS_DEPRECATED_REMOVED */\r
 223 \r
 224 /**\r
 225  * \brief          This function calculates the SHA-512 or SHA-384\r
 226  *                 checksum of a buffer.\r
 227  *\r
 228  *                 The function allocates the context, performs the\r
 229  *                 calculation, and frees the context.\r
 230  *\r
 231  *                 The SHA-512 result is calculated as\r
 232  *                 output = SHA-512(input buffer).\r
 233  *\r
 234  * \param input    The buffer holding the input data. This must be\r
 235  *                 a readable buffer of length \p ilen Bytes.\r
 236  * \param ilen     The length of the input data in Bytes.\r
 237  * \param output   The SHA-384 or SHA-512 checksum result.\r
 238  *                 This must be a writable buffer of length \c 64 Bytes.\r
 239  * \param is384    Determines which function to use. This must be either\r
 240  *                 \c 0 for SHA-512, or \c 1 for SHA-384.\r
 241  *\r
 242  * \return         \c 0 on success.\r
 243  * \return         A negative error code on failure.\r
 244  */\r
 245 int mbedtls_sha512_ret( const unsigned char *input,\r
 246                         size_t ilen,\r
 247                         unsigned char output[64],\r
 248                         int is384 );\r
 249 \r
 250 #if !defined(MBEDTLS_DEPRECATED_REMOVED)\r
 251 #if defined(MBEDTLS_DEPRECATED_WARNING)\r
 252 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))\r
 253 #else\r
 254 #define MBEDTLS_DEPRECATED\r
 255 #endif\r
 256 \r
 257 /**\r
 258  * \brief          This function calculates the SHA-512 or SHA-384\r
 259  *                 checksum of a buffer.\r
 260  *\r
 261  *                 The function allocates the context, performs the\r
 262  *                 calculation, and frees the context.\r
 263  *\r
 264  *                 The SHA-512 result is calculated as\r
 265  *                 output = SHA-512(input buffer).\r
 266  *\r
 267  * \deprecated     Superseded by mbedtls_sha512_ret() in 2.7.0\r
 268  *\r
 269  * \param input    The buffer holding the data. This must be a\r
 270  *                 readable buffer of length \p ilen Bytes.\r
 271  * \param ilen     The length of the input data in Bytes.\r
 272  * \param output   The SHA-384 or SHA-512 checksum result. This must\r
 273  *                 be a writable buffer of length \c 64 Bytes.\r
 274  * \param is384    Determines which function to use. This must be either\r
 275  *                 \c 0 for SHA-512, or \c 1 for SHA-384.\r
 276  */\r
 277 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,\r
 278                                         size_t ilen,\r
 279                                         unsigned char output[64],\r
 280                                         int is384 );\r
 281 \r
 282 #undef MBEDTLS_DEPRECATED\r
 283 #endif /* !MBEDTLS_DEPRECATED_REMOVED */\r
 284 \r
 285 #if defined(MBEDTLS_SELF_TEST)\r
 286 \r
 287  /**\r
 288  * \brief          The SHA-384 or SHA-512 checkup routine.\r
 289  *\r
 290  * \return         \c 0 on success.\r
 291  * \return         \c 1 on failure.\r
 292  */\r
 293 int mbedtls_sha512_self_test( int verbose );\r
 294 #endif /* MBEDTLS_SELF_TEST */\r
 295 \r
 296 #ifdef __cplusplus\r
 297 }\r
 298 #endif\r
 299 \r
 300 #endif /* mbedtls_sha512.h */\r