mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-07-05 15:50:51 +02:00
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.
# Notes on the wolfssl-fips project First, if you did not get the FIPS files with your archive, you must contact wolfSSL to obtain them. The IDE/WIN10/wolfssl-fips.sln solution is for the FIPS 140-3 certificate or later. # Building the wolfssl-fips project The wolfCrypt FIPS library for Windows is a part of the wolfSSL library. It must be built as a static library, for the moment. The library project is built with Whole Program Optimization disabled. This is required so that necessary components of the library are not optimized away. There are two functions added to the library that are used as markers in memory for the in-core memory check of the code. WPO consolidates them into a single function. WPO also optimizes away the automatic FIPS entry function. Each of the source files inside the FIPS boundary defines their own code and constant section. The code section names start with ".fipsA$" and the constant section names start with ".fipsB$". Each subsection has a letter to organize them in a specific order. This specific ordering puts marker functions and constants on either end of the boundary so it can be hashed. # In Core Memory Test The In Core Memory test calculates a checksum (HMAC-SHA256) of the wolfCrypt FIPS library code and constant data and compares it with a known value in the code. The following wolfCrypt FIPS project linker settings are required for the DLL Win32 configuration: 1) The [Randomized Base Address setting (ASLR)](https://learn.microsoft.com/en-us/cpp/build/reference/dynamicbase-use-address-space-layout-randomization?view=msvc-170) needs to be disabled on all builds as the feature throws off the in-core memory calculation causing the test to fail. 2) The [Incremental Link](https://learn.microsoft.com/en-us/cpp/build/reference/incremental-link-incrementally?view=msvc-170) option need turned off so function pointers go to actual code, not a jump instruction. 3) The [FixedBaseAddress](https://learn.microsoft.com/en-us/cpp/build/reference/fixed-fixed-base-address?view=msvc-170) option to YES, which disables the support for ASLR. The "verifyCore" check value in the source fips_test.c needs to be updated when building the code. The POS performs this check and the default failure callback will print out the calculated checksum. When developing your code, copy this value and paste it back into your code in the verifyCore initializer then rebuild the code. When statically linking, you may have to recalculate your check value when changing your application. # Build Options The default build options should be the proper default set of options: * HAVE_FIPS * HAVE_FIPS_VERSION=5 * HAVE_FIPS_VERSION_MINOR=1 (Also for FIPS Ready) * HAVE_THREAD_LS * WOLFSSL_KEY_GEN * HAVE_AESGCM * HAVE_HASHDRBG * WOLFSSL_SHA384 * WOLFSSL_SHA512 * NO_PSK * NO_RC4 * NO_DSA * NO_MD4 * WOLFSSL_SHA224 * WOLFSSL_SHA3 * WC_RSA_PSS * WC_RSA_NO_PADDING * HAVE_ECC * ECC_SHAMIR * HAVE_ECC_CDH * ECC_TIMING_RESISTANT * TFM_TIMING_RESISTANT * WOLFSSL_AES_COUNTER * WOLFSSL_AES_DIRECT * HAVE_AES_ECB * HAVE_AESCCM * WOLFSSL_CMAC * HAVE_HKDF * WOLFSSL_VALIDATE_ECC_IMPORT * WOLFSSL_VALIDATE_FFC_IMPORT * HAVE_FFDHE_Q * NO_DES * NO_DES3 * NO_MD5 * NO_OLD_TLS * WOLFSSL_TLS13 * HAVE_TLS_EXTENSIONS * HAVE_SUPPORTED_CURVES * GCM_TABLE_4BIT * WOLFSSL_NO_SHAKE256 * WOLFSSL_VALIDATE_ECC_KEYGEN * WOLFSSL_ECDSA_SET_K * WOLFSSL_WOLFSSH * WOLFSSL_PUBLIC_MP * WC_RNG_SEED_CB * TFM_ECC256 * ECC_USER_CURVES * HAVE_ECC192 * HAVE_ECC224 * HAVE_ECC256 * HAVE_ECC384 * HAVE_ECC521 * HAVE_FFDHE_2048 * HAVE_FFDHE_3072 * HAVE_FFDHE_4096 * HAVE_FFDHE_6144 * HAVE_FFDHE_8192 * FP_MAX_BITS 16384 The "NO" options explicitly disable algorithms that are not allowed in FIPS mode. Additionally one may enable: * WOLFSSL_AESNI * OPENSSL_EXTRA These settings are defined in IDE/WIN10/user_settings.h.