include/crypto/hmac.h

   1 /*
   2  * QEMU Crypto hmac algorithms
   3  *
   4  * Copyright (c) 2016 HUAWEI TECHNOLOGIES CO., LTD.
   5  *
   6  * This work is licensed under the terms of the GNU GPL, version 2 or
   7  * (at your option) any later version.  See the COPYING file in the
   8  * top-level directory.
   9  *
  10  */
  11
  12 #ifndef QCRYPTO_HMAC_H
  13 #define QCRYPTO_HMAC_H
  14
  15 #include "qapi-types.h"
  16
  17 typedef struct QCryptoHmac QCryptoHmac;
  18 struct QCryptoHmac {
  19     QCryptoHashAlgorithm alg;
  20     void *opaque;
  21     void *driver;
  22 };
  23
  24 /**
  25  * qcrypto_hmac_supports:
  26  * @alg: the hmac algorithm
  27  *
  28  * Determine if @alg hmac algorithm is supported by
  29  * the current configured build
  30  *
  31  * Returns:
  32  *  true if the algorithm is supported, false otherwise
  33  */
  34 bool qcrypto_hmac_supports(QCryptoHashAlgorithm alg);
  35
  36 /**
  37  * qcrypto_hmac_new:
  38  * @alg: the hmac algorithm
  39  * @key: the key bytes
  40  * @nkey: the length of @key
  41  * @errp: pointer to a NULL-initialized error object
  42  *
  43  * Creates a new hmac object with the algorithm @alg
  44  *
  45  * The @key parameter provides the bytes representing
  46  * the secret key to use. The @nkey parameter specifies
  47  * the length of @key in bytes
  48  *
  49  * Note: must use qcrypto_hmac_free() to release the
  50  * returned hmac object when no longer required
  51  *
  52  * Returns:
  53  *  a new hmac object, or NULL on error
  54  */
  55 QCryptoHmac *qcrypto_hmac_new(QCryptoHashAlgorithm alg,
  56                               const uint8_t *key, size_t nkey,
  57                               Error **errp);
  58
  59 /**
  60  * qcrypto_hmac_free:
  61  * @hmac: the hmac object
  62  *
  63  * Release the memory associated with @hmac that was
  64  * previously allocated by qcrypto_hmac_new()
  65  */
  66 void qcrypto_hmac_free(QCryptoHmac *hmac);
  67
  68 /**
  69  * qcrypto_hmac_bytesv:
  70  * @hmac: the hmac object
  71  * @iov: the array of memory regions to hmac
  72  * @niov: the length of @iov
  73  * @result: pointer to hold output hmac
  74  * @resultlen: pointer to hold length of @result
  75  * @errp: pointer to a NULL-initialized error object
  76  *
  77  * Computes the hmac across all the memory regions
  78  * present in @iov. The @result pointer will be
  79  * filled with raw bytes representing the computed
  80  * hmac, which will have length @resultlen. The
  81  * memory pointer in @result must be released
  82  * with a call to g_free() when no longer required.
  83  *
  84  * Returns:
  85  *  0 on success, -1 on error
  86  */
  87 int qcrypto_hmac_bytesv(QCryptoHmac *hmac,
  88                         const struct iovec *iov,
  89                         size_t niov,
  90                         uint8_t **result,
  91                         size_t *resultlen,
  92                         Error **errp);
  93
  94 /**
  95  * qcrypto_hmac_bytes:
  96  * @hmac: the hmac object
  97  * @buf: the memory region to hmac
  98  * @len: the length of @buf
  99  * @result: pointer to hold output hmac
 100  * @resultlen: pointer to hold length of @result
 101  * @errp: pointer to a NULL-initialized error object
 102  *
 103  * Computes the hmac across all the memory region
 104  * @buf of length @len. The @result pointer will be
 105  * filled with raw bytes representing the computed
 106  * hmac, which will have length @resultlen. The
 107  * memory pointer in @result must be released
 108  * with a call to g_free() when no longer required.
 109  *
 110  * Returns:
 111  *  0 on success, -1 on error
 112  */
 113 int qcrypto_hmac_bytes(QCryptoHmac *hmac,
 114                        const char *buf,
 115                        size_t len,
 116                        uint8_t **result,
 117                        size_t *resultlen,
 118                        Error **errp);
 119
 120 /**
 121  * qcrypto_hmac_digestv:
 122  * @hmac: the hmac object
 123  * @iov: the array of memory regions to hmac
 124  * @niov: the length of @iov
 125  * @digest: pointer to hold output hmac
 126  * @errp: pointer to a NULL-initialized error object
 127  *
 128  * Computes the hmac across all the memory regions
 129  * present in @iov. The @digest pointer will be
 130  * filled with the printable hex digest of the computed
 131  * hmac, which will be terminated by '\0'. The
 132  * memory pointer in @digest must be released
 133  * with a call to g_free() when no longer required.
 134  *
 135  * Returns:
 136  *  0 on success, -1 on error
 137  */
 138 int qcrypto_hmac_digestv(QCryptoHmac *hmac,
 139                          const struct iovec *iov,
 140                          size_t niov,
 141                          char **digest,
 142                          Error **errp);
 143
 144 /**
 145  * qcrypto_hmac_digest:
 146  * @hmac: the hmac object
 147  * @buf: the memory region to hmac
 148  * @len: the length of @buf
 149  * @digest: pointer to hold output hmac
 150  * @errp: pointer to a NULL-initialized error object
 151  *
 152  * Computes the hmac across all the memory region
 153  * @buf of length @len. The @digest pointer will be
 154  * filled with the printable hex digest of the computed
 155  * hmac, which will be terminated by '\0'. The
 156  * memory pointer in @digest must be released
 157  * with a call to g_free() when no longer required.
 158  *
 159  * Returns: 0 on success, -1 on error
 160  */
 161 int qcrypto_hmac_digest(QCryptoHmac *hmac,
 162                         const char *buf,
 163                         size_t len,
 164                         char **digest,
 165                         Error **errp);
 166
 167 #endif