diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 3aacf33a..012c2020 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -4064,6 +4064,113 @@ Implements a lean TLS 1.2 client only (no client auth), ECC256, AES128 and SHA25 Enabling produces a small footprint TLS client that supports TLS 1.2 client only (no client auth), ECC256, AES128 and SHA256 w/o Shamir. Meant to be used by itself at the moment and not in conjunction with other build options. +### `--enable-tinytls13` + +Enable the tiny TLS 1.3 footprint profile. This is a TLS 1.3 only build that strips wolfSSL to a minimal handshake surface for embedded and resource constrained targets. It is expressed as a translation layer over standard wolfSSL macros (the `WOLFSSL_TINY_TLS13` umbrella in `settings.h`), so it adds no new feature flags to the core library. + +The profile is selected with a comma separated list: + +```sh +./configure --enable-tinytls13=LIST +``` + +The bare flag `--enable-tinytls13` is equivalent to `--enable-tinytls13=psk`. This profile is non FIPS and cannot be combined with a FIPS build. + +#### Base profiles + +* `psk` (default): a pre shared key plus ECDHE build with no X.509. The floor is X25519 key exchange, AES-128-GCM, SHA-256 and HKDF. This is the smallest configuration. +* `cert`: adds a minimal X.509 certificate chain verify on top of the floor, using ECDSA P-256 by default. + +The certificate profile is a reduced security verify. It disables X.509 name constraint enforcement, relaxes ASN.1 strictness and removes CRL revocation checking to save code. It is intended for a known or pinned certificate authority, not for general public internet PKI. Configure prints a notice when the certificate profile is selected. + +#### Adders + +The following may be combined with a base profile in the comma separated list: + +* `server`: add the TLS 1.3 server role. The default is client only. +* `mutualauth`: mutual TLS with X.509 client authentication. Implies `cert`. +* `staticmem`: serve TLS allocations from a caller provided static memory pool. Add `WOLFSSL_NO_MALLOC` separately for a true zero heap build. +* `asm`: use assembly crypto instead of the small C backend. Larger but faster. +* `p256`: use P-256 ECDHE on the PSK floor instead of X25519. +* `sha384`: add SHA-384, for example for AES-256-GCM-SHA384. +* `mldsa`: add ML-DSA-65 certificate verification (verify only). +* `rsaverify`: add RSA-PSS certificate verification. The certificate profile is ECDSA only by default. + +For example, a TLS 1.3 server that verifies ECDSA certificates and also supports SHA-384: + +```sh +./configure --enable-tinytls13=cert,server,sha384 +``` + +#### Footprint + +The figures below are flash (text plus data) of the linked client binary, built `-Os` with link time optimization and dead code elimination (`-flto -ffunction-sections -fdata-sections -Wl,--gc-sections`) on the SHA-256 only floor. This is what links into an application, which is much smaller than the size of `libwolfssl.a`. Toolchains: arm-none-eabi-gcc 14.2 with newlib-nano (Cortex-M33), clang `-Os` (Intel x86_64), aarch64-none-elf-gcc 14.2 with newlib (ARM aarch64). + +| Configuration | Cortex-M33 | Intel x86_64 | ARM aarch64 | +| --- | --: | --: | --: | +| PSK, X25519 (floor) | 30,836 | 56,092 | 50,700 | +| PSK, P-256 | 37,347 | 66,068 | 59,292 | +| Cert, ECDSA P-256 | 62,765 | 110,817 | 95,404 | +| Mutual TLS | 66,554 | 116,789 | 99,836 | + +Cost of common adders on Cortex-M33, relative to the PSK floor: + +| Build | Flash (bytes) | Delta vs floor | +| --- | --: | --: | +| PSK floor (X25519) | 30,836 | 0 | +| plus static memory (zero heap) | 32,169 | +1,333 | +| plus P-256 | 37,347 | +6,511 | +| plus ML-DSA-65 verify | 43,780 | +12,944 | + +Where the flash goes for a PSK P-256 client on Cortex-M33 (37,347 bytes): + +| Component | Bytes | +| --- | --: | +| TLS 1.3 handshake | 7,766 | +| TLS extensions | 5,678 | +| ECC P-256 (SP math) | 5,962 | +| CTX, SSL object and API | 4,050 | +| Record layer | 3,564 | +| AES-128-GCM | 2,650 | +| HMAC, HKDF, DRBG and RNG | 2,110 | +| SHA-256 | 1,370 | +| Key schedule | 1,120 | +| Memory and cleanup | 630 | +| C library (newlib) | 952 | +| Other and inlined | 1,486 | + +#### Customizing for your application + +1. Start from the closest base profile. Use `psk` if your endpoints share a pre shared key and you do not need certificates. Use `cert` if you must validate an X.509 certificate from a known certificate authority. +2. Add only the adders you need. Each one is a deliberate, measured step up in size, as the tables above show. Begin with `server` if the build is a server, and add a curve or signature adder only when your peer requires it. +3. Choose the key exchange curve. The PSK floor uses X25519. Add `p256` when you want P-256, for example to reuse the P-256 code already pulled in by an ECDSA certificate. +4. Choose the memory model. The default uses the system allocator. Add `staticmem` to serve TLS allocations from a fixed pool supplied with `wolfSSL_CTX_load_static_memory()`. For a target with no heap at all, also define `WOLFSSL_NO_MALLOC`. +5. Provide the platform glue for bare metal. The example template enables `WOLFSSL_USER_IO` (you supply send and receive callbacks), `NO_FILESYSTEM` and `WOLFSSL_NO_SOCK`, and expects a hardware entropy source through `CUSTOM_RAND_GENERATE_SEED`. +6. Build for size. Link your application with `-Os -flto -ffunction-sections -fdata-sections -Wl,--gc-sections` so unused code is dropped. + +The same profile is available without autotools through the `WOLFSSL_TINY_TLS13` umbrella in `settings.h`. The template `examples/configs/user_settings_tinytls13.h` selects the profile and adders with `#if 0` and `#if 1` blocks. The smallest result comes from a dead code eliminated, link time optimized build: + +```sh +cp ./examples/configs/user_settings_tinytls13.h user_settings.h +./configure --enable-usersettings --enable-static --disable-shared \ + --disable-examples --disable-crypttests +make +# link your application with: +# -Os -flto -ffunction-sections -fdata-sections -Wl,--gc-sections +``` + +A self contained, single process TLS 1.3 handshake smoke test for the profile is provided in `examples/configs/tinytls13_smoke.c`. It wires an in memory client and server together with no sockets or threads, so it can validate a tiny build that has no example or test harness available. + +#### Dos and don'ts + +* Do use the `cert` profile only with a known or pinned certificate authority. Its verify is deliberately reduced (no name constraints, relaxed ASN.1, no CRL). +* Do not use the `cert` profile for general public internet PKI. +* Do pair `mldsa` and `rsaverify` with the `cert` profile. They are certificate verification algorithms, so on the PSK floor they only confirm the build links. +* Do supply a real hardware entropy source through `CUSTOM_RAND_GENERATE_SEED` on bare metal. The default seed sources are not present once `NO_FILESYSTEM` and similar are set. +* Do not combine the profile with a FIPS build. It is a non FIPS footprint profile. +* Do not define `WOLFSSL_NO_MALLOC` and expect the standard `make check` test suite to run, since that suite needs an allocator. Validate a zero heap build by linking it and running the smoke test instead. +* Note that AES-256-GCM-SHA384 uses a SHA-384 transcript. With an external pre shared key, provision the key for SHA-384 through the cipher suite specific PSK callback, or use the cipher on the certificate profile, otherwise the PSK binder will not match. + ### `--enable-bigcache` Enable a big session cache.