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 QCryptoHashAlgo 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(QCryptoHashAlgo 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(QCryptoHashAlgo 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. 81 * 82 * If @result_len is set to a non-zero value by the caller, then 83 * @result must hold a pointer that is @result_len in size, and 84 * @result_len match the size of the hash output. The digest will 85 * be written into @result. 86 * 87 * If @result_len is set to zero, then this function will allocate 88 * a buffer to hold the hash output digest, storing a pointer to 89 * the buffer in @result, and setting @result_len to its size. 90 * The memory referenced in @result must be released with a call 91 * to g_free() when no longer required by the caller. 92 * 93 * Returns: 94 * 0 on success, -1 on error 95 */ 96 int qcrypto_hmac_bytesv(QCryptoHmac *hmac, 97 const struct iovec *iov, 98 size_t niov, 99 uint8_t **result, 100 size_t *resultlen, 101 Error **errp); 102 103 /** 104 * qcrypto_hmac_bytes: 105 * @hmac: the hmac object 106 * @buf: the memory region to hmac 107 * @len: the length of @buf 108 * @result: pointer to hold output hmac 109 * @resultlen: pointer to hold length of @result 110 * @errp: pointer to a NULL-initialized error object 111 * 112 * Computes the hmac across all the memory region 113 * @buf of length @len. 114 * 115 * If @result_len is set to a non-zero value by the caller, then 116 * @result must hold a pointer that is @result_len in size, and 117 * @result_len match the size of the hash output. The digest will 118 * be written into @result. 119 * 120 * If @result_len is set to zero, then this function will allocate 121 * a buffer to hold the hash output digest, storing a pointer to 122 * the buffer in @result, and setting @result_len to its size. 123 * The memory referenced in @result must be released with a call 124 * to g_free() when no longer required by the caller. 125 * 126 * Returns: 127 * 0 on success, -1 on error 128 */ 129 int qcrypto_hmac_bytes(QCryptoHmac *hmac, 130 const char *buf, 131 size_t len, 132 uint8_t **result, 133 size_t *resultlen, 134 Error **errp); 135 136 /** 137 * qcrypto_hmac_digestv: 138 * @hmac: the hmac object 139 * @iov: the array of memory regions to hmac 140 * @niov: the length of @iov 141 * @digest: pointer to hold output hmac 142 * @errp: pointer to a NULL-initialized error object 143 * 144 * Computes the hmac across all the memory regions 145 * present in @iov. The @digest pointer will be 146 * filled with the printable hex digest of the computed 147 * hmac, which will be terminated by '\0'. The 148 * memory pointer in @digest must be released 149 * with a call to g_free() when no longer required. 150 * 151 * Returns: 152 * 0 on success, -1 on error 153 */ 154 int qcrypto_hmac_digestv(QCryptoHmac *hmac, 155 const struct iovec *iov, 156 size_t niov, 157 char **digest, 158 Error **errp); 159 160 /** 161 * qcrypto_hmac_digest: 162 * @hmac: the hmac object 163 * @buf: the memory region to hmac 164 * @len: the length of @buf 165 * @digest: pointer to hold output hmac 166 * @errp: pointer to a NULL-initialized error object 167 * 168 * Computes the hmac across all the memory region 169 * @buf of length @len. The @digest pointer will be 170 * filled with the printable hex digest of the computed 171 * hmac, which will be terminated by '\0'. The 172 * memory pointer in @digest must be released 173 * with a call to g_free() when no longer required. 174 * 175 * Returns: 0 on success, -1 on error 176 */ 177 int qcrypto_hmac_digest(QCryptoHmac *hmac, 178 const char *buf, 179 size_t len, 180 char **digest, 181 Error **errp); 182 183 #endif 184