sha1.h

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