sha256.h

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