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