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