Repository navigation
Conversation
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are recorded for this documentation-only update clarifying wolfCrypt context alignment requirements.
No open issues 🎉
What changed in this PR
This documentation-only PR clarifies wolfCrypt context alignment requirements to help integrations avoid misaligned allocations, motivated by the reported curl HMAC crash.
Changes:
- Add alignment notes to SHA-256/224, HMAC, AES, Curve25519, and Ed25519 initialization documentation.
- Document
wc_HmacInit()parameters, return values, usage, and cleanup, and link it fromwc_HmacSetKey().
| File | Description |
|---|---|
doc/dox_comments/header_files/sha256.h |
Add alignment notes for SHA-256 and SHA-224 initialization. |
doc/dox_comments/header_files/hmac.h |
Add wc_HmacInit() documentation, alignment guidance, and a cross-reference. |
doc/dox_comments/header_files/ed25519.h |
Document alignment for Ed25519 key initialization. |
doc/dox_comments/header_files/curve25519.h |
Document alignment for Curve25519 key initialization. |
doc/dox_comments/header_files/aes.h |
Document AES alignment, including the Xilinx Versal exception. |
Review effort: Balanced
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().
Frauschi
force-pushed
the
doc-struct-alignment
branch
from
November 3, 2026 18:50
9139767 to
f26f4ee
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.
Several wolfCrypt context structures need 16-byte alignment when
WOLFSSL_USE_ALIGNis defined, which configure and CMake builds do by default, but the API docs never said so. curl's HMAC code placed awc_Sha2568 bytes off a 16-byte boundary and crashed on x86_64 (curl/curl#23690).Changes:
\noteto the SHA-256/224, HMAC, AES, Curve25519 and Ed25519 init docswc_HmacInit()wolfSSL/documentation#294 adds these requirements to the documentation as well.