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