include/crypto/hash.h

   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 */