Repository navigation
Conversation
This was referenced Nov 3, 2026
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The alignment guidance omits matching header and library configurations, packed context risks, and 64-byte-aligned LMS/XMSS types.
3 open issues
What changed in this PR
This documentation-only PR adds structure-alignment guidance to the wolfCrypt Usage Reference, motivated by a misaligned wc_Sha256 crash in curl.
Changes:
- Explains when
WOLFSSL_USE_ALIGNis enabled and lists affected structures. - Describes allocation alignment limits and warns about contexts placed at arbitrary buffer offsets.
- Updates only the English manual; the Japanese manual remains unchanged.
| File | Description |
|---|---|
wolfSSL/src/chapter10.md |
Adds a Structure Alignment section covering configuration, affected types, and memory allocation guidance. |
Review effort: Balanced
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.
Frauschi
force-pushed
the
wolfcrypt-struct-alignment
branch
from
November 3, 2026 14:51
fb3d639 to
88748b8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a "Structure Alignment" section to the wolfCrypt Usage Reference: when
WOLFSSL_USE_ALIGNis defined, which structures need 16-byte or larger alignment, and whatmalloc()provides. A misalignedwc_Sha256crashed curl's HMAC code on x86_64 (curl/curl#23690). The Japanese manual (wolfSSL/src-ja/chapter10.md) is not updated.wolfSSL/wolfssl#11969 adds doxygen notes to the relevant wolfCrypt methods as well.