crypto_opt.h File Reference

Per-translation-unit optimization override for hot, pure-integer crypto. More...

Go to the source code of this file.

Macros
#define	DETWS_CRYPTO_HOT

Detailed Description

Per-translation-unit optimization override for hot, pure-integer crypto.

The library ships at the arduino framework's -Os (the framework appends it AFTER any PlatformIO env build_flags, so a plain -O2 there is overridden). -Os roughly halves the throughput of the software ciphers/MACs. Put DETWS_CRYPTO_HOT at the top of such a .cpp (after its includes) to force a higher level for that one translation unit, regardless of the consumer's size-optimized build:

#include "ssh_chacha20.h"
#include "shared_primitives/crypto_opt.h"
DETWS_CRYPTO_HOT   // this TU builds at -O2 (or the configured level)

Configure with DETWS_CRYPTO_OPT_LEVEL (define in build_flags or ServerConfig): 2 (default) or 3; define it to 0 to inherit the framework -Os. Only GCC honors #pragma GCC optimize; clang/other compilers get a no-op and inherit their normal level.

═══════════════════════════════════════════════════════════════════════════ CAVEATS - read before applying this to a new file ═══════════════════════════════════════════════════════════════════════════

1. CONSTANT TIME. Apply this ONLY to code that is constant-time by STRUCTURE - no secret-dependent branches and no secret-dependent memory indexing: stream ciphers (ChaCha20), MACs (Poly1305), hashes. Do NOT put it on scalar-multiplication / bignum / point-arithmetic code that relies on branchless mask-selects to stay constant-time: an aggressive optimizer can (rarely, but it is documented) turn a mask-select into a data-dependent branch and reintroduce a timing side channel. Those paths are also HW-accelerator-dominated (RSA/MPI MODMULT, HW AES/SHA), so the -O level buys them almost nothing - all risk, no reward. When in doubt, leave it off.
2. SIZE. -O2/-O3 inline and unroll aggressively -> larger flash and IRAM; -O3 more so. On the classic ESP32 (tight internal DRAM/IRAM, where TLS example builds already run close to the limit) prefer level 2 or 0.
3. -O3 IS NOT RELIABLY FASTER than -O2 here. The bigger unrolled code can thrash the instruction / flash cache and regress, and -O3 widens the miscompile and latent-UB surface. -O2 captures essentially all of the practical win; treat 3 as a measure-it-yourself option, not a default.

Definition in file crypto_opt.h.

Macro Definition Documentation

DETWS_CRYPTO_HOT

#define DETWS_CRYPTO_HOT

Definition at line 59 of file crypto_opt.h.