X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=fuzz%2FREADME.md;h=8536566ec1c3d75ace1ee538dc986b0f2c1bd96f;hb=5d99881e6a58a8775b8ca866b794f615a16bb033;hp=e9ec88b8c6b90c2d2621a1e8bf1e03d2a7838c37;hpb=f59d0131cb6fc224aee0a0a92de1f04cdebe97c8;p=openssl.git diff --git a/fuzz/README.md b/fuzz/README.md index e9ec88b8c6..8536566ec1 100644 --- a/fuzz/README.md +++ b/fuzz/README.md @@ -3,7 +3,7 @@ LibFuzzer ========= -Or, how to fuzz OpenSSL with [libfuzzer](llvm.org/docs/LibFuzzer.html). +Or, how to fuzz OpenSSL with [libfuzzer](http://llvm.org/docs/LibFuzzer.html). Starting from a vanilla+OpenSSH server Ubuntu install. @@ -27,7 +27,7 @@ https://github.com/llvm-mirror/llvm/tree/master/lib/Fuzzer if you prefer): $ sudo apt-get install subversion $ mkdir svn-work $ cd svn-work - $ svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer + $ svn co https://llvm.org/svn/llvm-project/compiler-rt/trunk/lib/fuzzer Fuzzer $ cd Fuzzer $ clang++ -c -g -O2 -std=c++11 *.cpp $ ar r libFuzzer.a *.o @@ -38,19 +38,21 @@ Configure for fuzzing: $ CC=clang ./config enable-fuzz-libfuzzer \ --with-fuzzer-include=../../svn-work/Fuzzer \ --with-fuzzer-lib=../../svn-work/Fuzzer/libFuzzer \ - enable-asan enable-ubsan no-shared + -DPEDANTIC enable-asan enable-ubsan no-shared \ + -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION \ + -fsanitize-coverage=trace-pc-guard,indirect-calls,trace-cmp \ + enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment enable-tls1_3 \ + enable-weak-ssl-ciphers enable-rc5 enable-md2 \ + enable-ssl3 enable-ssl3-method enable-nextprotoneg \ + --debug $ sudo apt-get install make $ LDCMD=clang++ make -j - $ fuzz/helper.py + $ fuzz/helper.py $FUZZER -Where `` is one of the executables in `fuzz/`. Most fuzzers do not -need any command line arguments, but, for example, `asn1` needs the name of a -data type. +Where $FUZZER is one of the executables in `fuzz/`. If you get a crash, you should find a corresponding input file in -`fuzz/corpora/-crash/`. You can reproduce the crash with - - $ fuzz/ +`fuzz/corpora/$FUZZER-crash/`. AFL === @@ -58,13 +60,72 @@ AFL Configure for fuzzing: $ sudo apt-get install afl-clang - $ CC=afl-clang-fast ./config enable-fuzz-afl no-shared + $ CC=afl-clang-fast ./config enable-fuzz-afl no-shared -DPEDANTIC \ + enable-tls1_3 enable-weak-ssl-ciphers enable-rc5 enable-md2 \ + enable-ssl3 enable-ssl3-method enable-nextprotoneg \ + enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ + --debug $ make +The following options can also be enabled: enable-asan, enable-ubsan, enable-msan + Run one of the fuzzers: - $ afl-fuzz fuzz/ -i fuzz/corpora/ -o fuzz/corpora//out + $ afl-fuzz -i fuzz/corpora/$FUZZER -o fuzz/corpora/$FUZZER/out fuzz/$FUZZER + +Where $FUZZER is one of the executables in `fuzz/`. + +Reproducing issues +================== + +If a fuzzer generates a reproducible error, you can reproduce the problem using +the fuzz/*-test binaries and the file generated by the fuzzer. They binaries +don't need to be build for fuzzing, there is no need to set CC or the call +config with enable-fuzz-* or -fsanitize-coverage, but some of the other options +above might be needed. For instance the enable-asan or enable-ubsan option might +be useful to show you when the problem happens. For the client and server fuzzer +it might be needed to use -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION to +reproduce the generated random numbers. + +To reproduce the crash you can run: + + $ fuzz/$FUZZER-test $file + +Random numbers +============== + +The client and server fuzzer normally generate random numbers as part of the TLS +connection setup. This results in the coverage of the fuzzing corpus changing +depending on the random numbers. This also has an effect for coverage of the +rest of the test suite and you see the coverage change for each commit even when +no code has been modified. + +Since we want to maximize the coverage of the fuzzing corpus, the client and +server fuzzer will use predictable numbers instead of the random numbers. This +is controlled by the FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION define. + +The coverage depends on the way the numbers are generated. We don't disable any +check of hashes, but the corpus has the correct hash in it for the random +numbers that were generated. For instance the client fuzzer will always generate +the same client hello with the same random number in it, and so the server, as +emulated by the file, can be generated for that client hello. + +Coverage changes +================ + +Since the corpus depends on the default behaviour of the client and the server, +changes in what they send by default will have an impact on the coverage. The +corpus will need to be updated in that case. + +Updating the corpus +=================== + +The client and server corpus is generated with multiple config options: +- The options as documented above +- Without enable-ec_nistp_64_gcc_128 and without --debug +- With no-asm +- Using 32 bit +- A default config, plus options needed to generate the fuzzer. -Where `` is one of the executables in `fuzz/`. Most fuzzers do not -need any command line arguments, but, for example, `asn1` needs the name of a -data type. +The libfuzzer merge option is used to add the additional coverage +from each config to the minimal set.