trezor-firmware/crypto/fuzzer/README.md

trezor-crypto fuzzing

Selected functions can be fuzzed via specific libFuzzer harnesses for increased test coverage and issue detection.

Note: the following commands are relative to the trezor-crypto main directory.

Build

A modern C compiler with built-in libFuzzer support is required. The build process will use clang by default. Set the CC= environment variable if you want to use a special compiler variant.

make clean
FUZZER=1 make fuzzer

Sanitizers

Recommended: ASAN / UBSAN / MSAN flags for error detection can be specified via the special SANFLAGS.

Examples:

• SANFLAGS="-fsanitize=address,undefined"
• SANFLAGS="-fsanitize=memory"

Optimizations

Override OPTFLAGS to test the library at different optimization levels or simplify the debugging of detected issues.

Example:

• OPTFLAGS="-O0 -ggdb3"

Operation

See the libFuzzer documentation for valid options and usage. Detailed fuzzer usage and relevant considerations are out of scope of this document.

Warning: fuzzing is resource-intensive and can have a negative impact on your system stability.

Basic fuzzer call:

./fuzzer/fuzzer

Here is a more sophisticated multithreading example with a persistent input corpus and other optimizations:

mkdir fuzzer/fuzzer_corpus
./fuzzer/fuzzer -max_len=2048 -use_value_profile=1 -jobs=16 -timeout=1 -reload=5 -print_pcs=1 -print_funcs=42  fuzzer/fuzzer_corpus

Hint: for more permanent setups, consider invoking the fuzzer from outside of the source directory to avoid cluttering it with logfiles and crash inputs.

Automated fuzzer dictionary generation

Dictionaries are a useful mechanism to augment the capabilities of the fuzzer. Specify them via the -dict= flag.

Collect interesting strings from the unit tests

grep -r -P -o -h  "\"\w+\"" tests | sort  | uniq > fuzzer_crypto_tests_strings_dictionary1.txt

Evaluate source coverage

1. build the fuzzer binary with CFLAGS="-fprofile-instr-generate -fcoverage-mapping"
2. run with suitable -runs= or -max_total_time= limits
3. convert the recorded data llvm-profdata merge -output=default.profdata -instr default.profraw
4. render the data llvm-cov show fuzzer/fuzzer -instr-profile=default.profdata -format=html -output-dir=coverage-report
5. analyze report at coverage-report/index.html
6. (optional) remove artifacts with rm default.profraw default.profdata && rm -r coverage-report