mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

include/crypto: clarify @result/@result_len for hash/hmac APIs

Browse Source 
The @result parameter passed to hash/hmac APIs may either contain
a pre-allocated buffer, or a buffer can be allocated on the fly.
Clarify these two different usage models in the API docs.

Reviewed-by: Dorjoy Chowdhury <dorjoychy111@gmail.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Daniel P. Berrangé 2024-10-16 11:17:22 +01:00
parent 164f2be1b5
commit 769660955a
2 changed files with 59 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
include/crypto/hash.h
View File

@ -73,11 +73,18 @@ size_t qcrypto_hash_digest_len(QCryptoHashAlgo alg);
* @errp: pointer to a NULL-initialized error object
*
* Computes the hash across all the memory regions
* present in @iov. The @result pointer will be
* filled with raw bytes representing the computed
* hash, which will have length @resultlen. The
* memory pointer in @result must be released
* with a call to g_free() when no longer required.
* present in @iov.
*
* If @result_len is set to a non-zero value by the caller, then
* @result must hold a pointer that is @result_len in size, and
* @result_len match the size of the hash output. The digest will
* be written into @result.
*
* If @result_len is set to zero, then this function will allocate
* a buffer to hold the hash output digest, storing a pointer to
* the buffer in @result, and setting @result_len to its size.
* The memory referenced in @result must be released with a call
* to g_free() when no longer required by the caller.
*
* Returns: 0 on success, -1 on error
*/
@ -98,11 +105,18 @@ int qcrypto_hash_bytesv(QCryptoHashAlgo alg,
* @errp: pointer to a NULL-initialized error object
*
* Computes the hash across all the memory region
* @buf of length @len. The @result pointer will be
* filled with raw bytes representing the computed
* hash, which will have length @resultlen. The
* memory pointer in @result must be released
* with a call to g_free() when no longer required.
* @buf of length @len.
*
* If @result_len is set to a non-zero value by the caller, then
* @result must hold a pointer that is @result_len in size, and
* @result_len match the size of the hash output. The digest will
* be written into @result.
*
* If @result_len is set to zero, then this function will allocate
* a buffer to hold the hash output digest, storing a pointer to
* the buffer in @result, and setting @result_len to its size.
* The memory referenced in @result must be released with a call
* to g_free() when no longer required by the caller.
*
* Returns: 0 on success, -1 on error
*/
@ -215,8 +229,17 @@ int qcrypto_hash_finalize_base64(QCryptoHash *hash,
*
* Computes the hash from the given hash object. Hash object
* is expected to have it's data updated from the qcrypto_hash_update function.
* The memory pointer in @result must be released with a call to g_free()
* when no longer required.
*
* If @result_len is set to a non-zero value by the caller, then
* @result must hold a pointer that is @result_len in size, and
* @result_len match the size of the hash output. The digest will
* be written into @result.
*
* If @result_len is set to zero, then this function will allocate
* a buffer to hold the hash output digest, storing a pointer to
* the buffer in @result, and setting @result_len to its size.
* The memory referenced in @result must be released with a call
* to g_free() when no longer required by the caller.
*
* Returns: 0 on success, -1 on error
*/

34
include/crypto/hmac.h
View File

@ -77,11 +77,18 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoHmac, qcrypto_hmac_free)
* @errp: pointer to a NULL-initialized error object
*
* Computes the hmac across all the memory regions
* present in @iov. The @result pointer will be
* filled with raw bytes representing the computed
* hmac, which will have length @resultlen. The
* memory pointer in @result must be released
* with a call to g_free() when no longer required.
* present in @iov.
*
* If @result_len is set to a non-zero value by the caller, then
* @result must hold a pointer that is @result_len in size, and
* @result_len match the size of the hash output. The digest will
* be written into @result.
*
* If @result_len is set to zero, then this function will allocate
* a buffer to hold the hash output digest, storing a pointer to
* the buffer in @result, and setting @result_len to its size.
* The memory referenced in @result must be released with a call
* to g_free() when no longer required by the caller.
*
* Returns:
* 0 on success, -1 on error
@ -103,11 +110,18 @@ int qcrypto_hmac_bytesv(QCryptoHmac *hmac,
* @errp: pointer to a NULL-initialized error object
*
* Computes the hmac across all the memory region
* @buf of length @len. The @result pointer will be
* filled with raw bytes representing the computed
* hmac, which will have length @resultlen. The
* memory pointer in @result must be released
* with a call to g_free() when no longer required.
* @buf of length @len.
*
* If @result_len is set to a non-zero value by the caller, then
* @result must hold a pointer that is @result_len in size, and
* @result_len match the size of the hash output. The digest will
* be written into @result.
*
* If @result_len is set to zero, then this function will allocate
* a buffer to hold the hash output digest, storing a pointer to
* the buffer in @result, and setting @result_len to its size.
* The memory referenced in @result must be released with a call
* to g_free() when no longer required by the caller.
*
* Returns:
* 0 on success, -1 on error