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