mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-01-28 04:12:20 +01:00
77d9410aa0
This PR adds Doxygen documentation for native wolfSSL API functions that were previously undocumented. It includes documentation notes for APIs gated on specific preprocessor macros: - WOLF_PRIVATE_KEY_ID: _Id and _Label init helpers (wc_AesInit_Id, wc_AesInit_Label, wc_ecc_init_id, wc_ecc_init_label, wc_InitRsaKey_Id, wc_InitRsaKey_Label) require this for PKCS11 support - WC_NO_CONSTRUCTORS: New/Delete constructor functions (wc_AesNew/Delete, wc_curve25519_new/delete, wc_ed25519_new/delete, wc_NewRsaKey/DeleteRsaKey) are only available when this is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined. - WOLFSSL_PUBLIC_ASN: ASN functions marked with WOLFSSL_ASN_API include notes indicating they are not public by default - WOLFSSL_DUAL_ALG_CERTS: wc_GeneratePreTBS and wc_MakeSigWithBitStr for Post-Quantum dual algorithm certificate signing The New/Delete functions are documented as being exposed to support allocation of structures using dynamic memory to provide better ABI compatibility.
288 lines
8.1 KiB
C
288 lines
8.1 KiB
C
/*!
|
|
\ingroup CMAC
|
|
\brief Initialize the Cmac structure with defaults
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
\param key key pointer
|
|
\param keySz size of the key pointer (16, 24 or 32)
|
|
\param type Always WC_CMAC_AES = 1
|
|
\param unused not used, exists for potential future use around compatibility
|
|
|
|
_Example_
|
|
\code
|
|
Cmac cmac[1];
|
|
ret = wc_InitCmac(cmac, key, keySz, WC_CMAC_AES, NULL);
|
|
if (ret == 0) {
|
|
ret = wc_CmacUpdate(cmac, in, inSz);
|
|
}
|
|
if (ret == 0) {
|
|
ret = wc_CmacFinal(cmac, out, outSz);
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_InitCmac_ex
|
|
\sa wc_CmacUpdate
|
|
\sa wc_CmacFinal
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_InitCmac(Cmac* cmac,
|
|
const byte* key, word32 keySz,
|
|
int type, void* unused);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Initialize the Cmac structure with defaults
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
\param key key pointer
|
|
\param keySz size of the key pointer (16, 24 or 32)
|
|
\param type Always WC_CMAC_AES = 1
|
|
\param unused not used, exists for potential future use around compatibility
|
|
\param heap pointer to the heap hint used for dynamic allocation. Typically used with our static memory option. Can be NULL.
|
|
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
|
|
|
|
_Example_
|
|
\code
|
|
Cmac cmac[1];
|
|
ret = wc_InitCmac_ex(cmac, key, keySz, WC_CMAC_AES, NULL, NULL, INVALID_DEVID);
|
|
if (ret == 0) {
|
|
ret = wc_CmacUpdate(cmac, in, inSz);
|
|
}
|
|
if (ret == 0) {
|
|
ret = wc_CmacFinal(cmac, out, &outSz);
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_InitCmac_ex
|
|
\sa wc_CmacUpdate
|
|
\sa wc_CmacFinal
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_InitCmac_ex(Cmac* cmac,
|
|
const byte* key, word32 keySz,
|
|
int type, void* unused, void* heap, int devId);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Add Cipher-based Message Authentication Code input data
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
\param in input data to process
|
|
\param inSz size of input data
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_CmacUpdate(cmac, in, inSz);
|
|
\endcode
|
|
|
|
\sa wc_InitCmac
|
|
\sa wc_CmacFinal
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_CmacUpdate(Cmac* cmac,
|
|
const byte* in, word32 inSz);
|
|
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Generate the final result using Cipher-based Message Authentication Code, deferring context cleanup.
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
\param out pointer to return the result
|
|
\param outSz pointer size of output (in/out)
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_CmacFinalNoFree(cmac, out, &outSz);
|
|
(void)wc_CmacFree(cmac);
|
|
\endcode
|
|
|
|
\sa wc_InitCmac
|
|
\sa wc_CmacFinal
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_CmacFinalNoFree(Cmac* cmac,
|
|
byte* out, word32* outSz);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Generate the final result using Cipher-based Message Authentication Code, and clean up the context with wc_CmacFree().
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
\param out pointer to return the result
|
|
\param outSz pointer size of output (in/out)
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_CmacFinal(cmac, out, &outSz);
|
|
\endcode
|
|
|
|
\sa wc_InitCmac
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_CmacFinal(Cmac* cmac,
|
|
byte* out, word32* outSz);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Clean up allocations in a CMAC context.
|
|
\return 0 on success
|
|
\param cmac pointer to the Cmac structure
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_CmacFinalNoFree(cmac, out, &outSz);
|
|
(void)wc_CmacFree(cmac);
|
|
\endcode
|
|
|
|
\sa wc_InitCmac
|
|
\sa wc_CmacFinalNoFree
|
|
\sa wc_CmacFinal
|
|
\sa wc_CmacFree
|
|
*/
|
|
int wc_CmacFree(Cmac* cmac);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Single shot function for generating a CMAC
|
|
\return 0 on success
|
|
\param out pointer to return the result
|
|
\param outSz pointer size of output (in/out)
|
|
\param in input data to process
|
|
\param inSz size of input data
|
|
\param key key pointer
|
|
\param keySz size of the key pointer (16, 24 or 32)
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_AesCmacGenerate(mac, &macSz, msg, msgSz, key, keySz);
|
|
\endcode
|
|
|
|
\sa wc_AesCmacVerify
|
|
*/
|
|
int wc_AesCmacGenerate(byte* out, word32* outSz,
|
|
const byte* in, word32 inSz,
|
|
const byte* key, word32 keySz);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Single shot function for validating a CMAC
|
|
\return 0 on success
|
|
\param check CMAC value to verify
|
|
\param checkSz size of check buffer
|
|
\param in input data to process
|
|
\param inSz size of input data
|
|
\param key key pointer
|
|
\param keySz size of the key pointer (16, 24 or 32)
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_AesCmacVerify(mac, macSz, msg, msgSz, key, keySz);
|
|
\endcode
|
|
|
|
\sa wc_AesCmacGenerate
|
|
*/
|
|
int wc_AesCmacVerify(const byte* check, word32 checkSz,
|
|
const byte* in, word32 inSz,
|
|
const byte* key, word32 keySz);
|
|
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Only used with WOLFSSL_HASH_KEEP when hardware requires single-shot and the updates must be cached in memory
|
|
\return 0 on success
|
|
\param in input data to process
|
|
\param inSz size of input data
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_CMAC_Grow(cmac, in, inSz)
|
|
\endcode
|
|
*/
|
|
int wc_CMAC_Grow(Cmac* cmac, const byte* in, int inSz);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Single shot AES-CMAC generation with extended parameters
|
|
including heap and device ID.
|
|
|
|
\return 0 on success
|
|
\return BAD_FUNC_ARG if parameters are invalid
|
|
|
|
\param cmac Pointer to Cmac structure (can be NULL for one-shot)
|
|
\param out Buffer to store MAC output
|
|
\param outSz Pointer to output size (in/out)
|
|
\param in Input data to authenticate
|
|
\param inSz Length of input data
|
|
\param key AES key
|
|
\param keySz Key size (16, 24, or 32 bytes)
|
|
\param heap Heap hint for memory allocation (can be NULL)
|
|
\param devId Device ID for hardware acceleration (use
|
|
INVALID_DEVID for software)
|
|
|
|
_Example_
|
|
\code
|
|
byte mac[AES_BLOCK_SIZE];
|
|
word32 macSz = sizeof(mac);
|
|
byte key[16], msg[64];
|
|
|
|
int ret = wc_AesCmacGenerate_ex(NULL, mac, &macSz, msg,
|
|
sizeof(msg), key, sizeof(key),
|
|
NULL, INVALID_DEVID);
|
|
\endcode
|
|
|
|
\sa wc_AesCmacGenerate
|
|
\sa wc_AesCmacVerify_ex
|
|
*/
|
|
int wc_AesCmacGenerate_ex(Cmac *cmac, byte* out, word32* outSz,
|
|
const byte* in, word32 inSz,
|
|
const byte* key, word32 keySz,
|
|
void* heap, int devId);
|
|
|
|
/*!
|
|
\ingroup CMAC
|
|
\brief Single shot AES-CMAC verification with extended parameters
|
|
including heap and device ID.
|
|
|
|
\return 0 on success
|
|
\return BAD_FUNC_ARG if parameters are invalid
|
|
\return MAC_CMP_FAILED_E if MAC verification fails
|
|
|
|
\param cmac Pointer to Cmac structure (can be NULL for one-shot)
|
|
\param check Expected MAC value to verify
|
|
\param checkSz Size of expected MAC
|
|
\param in Input data to authenticate
|
|
\param inSz Length of input data
|
|
\param key AES key
|
|
\param keySz Key size (16, 24, or 32 bytes)
|
|
\param heap Heap hint for memory allocation (can be NULL)
|
|
\param devId Device ID for hardware acceleration (use
|
|
INVALID_DEVID for software)
|
|
|
|
_Example_
|
|
\code
|
|
byte mac[AES_BLOCK_SIZE];
|
|
byte key[16], msg[64];
|
|
|
|
int ret = wc_AesCmacVerify_ex(NULL, mac, sizeof(mac), msg,
|
|
sizeof(msg), key, sizeof(key),
|
|
NULL, INVALID_DEVID);
|
|
if (ret == MAC_CMP_FAILED_E) {
|
|
// MAC verification failed
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_AesCmacVerify
|
|
\sa wc_AesCmacGenerate_ex
|
|
*/
|
|
int wc_AesCmacVerify_ex(Cmac* cmac, const byte* check, word32 checkSz,
|
|
const byte* in, word32 inSz,
|
|
const byte* key, word32 keySz,
|
|
void* heap, int devId);
|