Tobias Frauenschläger
fb6b62dd8e
NIST standardized the pre-standardization Dilithium signature scheme as ML-DSA in FIPS 204. Migrate the provider's user-visible surface to canonical spellings, with a temporary shim that preserves source-level backward compatibility for existing consumers. Renames ------- * File: wolfcrypt/src/dilithium.c -> wolfcrypt/src/wc_mldsa.c * New canonical header: wolfssl/wolfcrypt/wc_mldsa.h * Types: dilithium_key -> MlDsaKey, wc_dilithium_params -> MlDsaParams * Functions: wc_dilithium_* / wc_Dilithium_* -> wc_MlDsaKey_* * Build gates: HAVE_DILITHIUM -> WOLFSSL_HAVE_MLDSA, WOLFSSL_DILITHIUM_* / WC_DILITHIUM_* -> WOLFSSL_MLDSA_* / WC_MLDSA_* * Configure flag: --enable-mldsa (legacy --enable-dilithium still works) * CMake option: WOLFSSL_MLDSA (legacy WOLFSSL_DILITHIUM emits a DEPRECATION message) Backward compatibility ---------------------- wolfssl/wolfcrypt/dilithium.h is now a temporary compatibility shim: * Forward-translates legacy build gates to canonical (the two sub-gates read by certs_test.h are translated in settings.h so the auto-generated header is reachable without including dilithium.h; the remainder lives in dilithium.h itself). * Reverse-translates canonical gates back to legacy so unmigrated consumer code keying off HAVE_DILITHIUM / WOLFSSL_DILITHIUM_* keeps compiling. * Provides macro / static-inline aliases for the legacy type and function names so source-level callers compile unchanged. Sets WC_DILITHIUMKEY_TYPE_DEFINED to suppress strict-C99 typedef redefinition in asn_public.h. Two opt-outs are honored: WOLFSSL_NO_DILITHIUM_LEGACY_GATES disables build-gate translation; WOLFSSL_NO_DILITHIUM_LEGACY_NAMES disables the symbol aliases. Both are temporary and the shim will be removed in a future release. doc/dilithium-to-mldsa-migration.md describes the migration path for downstream consumers. ABI note -------- The library now exports wc_MlDsaKey_* instead of wc_dilithium_*. Pre-built binaries that linked against the legacy symbols need to recompile against the shim header (which resolves to the new symbols at compile time) or migrate to the canonical names directly. Source code keeps building unchanged. Other changes ------------- * wolfssl/wolfcrypt/memory.h: drop ML-DSA sub-gate branching for static memory pool sizing; WOLFSSL_HAVE_MLDSA builds now pick the larger LARGEST_MEM_BUCKET / WOLFMEM_BUCKETS / WOLFMEM_DIST unconditionally. Override these macros for small-mem builds. * gencertbuf.pl + wolfssl/certs_test.h: outer guards migrated to the canonical WOLFSSL_HAVE_MLDSA spelling. * tests/api/test_mldsa.c: adds compile-time API surface validators (canonical wc_MlDsaKey_* surface plus legacy alias surface) so signature drift produces a build error during make check. * IDE files (Xcode, INTIME-RTOS, WIN10, VS2022, CSharp wrapper), Zephyr CMakeLists.txt, and autotools include.am updated for the rename. * DYNAMIC_TYPE_DILITHIUM and ML_DSA_PCT_E retained as internal symbols; scheduled to be renamed alongside the eventual shim removal.
Zephyr Project Port
Overview
This port is for the Zephyr RTOS Project, available here.
It provides the following zephyr code.
- modules/crypto/wolfssl
- wolfssl library code
- modules/crypto/wolfssl/zephyr/
- Configuration and CMake files for wolfSSL as a Zephyr module
- modules/crypto/wolfssl/zephyr/samples/wolfssl_test
- wolfCrypt test application
- modules/crypto/wolfssl/zephyr/samples/wolfssl_bench
- wolfCrypt benchmark application
- modules/crypto/wolfssl/zephyr/samples/wolfssl_tls_sock
- socket based sample of TLS
- modules/crypto/wolfssl/zephyr/samples/wolfssl_tls_thread
- socket based sample of TLS using threads
How to setup as a Zephyr Module
Modify your project's west manifest
Add wolfssl as a project to your west.yml:
manifest:
remotes:
# <your other remotes>
- name: wolfssl
url-base: https://github.com/wolfssl
projects:
# <your other projects>
- name: wolfssl
path: modules/crypto/wolfssl
revision: master
remote: wolfssl
If you are using the Nordic nRF Connect SDK with Zephyr, the sdk-nrf manifest
file is located at: vX.X.X/nrf/west.yml. On OSX the default installation
location for the nRF Connect SDK is at /opt/nordic/ncs/vX.X.X.
Update west's modules:
west update
Now west recognizes 'wolfssl' as a module, and will include it's Kconfig and CMakeFiles.txt in the build system.
If using the Nordic nRF Connect SDK, to get access to a terminal with west tool access, open "nRF Connect for Desktop", then "Toolchain Manager", and finally next to the SDK version you are using click the drop down arrow, then "Open Terminal".
Build and Run wolfCrypt Test Application
If you want to run build apps without running west zephyr-export then it is
possible by setting the CMAKE_PREFIX_PATH variable to the location of the
zephyr sdk and building from the zephyr directory. For example:
CMAKE_PREFIX_PATH=/path/to/zephyr-sdk-<VERSION> west build -p always -b qemu_x86 ../modules/crypto/wolfssl/zephyr/samples/wolfssl_test/
build and execute wolfssl_test
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/crypto/wolfssl/zephyr/samples/wolfssl_test
west build -t run
Build and Run wolfCrypt Benchmark Application
build and execute wolfssl_benchmark
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/crypto/wolfssl/zephyr/samples/wolfssl_benchmark
west build -t run
Build and Run wolfSSL example wolfssl_tls_sock
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/crypto/wolfssl/zephyr/samples/wolfssl_tls_sock
west build -t run
Build and Run wolfSSL example wolfssl_tls_thread
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/crypto/wolfssl/zephyr/samples/wolfssl_tls_thread
west build -t run
How to setup wolfSSL support for Zephyr TLS Sockets and RNG
wolfSSL can also be used as the underlying implementation for the default Zephyr TLS socket interface. With this enabled, all existing applications using the Zephyr TLS sockets will now use wolfSSL inside for all TLS operations. This will also enable wolfSSL as the default RNG implementation. To enable this feature, use the patch file and instructions found here: