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 35 /* See also "QCryptoHashAlgo" defined in qapi/crypto.json */ 36 37 typedef struct QCryptoHash QCryptoHash; 38 struct QCryptoHash { 39 QCryptoHashAlgo alg; 40 void *opaque; 41 void *driver; 42 }; 43 44 /** 45 * qcrypto_hash_supports: 46 * @alg: the hash algorithm 47 * 48 * Determine if @alg hash algorithm is supported by the 49 * current configured build. 50 * 51 * Returns: true if the algorithm is supported, false otherwise 52 */ 53 gboolean qcrypto_hash_supports(QCryptoHashAlgo alg); 54 55 56 /** 57 * qcrypto_hash_digest_len: 58 * @alg: the hash algorithm 59 * 60 * Determine the size of the hash digest in bytes 61 * 62 * Returns: the digest length in bytes 63 */ 64 size_t qcrypto_hash_digest_len(QCryptoHashAlgo alg); 65 66 /** 67 * qcrypto_hash_bytesv: 68 * @alg: the hash algorithm 69 * @iov: the array of memory regions to hash 70 * @niov: the length of @iov 71 * @result: pointer to hold output hash 72 * @resultlen: pointer to hold length of @result 73 * @errp: pointer to a NULL-initialized error object 74 * 75 * Computes the hash across all the memory regions 76 * present in @iov. 77 * 78 * If @result_len is set to a non-zero value by the caller, then 79 * @result must hold a pointer that is @result_len in size, and 80 * @result_len match the size of the hash output. The digest will 81 * be written into @result. 82 * 83 * If @result_len is set to zero, then this function will allocate 84 * a buffer to hold the hash output digest, storing a pointer to 85 * the buffer in @result, and setting @result_len to its size. 86 * The memory referenced in @result must be released with a call 87 * to g_free() when no longer required by the caller. 88 * 89 * Returns: 0 on success, -1 on error 90 */ 91 int qcrypto_hash_bytesv(QCryptoHashAlgo alg, 92 const struct iovec *iov, 93 size_t niov, 94 uint8_t **result, 95 size_t *resultlen, 96 Error **errp); 97 98 /** 99 * qcrypto_hash_bytes: 100 * @alg: the hash algorithm 101 * @buf: the memory region to hash 102 * @len: the length of @buf 103 * @result: pointer to hold output hash 104 * @resultlen: pointer to hold length of @result 105 * @errp: pointer to a NULL-initialized error object 106 * 107 * Computes the hash across all the memory region 108 * @buf of length @len. 109 * 110 * If @result_len is set to a non-zero value by the caller, then 111 * @result must hold a pointer that is @result_len in size, and 112 * @result_len match the size of the hash output. The digest will 113 * be written into @result. 114 * 115 * If @result_len is set to zero, then this function will allocate 116 * a buffer to hold the hash output digest, storing a pointer to 117 * the buffer in @result, and setting @result_len to its size. 118 * The memory referenced in @result must be released with a call 119 * to g_free() when no longer required by the caller. 120 * 121 * Returns: 0 on success, -1 on error 122 */ 123 int qcrypto_hash_bytes(QCryptoHashAlgo alg, 124 const char *buf, 125 size_t len, 126 uint8_t **result, 127 size_t *resultlen, 128 Error **errp); 129 130 /** 131 * qcrypto_hash_digestv: 132 * @alg: the hash algorithm 133 * @iov: the array of memory regions to hash 134 * @niov: the length of @iov 135 * @digest: pointer to hold output hash 136 * @errp: pointer to a NULL-initialized error object 137 * 138 * Computes the hash across all the memory regions 139 * present in @iov. The @digest pointer will be 140 * filled with the printable hex digest of the computed 141 * hash, which will be terminated by '\0'. The 142 * memory pointer in @digest must be released 143 * with a call to g_free() when no longer required. 144 * 145 * Returns: 0 on success, -1 on error 146 */ 147 int qcrypto_hash_digestv(QCryptoHashAlgo alg, 148 const struct iovec *iov, 149 size_t niov, 150 char **digest, 151 Error **errp); 152 153 /** 154 * qcrypto_hash_updatev: 155 * @hash: hash object from qcrypto_hash_new 156 * @iov: the array of memory regions to hash 157 * @niov: the length of @iov 158 * @errp: pointer to a NULL-initialized error object 159 * 160 * Updates the given hash object with all the memory regions 161 * present in @iov. 162 * 163 * Returns: 0 on success, -1 on error 164 */ 165 int qcrypto_hash_updatev(QCryptoHash *hash, 166 const struct iovec *iov, 167 size_t niov, 168 Error **errp); 169 /** 170 * qcrypto_hash_update: 171 * @hash: hash object from qcrypto_hash_new 172 * @buf: the memory region to hash 173 * @len: the length of @buf 174 * @errp: pointer to a NULL-initialized error object 175 * 176 * Updates the given hash object with the data from 177 * the given buffer. 178 * 179 * Returns: 0 on success, -1 on error 180 */ 181 int qcrypto_hash_update(QCryptoHash *hash, 182 const char *buf, 183 size_t len, 184 Error **errp); 185 186 /** 187 * qcrypto_hash_finalize_digest: 188 * @hash: the hash object to finalize 189 * @digest: pointer to hold output hash 190 * @errp: pointer to a NULL-initialized error object 191 * 192 * Computes the hash from the given hash object. Hash object 193 * is expected to have its data updated from the qcrypto_hash_update function. 194 * The @digest pointer will be filled with the printable hex digest of the 195 * computed hash, which will be terminated by '\0'. The memory pointer 196 * in @digest must be released with a call to g_free() when 197 * no longer required. 198 * 199 * Returns: 0 on success, -1 on error 200 */ 201 int qcrypto_hash_finalize_digest(QCryptoHash *hash, 202 char **digest, 203 Error **errp); 204 205 /** 206 * qcrypto_hash_finalize_base64: 207 * @hash_ctx: hash object to finalize 208 * @base64: pointer to store the hash result in 209 * @errp: pointer to a NULL-initialized error object 210 * 211 * Computes the hash from the given hash object. Hash object 212 * is expected to have it's data updated from the qcrypto_hash_update function. 213 * The @base64 pointer will be filled with the base64 encoding of the computed 214 * hash, which will be terminated by '\0'. The memory pointer in @base64 215 * must be released with a call to g_free() when no longer required. 216 * 217 * Returns: 0 on success, -1 on error 218 */ 219 int qcrypto_hash_finalize_base64(QCryptoHash *hash, 220 char **base64, 221 Error **errp); 222 223 /** 224 * qcrypto_hash_finalize_bytes: 225 * @hash_ctx: hash object to finalize 226 * @result: pointer to store the hash result in 227 * @result_len: Pointer to store the length of the result in 228 * @errp: pointer to a NULL-initialized error object 229 * 230 * Computes the hash from the given hash object. Hash object 231 * is expected to have it's data updated from the qcrypto_hash_update function. 232 * 233 * If @result_len is set to a non-zero value by the caller, then 234 * @result must hold a pointer that is @result_len in size, and 235 * @result_len match the size of the hash output. The digest will 236 * be written into @result. 237 * 238 * If @result_len is set to zero, then this function will allocate 239 * a buffer to hold the hash output digest, storing a pointer to 240 * the buffer in @result, and setting @result_len to its size. 241 * The memory referenced in @result must be released with a call 242 * to g_free() when no longer required by the caller. 243 * 244 * Returns: 0 on success, -1 on error 245 */ 246 int qcrypto_hash_finalize_bytes(QCryptoHash *hash, 247 uint8_t **result, 248 size_t *result_len, 249 Error **errp); 250 251 /** 252 * qcrypto_hash_new: 253 * @alg: the hash algorithm 254 * @errp: pointer to a NULL-initialized error object 255 * 256 * Creates a new hashing context for the chosen algorithm for 257 * usage with qcrypto_hash_update. 258 * 259 * Returns: New hash object with the given algorithm, or NULL on error. 260 */ 261 QCryptoHash *qcrypto_hash_new(QCryptoHashAlgo alg, Error **errp); 262 263 /** 264 * qcrypto_hash_free: 265 * @hash: hash object to free 266 * 267 * Frees a hashing context for the chosen algorithm. 268 */ 269 void qcrypto_hash_free(QCryptoHash *hash); 270 271 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHash, qcrypto_hash_free) 272 273 /** 274 * qcrypto_hash_digest: 275 * @alg: the hash algorithm 276 * @buf: the memory region to hash 277 * @len: the length of @buf 278 * @digest: pointer to hold output hash 279 * @errp: pointer to a NULL-initialized error object 280 * 281 * Computes the hash across all the memory region 282 * @buf of length @len. The @digest pointer will be 283 * filled with the printable hex digest of the computed 284 * hash, which will be terminated by '\0'. The 285 * memory pointer in @digest must be released 286 * with a call to g_free() when no longer required. 287 * 288 * Returns: 0 on success, -1 on error 289 */ 290 int qcrypto_hash_digest(QCryptoHashAlgo alg, 291 const char *buf, 292 size_t len, 293 char **digest, 294 Error **errp); 295 296 /** 297 * qcrypto_hash_base64v: 298 * @alg: the hash algorithm 299 * @iov: the array of memory regions to hash 300 * @niov: the length of @iov 301 * @base64: pointer to hold output hash 302 * @errp: pointer to a NULL-initialized error object 303 * 304 * Computes the hash across all the memory regions 305 * present in @iov. The @base64 pointer will be 306 * filled with the base64 encoding of the computed 307 * hash, which will be terminated by '\0'. The 308 * memory pointer in @base64 must be released 309 * with a call to g_free() when no longer required. 310 * 311 * Returns: 0 on success, -1 on error 312 */ 313 int qcrypto_hash_base64v(QCryptoHashAlgo alg, 314 const struct iovec *iov, 315 size_t niov, 316 char **base64, 317 Error **errp); 318 319 /** 320 * qcrypto_hash_base64: 321 * @alg: the hash algorithm 322 * @buf: the memory region to hash 323 * @len: the length of @buf 324 * @base64: pointer to hold output hash 325 * @errp: pointer to a NULL-initialized error object 326 * 327 * Computes the hash across all the memory region 328 * @buf of length @len. The @base64 pointer will be 329 * filled with the base64 encoding of the computed 330 * hash, which will be terminated by '\0'. The 331 * memory pointer in @base64 must be released 332 * with a call to g_free() when no longer required. 333 * 334 * Returns: 0 on success, -1 on error 335 */ 336 int qcrypto_hash_base64(QCryptoHashAlgo alg, 337 const char *buf, 338 size_t len, 339 char **base64, 340 Error **errp); 341 342 #endif /* QCRYPTO_HASH_H */ 343