sha1.h (7501B)
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 #include "mbedtls/private_access.h" 20 21 #include "mbedtls/build_info.h" 22 23 #include <stddef.h> 24 #include <stdint.h> 25 26 /** SHA-1 input data was malformed. */ 27 #define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA -0x0073 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #if !defined(MBEDTLS_SHA1_ALT) 34 // Regular implementation 35 // 36 37 /** 38 * \brief The SHA-1 context structure. 39 * 40 * \warning SHA-1 is considered a weak message digest and its use 41 * constitutes a security risk. We recommend considering 42 * stronger message digests instead. 43 * 44 */ 45 typedef struct mbedtls_sha1_context { 46 uint32_t MBEDTLS_PRIVATE(total)[2]; /*!< The number of Bytes processed. */ 47 uint32_t MBEDTLS_PRIVATE(state)[5]; /*!< The intermediate digest state. */ 48 unsigned char MBEDTLS_PRIVATE(buffer)[64]; /*!< The data block being processed. */ 49 } 50 mbedtls_sha1_context; 51 52 #else /* MBEDTLS_SHA1_ALT */ 53 #include "sha1_alt.h" 54 #endif /* MBEDTLS_SHA1_ALT */ 55 56 /** 57 * \brief This function initializes a SHA-1 context. 58 * 59 * \warning SHA-1 is considered a weak message digest and its use 60 * constitutes a security risk. We recommend considering 61 * stronger message digests instead. 62 * 63 * \param ctx The SHA-1 context to initialize. 64 * This must not be \c NULL. 65 * 66 */ 67 void mbedtls_sha1_init(mbedtls_sha1_context *ctx); 68 69 /** 70 * \brief This function clears a SHA-1 context. 71 * 72 * \warning SHA-1 is considered a weak message digest and its use 73 * constitutes a security risk. We recommend considering 74 * stronger message digests instead. 75 * 76 * \param ctx The SHA-1 context to clear. This may be \c NULL, 77 * in which case this function does nothing. If it is 78 * not \c NULL, it must point to an initialized 79 * SHA-1 context. 80 * 81 */ 82 void mbedtls_sha1_free(mbedtls_sha1_context *ctx); 83 84 /** 85 * \brief This function clones the state of a SHA-1 context. 86 * 87 * \warning SHA-1 is considered a weak message digest and its use 88 * constitutes a security risk. We recommend considering 89 * stronger message digests instead. 90 * 91 * \param dst The SHA-1 context to clone to. This must be initialized. 92 * \param src The SHA-1 context to clone from. This must be initialized. 93 * 94 */ 95 void mbedtls_sha1_clone(mbedtls_sha1_context *dst, 96 const mbedtls_sha1_context *src); 97 98 /** 99 * \brief This function starts a SHA-1 checksum calculation. 100 * 101 * \warning SHA-1 is considered a weak message digest and its use 102 * constitutes a security risk. We recommend considering 103 * stronger message digests instead. 104 * 105 * \param ctx The SHA-1 context to initialize. This must be initialized. 106 * 107 * \return \c 0 on success. 108 * \return A negative error code on failure. 109 * 110 */ 111 int mbedtls_sha1_starts(mbedtls_sha1_context *ctx); 112 113 /** 114 * \brief This function feeds an input buffer into an ongoing SHA-1 115 * checksum calculation. 116 * 117 * \warning SHA-1 is considered a weak message digest and its use 118 * constitutes a security risk. We recommend considering 119 * stronger message digests instead. 120 * 121 * \param ctx The SHA-1 context. This must be initialized 122 * and have a hash operation started. 123 * \param input The buffer holding the input data. 124 * This must be a readable buffer of length \p ilen Bytes. 125 * \param ilen The length of the input data \p input in Bytes. 126 * 127 * \return \c 0 on success. 128 * \return A negative error code on failure. 129 */ 130 int mbedtls_sha1_update(mbedtls_sha1_context *ctx, 131 const unsigned char *input, 132 size_t ilen); 133 134 /** 135 * \brief This function finishes the SHA-1 operation, and writes 136 * the result to the output buffer. 137 * 138 * \warning SHA-1 is considered a weak message digest and its use 139 * constitutes a security risk. We recommend considering 140 * stronger message digests instead. 141 * 142 * \param ctx The SHA-1 context to use. This must be initialized and 143 * have a hash operation started. 144 * \param output The SHA-1 checksum result. This must be a writable 145 * buffer of length \c 20 Bytes. 146 * 147 * \return \c 0 on success. 148 * \return A negative error code on failure. 149 */ 150 int mbedtls_sha1_finish(mbedtls_sha1_context *ctx, 151 unsigned char output[20]); 152 153 /** 154 * \brief SHA-1 process data block (internal use only). 155 * 156 * \warning SHA-1 is considered a weak message digest and its use 157 * constitutes a security risk. We recommend considering 158 * stronger message digests instead. 159 * 160 * \param ctx The SHA-1 context to use. This must be initialized. 161 * \param data The data block being processed. This must be a 162 * readable buffer of length \c 64 Bytes. 163 * 164 * \return \c 0 on success. 165 * \return A negative error code on failure. 166 * 167 */ 168 int mbedtls_internal_sha1_process(mbedtls_sha1_context *ctx, 169 const unsigned char data[64]); 170 171 /** 172 * \brief This function calculates the SHA-1 checksum of a buffer. 173 * 174 * The function allocates the context, performs the 175 * calculation, and frees the context. 176 * 177 * The SHA-1 result is calculated as 178 * output = SHA-1(input buffer). 179 * 180 * \warning SHA-1 is considered a weak message digest and its use 181 * constitutes a security risk. We recommend considering 182 * stronger message digests instead. 183 * 184 * \param input The buffer holding the input data. 185 * This must be a readable buffer of length \p ilen Bytes. 186 * \param ilen The length of the input data \p input in Bytes. 187 * \param output The SHA-1 checksum result. 188 * This must be a writable buffer of length \c 20 Bytes. 189 * 190 * \return \c 0 on success. 191 * \return A negative error code on failure. 192 * 193 */ 194 int mbedtls_sha1(const unsigned char *input, 195 size_t ilen, 196 unsigned char output[20]); 197 198 #if defined(MBEDTLS_SELF_TEST) 199 200 /** 201 * \brief The SHA-1 checkup routine. 202 * 203 * \warning SHA-1 is considered a weak message digest and its use 204 * constitutes a security risk. We recommend considering 205 * stronger message digests instead. 206 * 207 * \return \c 0 on success. 208 * \return \c 1 on failure. 209 * 210 */ 211 int mbedtls_sha1_self_test(int verbose); 212 213 #endif /* MBEDTLS_SELF_TEST */ 214 215 #ifdef __cplusplus 216 } 217 #endif 218 219 #endif /* mbedtls_sha1.h */