1 /** 2 * \file sha1.h 3 * 4 * \brief This file contains SHA-1 definitions and functions. 5 * 6 * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in 7 * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>. 8 * 9 * \warning SHA-1 is considered a weak message digest and its use constitutes 10 * a security risk. We recommend considering stronger message 11 * digests instead. 12 */ 13 /* 14 * Copyright The Mbed TLS Contributors 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); you may 18 * not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 25 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 */ 29 #ifndef MBEDTLS_SHA1_H 30 #define MBEDTLS_SHA1_H 31 32 #if !defined(MBEDTLS_CONFIG_FILE) 33 #include "mbedtls/config.h" 34 #else 35 #include MBEDTLS_CONFIG_FILE 36 #endif 37 38 #include <stddef.h> 39 #include <stdint.h> 40 41 /* MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED is deprecated and should not be used. */ 42 #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED -0x0035 /**< SHA-1 hardware accelerator failed */ 43 #define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA -0x0073 /**< SHA-1 input data was malformed. */ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #if !defined(MBEDTLS_SHA1_ALT) 50 // Regular implementation 51 // 52 53 /** 54 * \brief The SHA-1 context structure. 55 * 56 * \warning SHA-1 is considered a weak message digest and its use 57 * constitutes a security risk. We recommend considering 58 * stronger message digests instead. 59 * 60 */ 61 typedef struct mbedtls_sha1_context 62 { 63 uint32_t total[2]; /*!< The number of Bytes processed. */ 64 uint32_t state[5]; /*!< The intermediate digest state. */ 65 unsigned char buffer[64]; /*!< The data block being processed. */ 66 } 67 mbedtls_sha1_context; 68 69 #else /* MBEDTLS_SHA1_ALT */ 70 #include "sha1_alt.h" 71 #endif /* MBEDTLS_SHA1_ALT */ 72 73 /** 74 * \brief This function initializes a SHA-1 context. 75 * 76 * \warning SHA-1 is considered a weak message digest and its use 77 * constitutes a security risk. We recommend considering 78 * stronger message digests instead. 79 * 80 * \param ctx The SHA-1 context to initialize. 81 * This must not be \c NULL. 82 * 83 */ 84 void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); 85 86 /** 87 * \brief This function clears a SHA-1 context. 88 * 89 * \warning SHA-1 is considered a weak message digest and its use 90 * constitutes a security risk. We recommend considering 91 * stronger message digests instead. 92 * 93 * \param ctx The SHA-1 context to clear. This may be \c NULL, 94 * in which case this function does nothing. If it is 95 * not \c NULL, it must point to an initialized 96 * SHA-1 context. 97 * 98 */ 99 void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); 100 101 /** 102 * \brief This function clones the state of a SHA-1 context. 103 * 104 * \warning SHA-1 is considered a weak message digest and its use 105 * constitutes a security risk. We recommend considering 106 * stronger message digests instead. 107 * 108 * \param dst The SHA-1 context to clone to. This must be initialized. 109 * \param src The SHA-1 context to clone from. This must be initialized. 110 * 111 */ 112 void mbedtls_sha1_clone( mbedtls_sha1_context *dst, 113 const mbedtls_sha1_context *src ); 114 115 /** 116 * \brief This function starts a SHA-1 checksum calculation. 117 * 118 * \warning SHA-1 is considered a weak message digest and its use 119 * constitutes a security risk. We recommend considering 120 * stronger message digests instead. 121 * 122 * \param ctx The SHA-1 context to initialize. This must be initialized. 123 * 124 * \return \c 0 on success. 125 * \return A negative error code on failure. 126 * 127 */ 128 int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); 129 130 /** 131 * \brief This function feeds an input buffer into an ongoing SHA-1 132 * checksum calculation. 133 * 134 * \warning SHA-1 is considered a weak message digest and its use 135 * constitutes a security risk. We recommend considering 136 * stronger message digests instead. 137 * 138 * \param ctx The SHA-1 context. This must be initialized 139 * and have a hash operation started. 140 * \param input The buffer holding the input data. 141 * This must be a readable buffer of length \p ilen Bytes. 142 * \param ilen The length of the input data \p input in Bytes. 143 * 144 * \return \c 0 on success. 145 * \return A negative error code on failure. 146 */ 147 int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, 148 const unsigned char *input, 149 size_t ilen ); 150 151 /** 152 * \brief This function finishes the SHA-1 operation, and writes 153 * the result to the output buffer. 154 * 155 * \warning SHA-1 is considered a weak message digest and its use 156 * constitutes a security risk. We recommend considering 157 * stronger message digests instead. 158 * 159 * \param ctx The SHA-1 context to use. This must be initialized and 160 * have a hash operation started. 161 * \param output The SHA-1 checksum result. This must be a writable 162 * buffer of length \c 20 Bytes. 163 * 164 * \return \c 0 on success. 165 * \return A negative error code on failure. 166 */ 167 int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, 168 unsigned char output[20] ); 169 170 /** 171 * \brief SHA-1 process data block (internal use only). 172 * 173 * \warning SHA-1 is considered a weak message digest and its use 174 * constitutes a security risk. We recommend considering 175 * stronger message digests instead. 176 * 177 * \param ctx The SHA-1 context to use. This must be initialized. 178 * \param data The data block being processed. This must be a 179 * readable buffer of length \c 64 Bytes. 180 * 181 * \return \c 0 on success. 182 * \return A negative error code on failure. 183 * 184 */ 185 int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, 186 const unsigned char data[64] ); 187 188 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 189 #if defined(MBEDTLS_DEPRECATED_WARNING) 190 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 191 #else 192 #define MBEDTLS_DEPRECATED 193 #endif 194 /** 195 * \brief This function starts a SHA-1 checksum calculation. 196 * 197 * \warning SHA-1 is considered a weak message digest and its use 198 * constitutes a security risk. We recommend considering 199 * stronger message digests instead. 200 * 201 * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0. 202 * 203 * \param ctx The SHA-1 context to initialize. This must be initialized. 204 * 205 */ 206 MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ); 207 208 /** 209 * \brief This function feeds an input buffer into an ongoing SHA-1 210 * checksum calculation. 211 * 212 * \warning SHA-1 is considered a weak message digest and its use 213 * constitutes a security risk. We recommend considering 214 * stronger message digests instead. 215 * 216 * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0. 217 * 218 * \param ctx The SHA-1 context. This must be initialized and 219 * have a hash operation started. 220 * \param input The buffer holding the input data. 221 * This must be a readable buffer of length \p ilen Bytes. 222 * \param ilen The length of the input data \p input in Bytes. 223 * 224 */ 225 MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx, 226 const unsigned char *input, 227 size_t ilen ); 228 229 /** 230 * \brief This function finishes the SHA-1 operation, and writes 231 * the result to the output buffer. 232 * 233 * \warning SHA-1 is considered a weak message digest and its use 234 * constitutes a security risk. We recommend considering 235 * stronger message digests instead. 236 * 237 * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0. 238 * 239 * \param ctx The SHA-1 context. This must be initialized and 240 * have a hash operation started. 241 * \param output The SHA-1 checksum result. 242 * This must be a writable buffer of length \c 20 Bytes. 243 */ 244 MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, 245 unsigned char output[20] ); 246 247 /** 248 * \brief SHA-1 process data block (internal use only). 249 * 250 * \warning SHA-1 is considered a weak message digest and its use 251 * constitutes a security risk. We recommend considering 252 * stronger message digests instead. 253 * 254 * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0. 255 * 256 * \param ctx The SHA-1 context. This must be initialized. 257 * \param data The data block being processed. 258 * This must be a readable buffer of length \c 64 bytes. 259 * 260 */ 261 MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx, 262 const unsigned char data[64] ); 263 264 #undef MBEDTLS_DEPRECATED 265 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 266 267 /** 268 * \brief This function calculates the SHA-1 checksum of a buffer. 269 * 270 * The function allocates the context, performs the 271 * calculation, and frees the context. 272 * 273 * The SHA-1 result is calculated as 274 * output = SHA-1(input buffer). 275 * 276 * \warning SHA-1 is considered a weak message digest and its use 277 * constitutes a security risk. We recommend considering 278 * stronger message digests instead. 279 * 280 * \param input The buffer holding the input data. 281 * This must be a readable buffer of length \p ilen Bytes. 282 * \param ilen The length of the input data \p input in Bytes. 283 * \param output The SHA-1 checksum result. 284 * This must be a writable buffer of length \c 20 Bytes. 285 * 286 * \return \c 0 on success. 287 * \return A negative error code on failure. 288 * 289 */ 290 int mbedtls_sha1_ret( const unsigned char *input, 291 size_t ilen, 292 unsigned char output[20] ); 293 294 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 295 #if defined(MBEDTLS_DEPRECATED_WARNING) 296 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 297 #else 298 #define MBEDTLS_DEPRECATED 299 #endif 300 /** 301 * \brief This function calculates the SHA-1 checksum of a buffer. 302 * 303 * The function allocates the context, performs the 304 * calculation, and frees the context. 305 * 306 * The SHA-1 result is calculated as 307 * output = SHA-1(input buffer). 308 * 309 * \warning SHA-1 is considered a weak message digest and its use 310 * constitutes a security risk. We recommend considering 311 * stronger message digests instead. 312 * 313 * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 314 * 315 * \param input The buffer holding the input data. 316 * This must be a readable buffer of length \p ilen Bytes. 317 * \param ilen The length of the input data \p input in Bytes. 318 * \param output The SHA-1 checksum result. This must be a writable 319 * buffer of size \c 20 Bytes. 320 * 321 */ 322 MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, 323 size_t ilen, 324 unsigned char output[20] ); 325 326 #undef MBEDTLS_DEPRECATED 327 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 328 329 #if defined(MBEDTLS_SELF_TEST) 330 331 /** 332 * \brief The SHA-1 checkup routine. 333 * 334 * \warning SHA-1 is considered a weak message digest and its use 335 * constitutes a security risk. We recommend considering 336 * stronger message digests instead. 337 * 338 * \return \c 0 on success. 339 * \return \c 1 on failure. 340 * 341 */ 342 int mbedtls_sha1_self_test( int verbose ); 343 344 #endif /* MBEDTLS_SELF_TEST */ 345 346 #ifdef __cplusplus 347 } 348 #endif 349 350 #endif /* mbedtls_sha1.h */ 351