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/qapi-types-crypto.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 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHmac, qcrypto_hmac_free)
  69
  70 /**
  71  * qcrypto_hmac_bytesv:
  72  * @hmac: the hmac object
  73  * @iov: the array of memory regions to hmac
  74  * @niov: the length of @iov
  75  * @result: pointer to hold output hmac
  76  * @resultlen: pointer to hold length of @result
  77  * @errp: pointer to a NULL-initialized error object
  78  *
  79  * Computes the hmac across all the memory regions
  80  * present in @iov. The @result pointer will be
  81  * filled with raw bytes representing the computed
  82  * hmac, which will have length @resultlen. The
  83  * memory pointer in @result must be released
  84  * with a call to g_free() when no longer required.
  85  *
  86  * Returns:
  87  *  0 on success, -1 on error
  88  */
  89 int qcrypto_hmac_bytesv(QCryptoHmac *hmac,
  90                         const struct iovec *iov,
  91                         size_t niov,
  92                         uint8_t **result,
  93                         size_t *resultlen,
  94                         Error **errp);
  95
  96 /**
  97  * qcrypto_hmac_bytes:
  98  * @hmac: the hmac object
  99  * @buf: the memory region to hmac
 100  * @len: the length of @buf
 101  * @result: pointer to hold output hmac
 102  * @resultlen: pointer to hold length of @result
 103  * @errp: pointer to a NULL-initialized error object
 104  *
 105  * Computes the hmac across all the memory region
 106  * @buf of length @len. The @result pointer will be
 107  * filled with raw bytes representing the computed
 108  * hmac, which will have length @resultlen. The
 109  * memory pointer in @result must be released
 110  * with a call to g_free() when no longer required.
 111  *
 112  * Returns:
 113  *  0 on success, -1 on error
 114  */
 115 int qcrypto_hmac_bytes(QCryptoHmac *hmac,
 116                        const char *buf,
 117                        size_t len,
 118                        uint8_t **result,
 119                        size_t *resultlen,
 120                        Error **errp);
 121
 122 /**
 123  * qcrypto_hmac_digestv:
 124  * @hmac: the hmac object
 125  * @iov: the array of memory regions to hmac
 126  * @niov: the length of @iov
 127  * @digest: pointer to hold output hmac
 128  * @errp: pointer to a NULL-initialized error object
 129  *
 130  * Computes the hmac across all the memory regions
 131  * present in @iov. The @digest pointer will be
 132  * filled with the printable hex digest of the computed
 133  * hmac, which will be terminated by '\0'. The
 134  * memory pointer in @digest must be released
 135  * with a call to g_free() when no longer required.
 136  *
 137  * Returns:
 138  *  0 on success, -1 on error
 139  */
 140 int qcrypto_hmac_digestv(QCryptoHmac *hmac,
 141                          const struct iovec *iov,
 142                          size_t niov,
 143                          char **digest,
 144                          Error **errp);
 145
 146 /**
 147  * qcrypto_hmac_digest:
 148  * @hmac: the hmac object
 149  * @buf: the memory region to hmac
 150  * @len: the length of @buf
 151  * @digest: pointer to hold output hmac
 152  * @errp: pointer to a NULL-initialized error object
 153  *
 154  * Computes the hmac across all the memory region
 155  * @buf of length @len. The @digest pointer will be
 156  * filled with the printable hex digest of the computed
 157  * hmac, which will be terminated by '\0'. The
 158  * memory pointer in @digest 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_hmac_digest(QCryptoHmac *hmac,
 164                         const char *buf,
 165                         size_t len,
 166                         char **digest,
 167                         Error **errp);
 168
 169 #endif