third_party/mbedtls/repo/include/mbedtls/sha512.h

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