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