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