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 "qapi-types.h"
  25
  26 /* See also "QCryptoHashAlgorithm" defined in qapi/crypto.json */
  27
  28 /**
  29  * qcrypto_hash_supports:
  30  * @alg: the hash algorithm
  31  *
  32  * Determine if @alg hash algorithm is supported by the
  33  * current configured build.
  34  *
  35  * Returns: true if the algorithm is supported, false otherwise
  36  */
  37 gboolean qcrypto_hash_supports(QCryptoHashAlgorithm alg);
  38
  39
  40 /**
  41  * qcrypto_hash_digest_len:
  42  * @alg: the hash algorithm
  43  *
  44  * Determine the size of the hash digest in bytes
  45  *
  46  * Returns: the digest length in bytes
  47  */
  48 size_t qcrypto_hash_digest_len(QCryptoHashAlgorithm alg);
  49
  50 /**
  51  * qcrypto_hash_bytesv:
  52  * @alg: the hash algorithm
  53  * @iov: the array of memory regions to hash
  54  * @niov: the length of @iov
  55  * @result: pointer to hold output hash
  56  * @resultlen: pointer to hold length of @result
  57  * @errp: pointer to a NULL-initialized error object
  58  *
  59  * Computes the hash across all the memory regions
  60  * present in @iov. The @result pointer will be
  61  * filled with raw bytes representing the computed
  62  * hash, which will have length @resultlen. The
  63  * memory pointer in @result must be released
  64  * with a call to g_free() when no longer required.
  65  *
  66  * Returns: 0 on success, -1 on error
  67  */
  68 int qcrypto_hash_bytesv(QCryptoHashAlgorithm alg,
  69                         const struct iovec *iov,
  70                         size_t niov,
  71                         uint8_t **result,
  72                         size_t *resultlen,
  73                         Error **errp);
  74
  75 /**
  76  * qcrypto_hash_bytes:
  77  * @alg: the hash algorithm
  78  * @buf: the memory region to hash
  79  * @len: the length of @buf
  80  * @result: pointer to hold output hash
  81  * @resultlen: pointer to hold length of @result
  82  * @errp: pointer to a NULL-initialized error object
  83  *
  84  * Computes the hash across all the memory region
  85  * @buf of length @len. The @result pointer will be
  86  * filled with raw bytes representing the computed
  87  * hash, which will have length @resultlen. The
  88  * memory pointer in @result must be released
  89  * with a call to g_free() when no longer required.
  90  *
  91  * Returns: 0 on success, -1 on error
  92  */
  93 int qcrypto_hash_bytes(QCryptoHashAlgorithm alg,
  94                        const char *buf,
  95                        size_t len,
  96                        uint8_t **result,
  97                        size_t *resultlen,
  98                        Error **errp);
  99
 100 /**
 101  * qcrypto_hash_digestv:
 102  * @alg: the hash algorithm
 103  * @iov: the array of memory regions to hash
 104  * @niov: the length of @iov
 105  * @digest: pointer to hold output hash
 106  * @errp: pointer to a NULL-initialized error object
 107  *
 108  * Computes the hash across all the memory regions
 109  * present in @iov. The @digest pointer will be
 110  * filled with the printable hex digest of the computed
 111  * hash, which will be terminated by '\0'. The
 112  * memory pointer in @digest must be released
 113  * with a call to g_free() when no longer required.
 114  *
 115  * Returns: 0 on success, -1 on error
 116  */
 117 int qcrypto_hash_digestv(QCryptoHashAlgorithm alg,
 118                          const struct iovec *iov,
 119                          size_t niov,
 120                          char **digest,
 121                          Error **errp);
 122
 123 /**
 124  * qcrypto_hash_digest:
 125  * @alg: the hash algorithm
 126  * @buf: the memory region to hash
 127  * @len: the length of @buf
 128  * @digest: pointer to hold output hash
 129  * @errp: pointer to a NULL-initialized error object
 130  *
 131  * Computes the hash across all the memory region
 132  * @buf of length @len. The @digest pointer will be
 133  * filled with the printable hex digest of the computed
 134  * hash, which will be terminated by '\0'. The
 135  * memory pointer in @digest must be released
 136  * with a call to g_free() when no longer required.
 137  *
 138  * Returns: 0 on success, -1 on error
 139  */
 140 int qcrypto_hash_digest(QCryptoHashAlgorithm alg,
 141                         const char *buf,
 142                         size_t len,
 143                         char **digest,
 144                         Error **errp);
 145
 146 /**
 147  * qcrypto_hash_base64v:
 148  * @alg: the hash algorithm
 149  * @iov: the array of memory regions to hash
 150  * @niov: the length of @iov
 151  * @base64: pointer to hold output hash
 152  * @errp: pointer to a NULL-initialized error object
 153  *
 154  * Computes the hash across all the memory regions
 155  * present in @iov. The @base64 pointer will be
 156  * filled with the base64 encoding of the computed
 157  * hash, which will be terminated by '\0'. The
 158  * memory pointer in @base64 must be released
 159  * with a call to g_free() when no longer required.
 160  *
 161  * Returns: 0 on success, -1 on error
 162  */
 163 int qcrypto_hash_base64v(QCryptoHashAlgorithm alg,
 164                          const struct iovec *iov,
 165                          size_t niov,
 166                          char **base64,
 167                          Error **errp);
 168
 169 /**
 170  * qcrypto_hash_base64:
 171  * @alg: the hash algorithm
 172  * @buf: the memory region to hash
 173  * @len: the length of @buf
 174  * @base64: pointer to hold output hash
 175  * @errp: pointer to a NULL-initialized error object
 176  *
 177  * Computes the hash across all the memory region
 178  * @buf of length @len. The @base64 pointer will be
 179  * filled with the base64 encoding of the computed
 180  * hash, which will be terminated by '\0'. The
 181  * memory pointer in @base64 must be released
 182  * with a call to g_free() when no longer required.
 183  *
 184  * Returns: 0 on success, -1 on error
 185  */
 186 int qcrypto_hash_base64(QCryptoHashAlgorithm alg,
 187                         const char *buf,
 188                         size_t len,
 189                         char **base64,
 190                         Error **errp);
 191
 192 #endif /* QCRYPTO_HASH_H */