sha512.h

00001 /**
00002  * \file sha512.h
00003  * \brief This file contains SHA-384 and SHA-512 definitions and functions.
00004  *
00005  * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
00006  * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
00007  */
00008 /*
00009  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00010  *  SPDX-License-Identifier: Apache-2.0
00011  *
00012  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00013  *  not use this file except in compliance with the License.
00014  *  You may obtain a copy of the License at
00015  *
00016  *  http://www.apache.org/licenses/LICENSE-2.0
00017  *
00018  *  Unless required by applicable law or agreed to in writing, software
00019  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00020  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00021  *  See the License for the specific language governing permissions and
00022  *  limitations under the License.
00023  *
00024  *  This file is part of Mbed TLS (https://tls.mbed.org)
00025  */
00026 #ifndef MBEDTLS_SHA512_H
00027 #define MBEDTLS_SHA512_H
00028 
00029 #if !defined(MBEDTLS_CONFIG_FILE)
00030 #include "mbedtls/config.h"
00031 #else
00032 #include MBEDTLS_CONFIG_FILE
00033 #endif
00034 
00035 #include <stddef.h>
00036 #include <stdint.h>
00037 
00038 /* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
00039 #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */
00040 #define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA                 -0x0075  /**< SHA-512 input data was malformed. */
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 #if !defined(MBEDTLS_SHA512_ALT)
00047 // Regular implementation
00048 //
00049 
00050 /**
00051  * \brief          The SHA-512 context structure.
00052  *
00053  *                 The structure is used both for SHA-384 and for SHA-512
00054  *                 checksum calculations. The choice between these two is
00055  *                 made in the call to mbedtls_sha512_starts_ret().
00056  */
00057 typedef struct mbedtls_sha512_context
00058 {
00059     uint64_t total [2];          /*!< The number of Bytes processed. */
00060     uint64_t state [8];          /*!< The intermediate digest state. */
00061     unsigned char buffer[128];  /*!< The data block being processed. */
00062     int is384 ;                  /*!< Determines which function to use:
00063                                      0: Use SHA-512, or 1: Use SHA-384. */
00064 }
00065 mbedtls_sha512_context;
00066 
00067 #else  /* MBEDTLS_SHA512_ALT */
00068 #include "sha512_alt.h"
00069 #endif /* MBEDTLS_SHA512_ALT */
00070 
00071 /**
00072  * \brief          This function initializes a SHA-512 context.
00073  *
00074  * \param ctx      The SHA-512 context to initialize. This must
00075  *                 not be \c NULL.
00076  */
00077 void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
00078 
00079 /**
00080  * \brief          This function clears a SHA-512 context.
00081  *
00082  * \param ctx      The SHA-512 context to clear. This may be \c NULL,
00083  *                 in which case this function does nothing. If it
00084  *                 is not \c NULL, it must point to an initialized
00085  *                 SHA-512 context.
00086  */
00087 void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
00088 
00089 /**
00090  * \brief          This function clones the state of a SHA-512 context.
00091  *
00092  * \param dst      The destination context. This must be initialized.
00093  * \param src      The context to clone. This must be initialized.
00094  */
00095 void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
00096                            const mbedtls_sha512_context *src );
00097 
00098 /**
00099  * \brief          This function starts a SHA-384 or SHA-512 checksum
00100  *                 calculation.
00101  *
00102  * \param ctx      The SHA-512 context to use. This must be initialized.
00103  * \param is384    Determines which function to use. This must be
00104  *                 either \c for SHA-512, or \c 1 for SHA-384.
00105  *
00106  * \return         \c 0 on success.
00107  * \return         A negative error code on failure.
00108  */
00109 int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
00110 
00111 /**
00112  * \brief          This function feeds an input buffer into an ongoing
00113  *                 SHA-512 checksum calculation.
00114  *
00115  * \param ctx      The SHA-512 context. This must be initialized
00116  *                 and have a hash operation started.
00117  * \param input    The buffer holding the input data. This must
00118  *                 be a readable buffer of length \p ilen Bytes.
00119  * \param ilen     The length of the input data in Bytes.
00120  *
00121  * \return         \c 0 on success.
00122  * \return         A negative error code on failure.
00123  */
00124 int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
00125                     const unsigned char *input,
00126                     size_t ilen );
00127 
00128 /**
00129  * \brief          This function finishes the SHA-512 operation, and writes
00130  *                 the result to the output buffer. This function is for
00131  *                 internal use only.
00132  *
00133  * \param ctx      The SHA-512 context. This must be initialized
00134  *                 and have a hash operation started.
00135  * \param output   The SHA-384 or SHA-512 checksum result.
00136  *                 This must be a writable buffer of length \c 64 Bytes.
00137  *
00138  * \return         \c 0 on success.
00139  * \return         A negative error code on failure.
00140  */
00141 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
00142                                unsigned char output[64] );
00143 
00144 /**
00145  * \brief          This function processes a single data block within
00146  *                 the ongoing SHA-512 computation.
00147  *
00148  * \param ctx      The SHA-512 context. This must be initialized.
00149  * \param data     The buffer holding one block of data. This
00150  *                 must be a readable buffer of length \c 128 Bytes.
00151  *
00152  * \return         \c 0 on success.
00153  * \return         A negative error code on failure.
00154  */
00155 int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
00156                                      const unsigned char data[128] );
00157 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00158 #if defined(MBEDTLS_DEPRECATED_WARNING)
00159 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00160 #else
00161 #define MBEDTLS_DEPRECATED
00162 #endif
00163 /**
00164  * \brief          This function starts a SHA-384 or SHA-512 checksum
00165  *                 calculation.
00166  *
00167  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
00168  *
00169  * \param ctx      The SHA-512 context to use. This must be initialized.
00170  * \param is384    Determines which function to use. This must be either
00171  *                 \c 0 for SHA-512 or \c 1 for SHA-384.
00172  */
00173 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
00174                                                int is384 );
00175 
00176 /**
00177  * \brief          This function feeds an input buffer into an ongoing
00178  *                 SHA-512 checksum calculation.
00179  *
00180  * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.
00181  *
00182  * \param ctx      The SHA-512 context. This must be initialized
00183  *                 and have a hash operation started.
00184  * \param input    The buffer holding the data. This must be a readable
00185  *                 buffer of length \p ilen Bytes.
00186  * \param ilen     The length of the input data in Bytes.
00187  */
00188 MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
00189                                                const unsigned char *input,
00190                                                size_t ilen );
00191 
00192 /**
00193  * \brief          This function finishes the SHA-512 operation, and writes
00194  *                 the result to the output buffer.
00195  *
00196  * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
00197  *
00198  * \param ctx      The SHA-512 context. This must be initialized
00199  *                 and have a hash operation started.
00200  * \param output   The SHA-384 or SHA-512 checksum result. This must
00201  *                 be a writable buffer of size \c 64 Bytes.
00202  */
00203 MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
00204                                                unsigned char output[64] );
00205 
00206 /**
00207  * \brief          This function processes a single data block within
00208  *                 the ongoing SHA-512 computation. This function is for
00209  *                 internal use only.
00210  *
00211  * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0.
00212  *
00213  * \param ctx      The SHA-512 context. This must be initialized.
00214  * \param data     The buffer holding one block of data. This must be
00215  *                 a readable buffer of length \c 128 Bytes.
00216  */
00217 MBEDTLS_DEPRECATED void mbedtls_sha512_process(
00218                                             mbedtls_sha512_context *ctx,
00219                                             const unsigned char data[128] );
00220 
00221 #undef MBEDTLS_DEPRECATED
00222 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00223 
00224 /**
00225  * \brief          This function calculates the SHA-512 or SHA-384
00226  *                 checksum of a buffer.
00227  *
00228  *                 The function allocates the context, performs the
00229  *                 calculation, and frees the context.
00230  *
00231  *                 The SHA-512 result is calculated as
00232  *                 output = SHA-512(input buffer).
00233  *
00234  * \param input    The buffer holding the input data. This must be
00235  *                 a readable buffer of length \p ilen Bytes.
00236  * \param ilen     The length of the input data in Bytes.
00237  * \param output   The SHA-384 or SHA-512 checksum result.
00238  *                 This must be a writable buffer of length \c 64 Bytes.
00239  * \param is384    Determines which function to use. This must be either
00240  *                 \c 0 for SHA-512, or \c 1 for SHA-384.
00241  *
00242  * \return         \c 0 on success.
00243  * \return         A negative error code on failure.
00244  */
00245 int mbedtls_sha512_ret( const unsigned char *input,
00246                         size_t ilen,
00247                         unsigned char output[64],
00248                         int is384 );
00249 
00250 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00251 #if defined(MBEDTLS_DEPRECATED_WARNING)
00252 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00253 #else
00254 #define MBEDTLS_DEPRECATED
00255 #endif
00256 
00257 /**
00258  * \brief          This function calculates the SHA-512 or SHA-384
00259  *                 checksum of a buffer.
00260  *
00261  *                 The function allocates the context, performs the
00262  *                 calculation, and frees the context.
00263  *
00264  *                 The SHA-512 result is calculated as
00265  *                 output = SHA-512(input buffer).
00266  *
00267  * \deprecated     Superseded by mbedtls_sha512_ret() in 2.7.0
00268  *
00269  * \param input    The buffer holding the data. This must be a
00270  *                 readable buffer of length \p ilen Bytes.
00271  * \param ilen     The length of the input data in Bytes.
00272  * \param output   The SHA-384 or SHA-512 checksum result. This must
00273  *                 be a writable buffer of length \c 64 Bytes.
00274  * \param is384    Determines which function to use. This must be either
00275  *                 \c 0 for SHA-512, or \c 1 for SHA-384.
00276  */
00277 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
00278                                         size_t ilen,
00279                                         unsigned char output[64],
00280                                         int is384 );
00281 
00282 #undef MBEDTLS_DEPRECATED
00283 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00284 
00285 #if defined(MBEDTLS_SELF_TEST)
00286 
00287  /**
00288  * \brief          The SHA-384 or SHA-512 checkup routine.
00289  *
00290  * \return         \c 0 on success.
00291  * \return         \c 1 on failure.
00292  */
00293 int mbedtls_sha512_self_test( int verbose );
00294 #endif /* MBEDTLS_SELF_TEST */
00295 
00296 #ifdef __cplusplus
00297 }
00298 #endif
00299 
00300 #endif /* mbedtls_sha512.h */