include/crypto/hash.h

   1 /*
   2  * QEMU Crypto hash algorithms
   3  *
   4  * Copyright (c) 2015 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #ifndef QCRYPTO_HASH_H__
  22 #define QCRYPTO_HASH_H__
  23
  24 #include "qemu-common.h"
  25 #include "qapi/error.h"
  26
  27 /* See also "QCryptoHashAlgorithm" defined in qapi/crypto.json */
  28
  29 /**
  30  * qcrypto_hash_supports:
  31  * @alg: the hash algorithm
  32  *
  33  * Determine if @alg hash algorithm is supported by the
  34  * current configured build.
  35  *
  36  * Returns: true if the algorithm is supported, false otherwise
  37  */
  38 gboolean qcrypto_hash_supports(QCryptoHashAlgorithm alg);
  39
  40
  41 /**
  42  * qcrypto_hash_digest_len:
  43  * @alg: the hash algorithm
  44  *
  45  * Determine the size of the hash digest in bytes
  46  *
  47  * Returns: the digest length in bytes
  48  */
  49 size_t qcrypto_hash_digest_len(QCryptoHashAlgorithm alg);
  50
  51 /**
  52  * qcrypto_hash_bytesv:
  53  * @alg: the hash algorithm
  54  * @iov: the array of memory regions to hash
  55  * @niov: the length of @iov
  56  * @result: pointer to hold output hash
  57  * @resultlen: pointer to hold length of @result
  58  * @errp: pointer to uninitialized error object
  59  *
  60  * Computes the hash across all the memory regions
  61  * present in @iov. The @result pointer will be
  62  * filled with raw bytes representing the computed
  63  * hash, which will have length @resultlen. The
  64  * memory pointer in @result must be released
  65  * with a call to g_free() when no longer required.
  66  *
  67  * Returns: 0 on success, -1 on error
  68  */
  69 int qcrypto_hash_bytesv(QCryptoHashAlgorithm alg,
  70                         const struct iovec *iov,
  71                         size_t niov,
  72                         uint8_t **result,
  73                         size_t *resultlen,
  74                         Error **errp);
  75
  76 /**
  77  * qcrypto_hash_bytes:
  78  * @alg: the hash algorithm
  79  * @buf: the memory region to hash
  80  * @len: the length of @buf
  81  * @result: pointer to hold output hash
  82  * @resultlen: pointer to hold length of @result
  83  * @errp: pointer to uninitialized error object
  84  *
  85  * Computes the hash across all the memory region
  86  * @buf of length @len. The @result pointer will be
  87  * filled with raw bytes representing the computed
  88  * hash, which will have length @resultlen. The
  89  * memory pointer in @result must be released
  90  * with a call to g_free() when no longer required.
  91  *
  92  * Returns: 0 on success, -1 on error
  93  */
  94 int qcrypto_hash_bytes(QCryptoHashAlgorithm alg,
  95                        const char *buf,
  96                        size_t len,
  97                        uint8_t **result,
  98                        size_t *resultlen,
  99                        Error **errp);
 100
 101 /**
 102  * qcrypto_hash_digestv:
 103  * @alg: the hash algorithm
 104  * @iov: the array of memory regions to hash
 105  * @niov: the length of @iov
 106  * @digest: pointer to hold output hash
 107  * @errp: pointer to uninitialized error object
 108  *
 109  * Computes the hash across all the memory regions
 110  * present in @iov. The @digest pointer will be
 111  * filled with the printable hex digest of the computed
 112  * hash, which will be terminated by '\0'. The
 113  * memory pointer in @digest must be released
 114  * with a call to g_free() when no longer required.
 115  *
 116  * Returns: 0 on success, -1 on error
 117  */
 118 int qcrypto_hash_digestv(QCryptoHashAlgorithm alg,
 119                          const struct iovec *iov,
 120                          size_t niov,
 121                          char **digest,
 122                          Error **errp);
 123
 124 /**
 125  * qcrypto_hash_digest:
 126  * @alg: the hash algorithm
 127  * @buf: the memory region to hash
 128  * @len: the length of @buf
 129  * @digest: pointer to hold output hash
 130  * @errp: pointer to uninitialized error object
 131  *
 132  * Computes the hash across all the memory region
 133  * @buf of length @len. The @digest pointer will be
 134  * filled with the printable hex digest of the computed
 135  * hash, which will be terminated by '\0'. The
 136  * memory pointer in @digest must be released
 137  * with a call to g_free() when no longer required.
 138  *
 139  * Returns: 0 on success, -1 on error
 140  */
 141 int qcrypto_hash_digest(QCryptoHashAlgorithm alg,
 142                         const char *buf,
 143                         size_t len,
 144                         char **digest,
 145                         Error **errp);
 146
 147 /**
 148  * qcrypto_hash_base64v:
 149  * @alg: the hash algorithm
 150  * @iov: the array of memory regions to hash
 151  * @niov: the length of @iov
 152  * @base64: pointer to hold output hash
 153  * @errp: pointer to uninitialized error object
 154  *
 155  * Computes the hash across all the memory regions
 156  * present in @iov. The @base64 pointer will be
 157  * filled with the base64 encoding of the computed
 158  * hash, which will be terminated by '\0'. The
 159  * memory pointer in @base64 must be released
 160  * with a call to g_free() when no longer required.
 161  *
 162  * Returns: 0 on success, -1 on error
 163  */
 164 int qcrypto_hash_base64v(QCryptoHashAlgorithm alg,
 165                          const struct iovec *iov,
 166                          size_t niov,
 167                          char **base64,
 168                          Error **errp);
 169
 170 /**
 171  * qcrypto_hash_base64:
 172  * @alg: the hash algorithm
 173  * @buf: the memory region to hash
 174  * @len: the length of @buf
 175  * @base64: pointer to hold output hash
 176  * @errp: pointer to uninitialized error object
 177  *
 178  * Computes the hash across all the memory region
 179  * @buf of length @len. The @base64 pointer will be
 180  * filled with the base64 encoding of the computed
 181  * hash, which will be terminated by '\0'. The
 182  * memory pointer in @base64 must be released
 183  * with a call to g_free() when no longer required.
 184  *
 185  * Returns: 0 on success, -1 on error
 186  */
 187 int qcrypto_hash_base64(QCryptoHashAlgorithm alg,
 188                         const char *buf,
 189                         size_t len,
 190                         char **base64,
 191                         Error **errp);
 192
 193 #endif /* QCRYPTO_HASH_H__ */