From 88748b8924746162f429a4c127997d96633fd440 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] wolfSSL: document wolfCrypt structure alignment Some wolfCrypt structures declare 16-byte or larger aligned members when WOLFSSL_USE_ALIGN is defined, which configure and CMake builds do by default, and need memory that meets that alignment. Add a short section to the wolfCrypt Usage Reference that lists when the macro gets defined, which structures it affects and what malloc() guarantees. The section also asks applications to build against the same configuration as the library (options.h or the same user_settings.h), since a mismatch changes the layout regardless of allocation, and notes that a packed enclosing structure can misalign a member. LmsState is listed as a 64-byte case because wc_hss_verify() is public and takes a caller-allocated state whose n-way members are ALIGN64 on x86_64 with USE_INTEL_SPEEDUP or the SHAKE parameter sets. XmssState has the same members but is only reachable through WOLFSSL_LOCAL functions. --- wolfSSL/src/chapter10.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/wolfSSL/src/chapter10.md b/wolfSSL/src/chapter10.md index 4c06ddb3..ec1c272a 100644 --- a/wolfSSL/src/chapter10.md +++ b/wolfSSL/src/chapter10.md @@ -9,6 +9,22 @@ typedef unsigned char byte; typedef unsigned int word32; ``` +## Structure Alignment + +Some wolfCrypt structures declare members with 16-byte or larger alignment when `WOLFSSL_USE_ALIGN` is defined. `./configure` (`--enable-aligndata`) and CMake (`WOLFSSL_ALIGN_DATA`) define it by default, except with `--enable-usersettings` or `WOLFSSL_USER_SETTINGS`, where `user_settings.h` decides. wolfSSL also forces it for AES-NI (`WOLFSSL_AESNI`), Intel speedups (`USE_INTEL_SPEEDUP`), ARM assembly (`WOLFSSL_ARMASM`), Xilinx (`WOLFSSL_XILINX`, `WOLFSSL_AFALG_XILINX`) and 32-bit ARM targets without unaligned access. + +Applications must compile the wolfSSL headers with the same configuration as the library. Include the generated `wolfssl/options.h` before any other wolfSSL header, or define `WOLFSSL_USER_SETTINGS` and use the same `user_settings.h`. Otherwise the structure layout and alignment differ between the application and the library. + +Affected structures include: + +- `Aes`, `curve25519_key`, `ed25519_key`, `Rc2`, `LmsKey` and the OpenSSL compatibility contexts, on any CPU +- `wc_Sha256` and `wc_Sha224` on 64-bit CPUs, unless a hardware port replaces the software hash state +- structures that embed one of these, such as `Hmac`, `wc_HashAlg`, `XtsAes`, `Gmac` and `Cmac` +- on Xilinx Versal, `Aes`, `ecc_key`, `RsaKey`, `wc_Sha3` and the structures that embed them, which need 64-byte alignment +- `LmsState`, passed to `wc_hss_verify()`, on x86_64 builds with Intel speedups or the LMS SHAKE parameter sets, which needs 64-byte alignment + +The compiler may use aligned load and store instructions on these structures, so their memory must meet the alignment of the type. Standalone declared variables always do. Memory from `malloc()` on common 64-bit platforms is 16-byte aligned, which covers everything above except the 64-byte cases. On 32-bit platforms, `malloc()` may return only 8-byte aligned memory. `posix_memalign()` and `aligned_alloc()` provide stricter alignment where needed. A structure placed at an arbitrary offset inside a larger buffer, or inside a packed structure, may be misaligned, and can crash, for example on x86_64. + ## Hash Functions ### MD4