sha1.h

00001 /**
00002  * \file sha1.h
00003  *
00004  * \brief The SHA-1 cryptographic hash function.
00005  *
00006  * \warning   SHA-1 is considered a weak message digest and its use constitutes
00007  *            a security risk. We recommend considering stronger message
00008  *            digests instead.
00009  */
00010 /*
00011  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00012  *  SPDX-License-Identifier: Apache-2.0
00013  *
00014  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00015  *  not use this file except in compliance with the License.
00016  *  You may obtain a copy of the License at
00017  *
00018  *  http://www.apache.org/licenses/LICENSE-2.0
00019  *
00020  *  Unless required by applicable law or agreed to in writing, software
00021  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00022  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00023  *  See the License for the specific language governing permissions and
00024  *  limitations under the License.
00025  *
00026  *  This file is part of Mbed TLS (https://tls.mbed.org)
00027  */
00028 #ifndef MBEDTLS_SHA1_H
00029 #define MBEDTLS_SHA1_H
00030 
00031 #if !defined(MBEDTLS_CONFIG_FILE)
00032 #include "config.h"
00033 #else
00034 #include MBEDTLS_CONFIG_FILE
00035 #endif
00036 
00037 #include <stddef.h>
00038 #include <stdint.h>
00039 
00040 #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED                  -0x0035  /**< SHA-1 hardware accelerator failed */
00041 
00042 #if !defined(MBEDTLS_SHA1_ALT)
00043 // Regular implementation
00044 //
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /**
00051  * \brief          The SHA-1 context structure.
00052  *
00053  * \warning        SHA-1 is considered a weak message digest and its use
00054  *                 constitutes a security risk. We recommend considering
00055  *                 stronger message digests instead.
00056  *
00057  */
00058 typedef struct
00059 {
00060     uint32_t total[2];          /*!< The number of Bytes processed.  */
00061     uint32_t state[5];          /*!< The intermediate digest state.  */
00062     unsigned char buffer[64];   /*!< The data block being processed. */
00063 }
00064 mbedtls_sha1_context;
00065 
00066 /**
00067  * \brief          This function initializes a SHA-1 context.
00068  *
00069  * \param ctx      The SHA-1 context to initialize.
00070  *
00071  * \warning        SHA-1 is considered a weak message digest and its use
00072  *                 constitutes a security risk. We recommend considering
00073  *                 stronger message digests instead.
00074  *
00075  */
00076 void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
00077 
00078 /**
00079  * \brief          This function clears a SHA-1 context.
00080  *
00081  * \param ctx      The SHA-1 context to clear.
00082  *
00083  * \warning        SHA-1 is considered a weak message digest and its use
00084  *                 constitutes a security risk. We recommend considering
00085  *                 stronger message digests instead.
00086  *
00087  */
00088 void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
00089 
00090 /**
00091  * \brief          This function clones the state of a SHA-1 context.
00092  *
00093  * \param dst      The destination context.
00094  * \param src      The context to clone.
00095  *
00096  * \warning        SHA-1 is considered a weak message digest and its use
00097  *                 constitutes a security risk. We recommend considering
00098  *                 stronger message digests instead.
00099  *
00100  */
00101 void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
00102                          const mbedtls_sha1_context *src );
00103 
00104 /**
00105  * \brief          This function starts a SHA-1 checksum calculation.
00106  *
00107  * \param ctx      The context to initialize.
00108  *
00109  * \return         \c 0 if successful
00110  *
00111  * \warning        SHA-1 is considered a weak message digest and its use
00112  *                 constitutes a security risk. We recommend considering
00113  *                 stronger message digests instead.
00114  *
00115  */
00116 int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
00117 
00118 /**
00119  * \brief          This function feeds an input buffer into an ongoing SHA-1
00120  *                 checksum calculation.
00121  *
00122  * \param ctx      The SHA-1 context.
00123  * \param input    The buffer holding the input data.
00124  * \param ilen     The length of the input data.
00125  *
00126  * \return         \c 0 if successful
00127  *
00128  * \warning        SHA-1 is considered a weak message digest and its use
00129  *                 constitutes a security risk. We recommend considering
00130  *                 stronger message digests instead.
00131  *
00132  */
00133 int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
00134                              const unsigned char *input,
00135                              size_t ilen );
00136 
00137 /**
00138  * \brief          This function finishes the SHA-1 operation, and writes
00139  *                 the result to the output buffer.
00140  *
00141  * \param ctx      The SHA-1 context.
00142  * \param output   The SHA-1 checksum result.
00143  *
00144  * \return         \c 0 if successful
00145  *
00146  * \warning        SHA-1 is considered a weak message digest and its use
00147  *                 constitutes a security risk. We recommend considering
00148  *                 stronger message digests instead.
00149  *
00150  */
00151 int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
00152                              unsigned char output[20] );
00153 
00154 /**
00155  * \brief          SHA-1 process data block (internal use only)
00156  *
00157  * \param ctx      SHA-1 context
00158  * \param data     The data block being processed.
00159  *
00160  * \return         \c 0 if successful
00161  *
00162  * \warning        SHA-1 is considered a weak message digest and its use
00163  *                 constitutes a security risk. We recommend considering
00164  *                 stronger message digests instead.
00165  *
00166  */
00167 int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
00168                                    const unsigned char data[64] );
00169 
00170 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00171 #if defined(MBEDTLS_DEPRECATED_WARNING)
00172 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00173 #else
00174 #define MBEDTLS_DEPRECATED
00175 #endif
00176 /**
00177  * \brief          SHA-1 context setup
00178  *
00179  * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0
00180  *
00181  * \param ctx      The SHA-1 context to be initialized.
00182  *
00183  * \warning        SHA-1 is considered a weak message digest and its use
00184  *                 constitutes a security risk. We recommend considering
00185  *                 stronger message digests instead.
00186  *
00187  */
00188 MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
00189 
00190 /**
00191  * \brief          SHA-1 process buffer
00192  *
00193  * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0
00194  *
00195  * \param ctx      The SHA-1 context.
00196  * \param input    The buffer holding the input data.
00197  * \param ilen     The length of the input data.
00198  *
00199  * \warning        SHA-1 is considered a weak message digest and its use
00200  *                 constitutes a security risk. We recommend considering
00201  *                 stronger message digests instead.
00202  *
00203  */
00204 MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
00205                                              const unsigned char *input,
00206                                              size_t ilen );
00207 
00208 /**
00209  * \brief          SHA-1 final digest
00210  *
00211  * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0
00212  *
00213  * \param ctx      The SHA-1 context.
00214  * \param output   The SHA-1 checksum result.
00215  *
00216  * \warning        SHA-1 is considered a weak message digest and its use
00217  *                 constitutes a security risk. We recommend considering
00218  *                 stronger message digests instead.
00219  *
00220  */
00221 MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
00222                                              unsigned char output[20] );
00223 
00224 /**
00225  * \brief          SHA-1 process data block (internal use only)
00226  *
00227  * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0
00228  *
00229  * \param ctx      The SHA-1 context.
00230  * \param data     The data block being processed.
00231  *
00232  * \warning        SHA-1 is considered a weak message digest and its use
00233  *                 constitutes a security risk. We recommend considering
00234  *                 stronger message digests instead.
00235  *
00236  */
00237 MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
00238                                               const unsigned char data[64] );
00239 
00240 #undef MBEDTLS_DEPRECATED
00241 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00242 
00243 #ifdef __cplusplus
00244 }
00245 #endif
00246 
00247 #else  /* MBEDTLS_SHA1_ALT */
00248 #include "sha1_alt.h"
00249 #endif /* MBEDTLS_SHA1_ALT */
00250 
00251 #ifdef __cplusplus
00252 extern "C" {
00253 #endif
00254 
00255 /**
00256  * \brief          This function calculates the SHA-1 checksum of a buffer.
00257  *
00258  *                 The function allocates the context, performs the
00259  *                 calculation, and frees the context.
00260  *
00261  *                 The SHA-1 result is calculated as
00262  *                 output = SHA-1(input buffer).
00263  *
00264  * \param input    The buffer holding the input data.
00265  * \param ilen     The length of the input data.
00266  * \param output   The SHA-1 checksum result.
00267  *
00268  * \return         \c 0 if successful
00269  *
00270  * \warning        SHA-1 is considered a weak message digest and its use
00271  *                 constitutes a security risk. We recommend considering
00272  *                 stronger message digests instead.
00273  *
00274  */
00275 int mbedtls_sha1_ret( const unsigned char *input,
00276                       size_t ilen,
00277                       unsigned char output[20] );
00278 
00279 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00280 #if defined(MBEDTLS_DEPRECATED_WARNING)
00281 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
00282 #else
00283 #define MBEDTLS_DEPRECATED
00284 #endif
00285 /**
00286  * \brief          Output = SHA-1( input buffer )
00287  *
00288  * \deprecated     Superseded by mbedtls_sha1_ret() in 2.7.0
00289  *
00290  * \param input    The buffer holding the input data.
00291  * \param ilen     The length of the input data.
00292  * \param output   The SHA-1 checksum result.
00293  *
00294  * \warning        SHA-1 is considered a weak message digest and its use
00295  *                 constitutes a security risk. We recommend considering
00296  *                 stronger message digests instead.
00297  *
00298  */
00299 MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
00300                                       size_t ilen,
00301                                       unsigned char output[20] );
00302 
00303 #undef MBEDTLS_DEPRECATED
00304 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00305 
00306 /**
00307  * \brief          The SHA-1 checkup routine.
00308  *
00309  * \return         \c 0 on success, or \c 1 on failure.
00310  *
00311  * \warning        SHA-1 is considered a weak message digest and its use
00312  *                 constitutes a security risk. We recommend considering
00313  *                 stronger message digests instead.
00314  *
00315  */
00316 int mbedtls_sha1_self_test( int verbose );
00317 
00318 #ifdef __cplusplus
00319 }
00320 #endif
00321 
00322 #endif /* mbedtls_sha1.h */