From f26f4ee6e7f01a15eff7bb075133f9bd8b5857b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Frauenschl=C3=A4ger?= Date: Tue, 3 Nov 2026 09:55:41 +0100 Subject: [PATCH] doc: note the alignment of wolfCrypt context structures wc_Sha256, wc_Sha224, Hmac, Aes, curve25519_key and ed25519_key declare 16-byte aligned members, directly or through an embedded context, so the structures themselves need 16-byte alignment when WOLFSSL_USE_ALIGN is defined. configure (--enable-aligndata) and CMake (WOLFSSL_ALIGN_DATA) define it by default, and types.h forces it for AES-NI, Intel speedups, ARM assembly, Xilinx and 32-bit ARM without unaligned access. For the SHA-256 context and Hmac this applies on 64-bit CPUs, unless a hardware port replaces the software hash state. On Xilinx Versal, Aes needs 64-byte alignment. The compiler may use aligned loads and stores on these structures, so an instance placed at an arbitrary offset inside a larger buffer can crash, as seen with wc_Sha256 contexts in curl's HMAC code on x86_64. Add a note to the init functions of these structures: wc_InitSha256(), wc_InitSha224() and their _ex variants, wc_AesInit(), and wc_curve25519_init() and wc_ed25519_init() with their _ex variants. wc_HmacInit() had no doxygen entry, so add one to carry the Hmac note, and reference it from wc_HmacSetKey(). --- doc/dox_comments/header_files/aes.h | 3 ++ doc/dox_comments/header_files/curve25519.h | 6 ++++ doc/dox_comments/header_files/ed25519.h | 6 ++++ doc/dox_comments/header_files/hmac.h | 36 ++++++++++++++++++++++ doc/dox_comments/header_files/sha256.h | 12 ++++++++ 5 files changed, 63 insertions(+) diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index f39d1c5ee68..6bfb342ae97 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -1098,6 +1098,9 @@ int wc_AesXtsFree(XtsAes* aes); \param heap heap hint to use for malloc / free if needed \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used + \note Aes has 16-byte alignment (64 on Xilinx Versal) if WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code Aes enc; diff --git a/doc/dox_comments/header_files/curve25519.h b/doc/dox_comments/header_files/curve25519.h index 33d276d2841..00d149fdb58 100644 --- a/doc/dox_comments/header_files/curve25519.h +++ b/doc/dox_comments/header_files/curve25519.h @@ -151,6 +151,9 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key, \param [in,out] key Pointer to the curve25519_key structure to initialize. + \note curve25519_key has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code curve25519_key key; @@ -975,6 +978,9 @@ int wc_curve25519_make_priv(WC_RNG* rng, int keysize, byte* priv); \param devId Device ID for hardware acceleration (use INVALID_DEVID for software only) + \note curve25519_key has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code curve25519_key key; diff --git a/doc/dox_comments/header_files/ed25519.h b/doc/dox_comments/header_files/ed25519.h index 4e741c6e3e0..efd9f1939d1 100644 --- a/doc/dox_comments/header_files/ed25519.h +++ b/doc/dox_comments/header_files/ed25519.h @@ -531,6 +531,9 @@ int wc_ed25519ph_verify_msg(const byte* sig, word32 siglen, const byte* msg, \param [in,out] key Pointer to the ed25519_key object to initialize. + \note ed25519_key has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code ed25519_key key; @@ -1246,6 +1249,9 @@ int wc_ed25519_verify_msg_final(const byte* sig, word32 sigLen, \param heap Heap hint for memory allocation \param devId Device ID for hardware acceleration + \note ed25519_key has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code ed25519_key key; diff --git a/doc/dox_comments/header_files/hmac.h b/doc/dox_comments/header_files/hmac.h index d7cc60c79ff..a39f69d8faa 100644 --- a/doc/dox_comments/header_files/hmac.h +++ b/doc/dox_comments/header_files/hmac.h @@ -1,3 +1,38 @@ +/*! + \ingroup HMAC + + \brief This function initializes an Hmac object, setting the heap hint + and the device ID used with crypto callbacks or async hardware. It is up + to the user to call wc_HmacFree on the Hmac object when done. + + \return 0 Returned on successfully initializing the Hmac object + \return BAD_FUNC_ARG Returned if hmac is NULL + + \param hmac pointer to the Hmac object to initialize + \param heap heap hint to use for memory allocation, or NULL + \param devId ID to use with crypto callbacks or async hardware. Set to + INVALID_DEVID (-2) if not used + + \note On 64-bit CPUs, Hmac has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + + _Example_ + \code + Hmac hmac; + byte key[] = { // initialize with key to use for encryption }; + if (wc_HmacInit(&hmac, NULL, INVALID_DEVID) != 0) { + // error initializing Hmac object + } + else if (wc_HmacSetKey(&hmac, WC_SHA256, key, sizeof(key)) != 0) { + // error setting the key + } + wc_HmacFree(&hmac); + \endcode + + \sa wc_HmacSetKey +*/ +int wc_HmacInit(Hmac* hmac, void* heap, int devId); + /*! \ingroup HMAC @@ -29,6 +64,7 @@ } \endcode + \sa wc_HmacInit \sa wc_HmacUpdate \sa wc_HmacFinal */ diff --git a/doc/dox_comments/header_files/sha256.h b/doc/dox_comments/header_files/sha256.h index 8a896ff795f..3ec4f30dd01 100644 --- a/doc/dox_comments/header_files/sha256.h +++ b/doc/dox_comments/header_files/sha256.h @@ -8,6 +8,9 @@ \param sha256 pointer to the sha256 structure to use for encryption + \note On 64-bit CPUs, wc_Sha256 has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code Sha256 sha256[1]; @@ -202,6 +205,9 @@ int wc_Sha256GetHash(wc_Sha256* sha256, byte* hash); \param sha224 Pointer to a Sha224 struct to initialize. + \note On 64-bit CPUs, wc_Sha224 has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code Sha224 sha224; @@ -296,6 +302,9 @@ int wc_Sha224Final(wc_Sha224* sha224, byte* hash); \param heap Heap hint \param devId Device ID + \note On 64-bit CPUs, wc_Sha256 has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code wc_Sha256 sha; @@ -493,6 +502,9 @@ int wc_Sha256GetFlags(wc_Sha256* sha256, word32* flags); \param heap Heap hint \param devId Device ID + \note On 64-bit CPUs, wc_Sha224 has 16-byte alignment when WOLFSSL_USE_ALIGN + is defined (default in configure and CMake, forced for AES-NI and asm). + _Example_ \code wc_Sha224 sha;