1 /* 2 * QEMU Crypto hash algorithms 3 * 4 * Copyright (c) 2024 Seagate Technology LLC and/or its Affiliates 5 * Copyright (c) 2015 Red Hat, Inc. 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, see <http://www.gnu.org/licenses/>. 19 * 20 */ 21 22 #ifndef QCRYPTO_HASH_H 23 #define QCRYPTO_HASH_H 24 25 #include "qapi/qapi-types-crypto.h" 26 27 #define QCRYPTO_HASH_DIGEST_LEN_MD5 16 28 #define QCRYPTO_HASH_DIGEST_LEN_SHA1 20 29 #define QCRYPTO_HASH_DIGEST_LEN_SHA224 28 30 #define QCRYPTO_HASH_DIGEST_LEN_SHA256 32 31 #define QCRYPTO_HASH_DIGEST_LEN_SHA384 48 32 #define QCRYPTO_HASH_DIGEST_LEN_SHA512 64 33 #define QCRYPTO_HASH_DIGEST_LEN_RIPEMD160 20 34 #define QCRYPTO_HASH_DIGEST_LEN_SM3 32 35 36 /* See also "QCryptoHashAlgo" defined in qapi/crypto.json */ 37 38 typedef struct QCryptoHash QCryptoHash; 39 struct QCryptoHash { 40 QCryptoHashAlgo alg; 41 void *opaque; 42 void *driver; 43 }; 44 45 /** 46 * qcrypto_hash_supports: 47 * @alg: the hash algorithm 48 * 49 * Determine if @alg hash algorithm is supported by the 50 * current configured build. 51 * 52 * Returns: true if the algorithm is supported, false otherwise 53 */ 54 gboolean qcrypto_hash_supports(QCryptoHashAlgo alg); 55 56 57 /** 58 * qcrypto_hash_digest_len: 59 * @alg: the hash algorithm 60 * 61 * Determine the size of the hash digest in bytes 62 * 63 * Returns: the digest length in bytes 64 */ 65 size_t qcrypto_hash_digest_len(QCryptoHashAlgo alg); 66 67 /** 68 * qcrypto_hash_bytesv: 69 * @alg: the hash algorithm 70 * @iov: the array of memory regions to hash 71 * @niov: the length of @iov 72 * @result: pointer to hold output hash 73 * @resultlen: pointer to hold length of @result 74 * @errp: pointer to a NULL-initialized error object 75 * 76 * Computes the hash across all the memory regions 77 * present in @iov. 78 * 79 * If @result_len is set to a non-zero value by the caller, then 80 * @result must hold a pointer that is @result_len in size, and 81 * @result_len match the size of the hash output. The digest will 82 * be written into @result. 83 * 84 * If @result_len is set to zero, then this function will allocate 85 * a buffer to hold the hash output digest, storing a pointer to 86 * the buffer in @result, and setting @result_len to its size. 87 * The memory referenced in @result must be released with a call 88 * to g_free() when no longer required by the caller. 89 * 90 * Returns: 0 on success, -1 on error 91 */ 92 int qcrypto_hash_bytesv(QCryptoHashAlgo alg, 93 const struct iovec *iov, 94 size_t niov, 95 uint8_t **result, 96 size_t *resultlen, 97 Error **errp); 98 99 /** 100 * qcrypto_hash_bytes: 101 * @alg: the hash algorithm 102 * @buf: the memory region to hash 103 * @len: the length of @buf 104 * @result: pointer to hold output hash 105 * @resultlen: pointer to hold length of @result 106 * @errp: pointer to a NULL-initialized error object 107 * 108 * Computes the hash across all the memory region 109 * @buf of length @len. 110 * 111 * If @result_len is set to a non-zero value by the caller, then 112 * @result must hold a pointer that is @result_len in size, and 113 * @result_len match the size of the hash output. The digest will 114 * be written into @result. 115 * 116 * If @result_len is set to zero, then this function will allocate 117 * a buffer to hold the hash output digest, storing a pointer to 118 * the buffer in @result, and setting @result_len to its size. 119 * The memory referenced in @result must be released with a call 120 * to g_free() when no longer required by the caller. 121 * 122 * Returns: 0 on success, -1 on error 123 */ 124 int qcrypto_hash_bytes(QCryptoHashAlgo alg, 125 const char *buf, 126 size_t len, 127 uint8_t **result, 128 size_t *resultlen, 129 Error **errp); 130 131 /** 132 * qcrypto_hash_digestv: 133 * @alg: the hash algorithm 134 * @iov: the array of memory regions to hash 135 * @niov: the length of @iov 136 * @digest: pointer to hold output hash 137 * @errp: pointer to a NULL-initialized error object 138 * 139 * Computes the hash across all the memory regions 140 * present in @iov. The @digest pointer will be 141 * filled with the printable hex digest of the computed 142 * hash, which will be terminated by '\0'. The 143 * memory pointer in @digest must be released 144 * with a call to g_free() when no longer required. 145 * 146 * Returns: 0 on success, -1 on error 147 */ 148 int qcrypto_hash_digestv(QCryptoHashAlgo alg, 149 const struct iovec *iov, 150 size_t niov, 151 char **digest, 152 Error **errp); 153 154 /** 155 * qcrypto_hash_updatev: 156 * @hash: hash object from qcrypto_hash_new 157 * @iov: the array of memory regions to hash 158 * @niov: the length of @iov 159 * @errp: pointer to a NULL-initialized error object 160 * 161 * Updates the given hash object with all the memory regions 162 * present in @iov. 163 * 164 * Returns: 0 on success, -1 on error 165 */ 166 int qcrypto_hash_updatev(QCryptoHash *hash, 167 const struct iovec *iov, 168 size_t niov, 169 Error **errp); 170 /** 171 * qcrypto_hash_update: 172 * @hash: hash object from qcrypto_hash_new 173 * @buf: the memory region to hash 174 * @len: the length of @buf 175 * @errp: pointer to a NULL-initialized error object 176 * 177 * Updates the given hash object with the data from 178 * the given buffer. 179 * 180 * Returns: 0 on success, -1 on error 181 */ 182 int qcrypto_hash_update(QCryptoHash *hash, 183 const char *buf, 184 size_t len, 185 Error **errp); 186 187 /** 188 * qcrypto_hash_finalize_digest: 189 * @hash: the hash object to finalize 190 * @digest: pointer to hold output hash 191 * @errp: pointer to a NULL-initialized error object 192 * 193 * Computes the hash from the given hash object. Hash object 194 * is expected to have its data updated from the qcrypto_hash_update function. 195 * The @digest pointer will be filled with the printable hex digest of the 196 * computed hash, which will be terminated by '\0'. The memory pointer 197 * in @digest must be released with a call to g_free() when 198 * no longer required. 199 * 200 * Returns: 0 on success, -1 on error 201 */ 202 int qcrypto_hash_finalize_digest(QCryptoHash *hash, 203 char **digest, 204 Error **errp); 205 206 /** 207 * qcrypto_hash_finalize_base64: 208 * @hash_ctx: hash object to finalize 209 * @base64: pointer to store the hash result in 210 * @errp: pointer to a NULL-initialized error object 211 * 212 * Computes the hash from the given hash object. Hash object 213 * is expected to have it's data updated from the qcrypto_hash_update function. 214 * The @base64 pointer will be filled with the base64 encoding of the computed 215 * hash, which will be terminated by '\0'. The memory pointer in @base64 216 * must be released with a call to g_free() when no longer required. 217 * 218 * Returns: 0 on success, -1 on error 219 */ 220 int qcrypto_hash_finalize_base64(QCryptoHash *hash, 221 char **base64, 222 Error **errp); 223 224 /** 225 * qcrypto_hash_finalize_bytes: 226 * @hash_ctx: hash object to finalize 227 * @result: pointer to store the hash result in 228 * @result_len: Pointer to store the length of the result in 229 * @errp: pointer to a NULL-initialized error object 230 * 231 * Computes the hash from the given hash object. Hash object 232 * is expected to have it's data updated from the qcrypto_hash_update function. 233 * 234 * If @result_len is set to a non-zero value by the caller, then 235 * @result must hold a pointer that is @result_len in size, and 236 * @result_len match the size of the hash output. The digest will 237 * be written into @result. 238 * 239 * If @result_len is set to zero, then this function will allocate 240 * a buffer to hold the hash output digest, storing a pointer to 241 * the buffer in @result, and setting @result_len to its size. 242 * The memory referenced in @result must be released with a call 243 * to g_free() when no longer required by the caller. 244 * 245 * Returns: 0 on success, -1 on error 246 */ 247 int qcrypto_hash_finalize_bytes(QCryptoHash *hash, 248 uint8_t **result, 249 size_t *result_len, 250 Error **errp); 251 252 /** 253 * qcrypto_hash_new: 254 * @alg: the hash algorithm 255 * @errp: pointer to a NULL-initialized error object 256 * 257 * Creates a new hashing context for the chosen algorithm for 258 * usage with qcrypto_hash_update. 259 * 260 * Returns: New hash object with the given algorithm, or NULL on error. 261 */ 262 QCryptoHash *qcrypto_hash_new(QCryptoHashAlgo alg, Error **errp); 263 264 /** 265 * qcrypto_hash_free: 266 * @hash: hash object to free 267 * 268 * Frees a hashing context for the chosen algorithm. 269 */ 270 void qcrypto_hash_free(QCryptoHash *hash); 271 272 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHash, qcrypto_hash_free) 273 274 /** 275 * qcrypto_hash_digest: 276 * @alg: the hash algorithm 277 * @buf: the memory region to hash 278 * @len: the length of @buf 279 * @digest: pointer to hold output hash 280 * @errp: pointer to a NULL-initialized error object 281 * 282 * Computes the hash across all the memory region 283 * @buf of length @len. The @digest pointer will be 284 * filled with the printable hex digest of the computed 285 * hash, which will be terminated by '\0'. The 286 * memory pointer in @digest must be released 287 * with a call to g_free() when no longer required. 288 * 289 * Returns: 0 on success, -1 on error 290 */ 291 int qcrypto_hash_digest(QCryptoHashAlgo alg, 292 const char *buf, 293 size_t len, 294 char **digest, 295 Error **errp); 296 297 /** 298 * qcrypto_hash_base64v: 299 * @alg: the hash algorithm 300 * @iov: the array of memory regions to hash 301 * @niov: the length of @iov 302 * @base64: pointer to hold output hash 303 * @errp: pointer to a NULL-initialized error object 304 * 305 * Computes the hash across all the memory regions 306 * present in @iov. The @base64 pointer will be 307 * filled with the base64 encoding of the computed 308 * hash, which will be terminated by '\0'. The 309 * memory pointer in @base64 must be released 310 * with a call to g_free() when no longer required. 311 * 312 * Returns: 0 on success, -1 on error 313 */ 314 int qcrypto_hash_base64v(QCryptoHashAlgo alg, 315 const struct iovec *iov, 316 size_t niov, 317 char **base64, 318 Error **errp); 319 320 /** 321 * qcrypto_hash_base64: 322 * @alg: the hash algorithm 323 * @buf: the memory region to hash 324 * @len: the length of @buf 325 * @base64: pointer to hold output hash 326 * @errp: pointer to a NULL-initialized error object 327 * 328 * Computes the hash across all the memory region 329 * @buf of length @len. The @base64 pointer will be 330 * filled with the base64 encoding of the computed 331 * hash, which will be terminated by '\0'. The 332 * memory pointer in @base64 must be released 333 * with a call to g_free() when no longer required. 334 * 335 * Returns: 0 on success, -1 on error 336 */ 337 int qcrypto_hash_base64(QCryptoHashAlgo alg, 338 const char *buf, 339 size_t len, 340 char **base64, 341 Error **errp); 342 343 #endif /* QCRYPTO_HASH_H */ 344