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. The @result pointer will be 77 * filled with raw bytes representing the computed 78 * hash, which will have length @resultlen. The 79 * memory pointer in @result must be released 80 * with a call to g_free() when no longer required. 81 * 82 * Returns: 0 on success, -1 on error 83 */ 84 int qcrypto_hash_bytesv(QCryptoHashAlgo alg, 85 const struct iovec *iov, 86 size_t niov, 87 uint8_t **result, 88 size_t *resultlen, 89 Error **errp); 90 91 /** 92 * qcrypto_hash_bytes: 93 * @alg: the hash algorithm 94 * @buf: the memory region to hash 95 * @len: the length of @buf 96 * @result: pointer to hold output hash 97 * @resultlen: pointer to hold length of @result 98 * @errp: pointer to a NULL-initialized error object 99 * 100 * Computes the hash across all the memory region 101 * @buf of length @len. The @result pointer will be 102 * filled with raw bytes representing the computed 103 * hash, which will have length @resultlen. The 104 * memory pointer in @result must be released 105 * with a call to g_free() when no longer required. 106 * 107 * Returns: 0 on success, -1 on error 108 */ 109 int qcrypto_hash_bytes(QCryptoHashAlgo alg, 110 const char *buf, 111 size_t len, 112 uint8_t **result, 113 size_t *resultlen, 114 Error **errp); 115 116 /** 117 * qcrypto_hash_digestv: 118 * @alg: the hash algorithm 119 * @iov: the array of memory regions to hash 120 * @niov: the length of @iov 121 * @digest: pointer to hold output hash 122 * @errp: pointer to a NULL-initialized error object 123 * 124 * Computes the hash across all the memory regions 125 * present in @iov. The @digest pointer will be 126 * filled with the printable hex digest of the computed 127 * hash, which will be terminated by '\0'. The 128 * memory pointer in @digest must be released 129 * with a call to g_free() when no longer required. 130 * 131 * Returns: 0 on success, -1 on error 132 */ 133 int qcrypto_hash_digestv(QCryptoHashAlgo alg, 134 const struct iovec *iov, 135 size_t niov, 136 char **digest, 137 Error **errp); 138 139 /** 140 * qcrypto_hash_updatev: 141 * @hash: hash object from qcrypto_hash_new 142 * @iov: the array of memory regions to hash 143 * @niov: the length of @iov 144 * @errp: pointer to a NULL-initialized error object 145 * 146 * Updates the given hash object with all the memory regions 147 * present in @iov. 148 * 149 * Returns: 0 on success, -1 on error 150 */ 151 int qcrypto_hash_updatev(QCryptoHash *hash, 152 const struct iovec *iov, 153 size_t niov, 154 Error **errp); 155 /** 156 * qcrypto_hash_update: 157 * @hash: hash object from qcrypto_hash_new 158 * @buf: the memory region to hash 159 * @len: the length of @buf 160 * @errp: pointer to a NULL-initialized error object 161 * 162 * Updates the given hash object with the data from 163 * the given buffer. 164 * 165 * Returns: 0 on success, -1 on error 166 */ 167 int qcrypto_hash_update(QCryptoHash *hash, 168 const char *buf, 169 size_t len, 170 Error **errp); 171 172 /** 173 * qcrypto_hash_finalize_digest: 174 * @hash: the hash object to finalize 175 * @digest: pointer to hold output hash 176 * @errp: pointer to a NULL-initialized error object 177 * 178 * Computes the hash from the given hash object. Hash object 179 * is expected to have its data updated from the qcrypto_hash_update function. 180 * The @digest pointer will be filled with the printable hex digest of the 181 * computed hash, which will be terminated by '\0'. The memory pointer 182 * in @digest must be released with a call to g_free() when 183 * no longer required. 184 * 185 * Returns: 0 on success, -1 on error 186 */ 187 int qcrypto_hash_finalize_digest(QCryptoHash *hash, 188 char **digest, 189 Error **errp); 190 191 /** 192 * qcrypto_hash_finalize_base64: 193 * @hash_ctx: hash object to finalize 194 * @base64: pointer to store the hash result in 195 * @errp: pointer to a NULL-initialized error object 196 * 197 * Computes the hash from the given hash object. Hash object 198 * is expected to have it's data updated from the qcrypto_hash_update function. 199 * The @base64 pointer will be filled with the base64 encoding of the computed 200 * hash, which will be terminated by '\0'. The memory pointer in @base64 201 * must be released with a call to g_free() when no longer required. 202 * 203 * Returns: 0 on success, -1 on error 204 */ 205 int qcrypto_hash_finalize_base64(QCryptoHash *hash, 206 char **base64, 207 Error **errp); 208 209 /** 210 * qcrypto_hash_finalize_bytes: 211 * @hash_ctx: hash object to finalize 212 * @result: pointer to store the hash result in 213 * @result_len: Pointer to store the length of the result in 214 * @errp: pointer to a NULL-initialized error object 215 * 216 * Computes the hash from the given hash object. Hash object 217 * is expected to have it's data updated from the qcrypto_hash_update function. 218 * The memory pointer in @result must be released with a call to g_free() 219 * when no longer required. 220 * 221 * Returns: 0 on success, -1 on error 222 */ 223 int qcrypto_hash_finalize_bytes(QCryptoHash *hash, 224 uint8_t **result, 225 size_t *result_len, 226 Error **errp); 227 228 /** 229 * qcrypto_hash_new: 230 * @alg: the hash algorithm 231 * @errp: pointer to a NULL-initialized error object 232 * 233 * Creates a new hashing context for the chosen algorithm for 234 * usage with qcrypto_hash_update. 235 * 236 * Returns: New hash object with the given algorithm, or NULL on error. 237 */ 238 QCryptoHash *qcrypto_hash_new(QCryptoHashAlgo alg, Error **errp); 239 240 /** 241 * qcrypto_hash_free: 242 * @hash: hash object to free 243 * 244 * Frees a hashing context for the chosen algorithm. 245 */ 246 void qcrypto_hash_free(QCryptoHash *hash); 247 248 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHash, qcrypto_hash_free) 249 250 /** 251 * qcrypto_hash_digest: 252 * @alg: the hash algorithm 253 * @buf: the memory region to hash 254 * @len: the length of @buf 255 * @digest: pointer to hold output hash 256 * @errp: pointer to a NULL-initialized error object 257 * 258 * Computes the hash across all the memory region 259 * @buf of length @len. The @digest pointer will be 260 * filled with the printable hex digest of the computed 261 * hash, which will be terminated by '\0'. The 262 * memory pointer in @digest must be released 263 * with a call to g_free() when no longer required. 264 * 265 * Returns: 0 on success, -1 on error 266 */ 267 int qcrypto_hash_digest(QCryptoHashAlgo alg, 268 const char *buf, 269 size_t len, 270 char **digest, 271 Error **errp); 272 273 /** 274 * qcrypto_hash_base64v: 275 * @alg: the hash algorithm 276 * @iov: the array of memory regions to hash 277 * @niov: the length of @iov 278 * @base64: pointer to hold output hash 279 * @errp: pointer to a NULL-initialized error object 280 * 281 * Computes the hash across all the memory regions 282 * present in @iov. The @base64 pointer will be 283 * filled with the base64 encoding of the computed 284 * hash, which will be terminated by '\0'. The 285 * memory pointer in @base64 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_base64v(QCryptoHashAlgo alg, 291 const struct iovec *iov, 292 size_t niov, 293 char **base64, 294 Error **errp); 295 296 /** 297 * qcrypto_hash_base64: 298 * @alg: the hash algorithm 299 * @buf: the memory region to hash 300 * @len: the length of @buf 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 region 305 * @buf of length @len. 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_base64(QCryptoHashAlgo alg, 314 const char *buf, 315 size_t len, 316 char **base64, 317 Error **errp); 318 319 #endif /* QCRYPTO_HASH_H */ 320