1Fuzzing OpenSSL 2=============== 3 4OpenSSL can use either LibFuzzer or AFL to do fuzzing. 5 6LibFuzzer 7--------- 8 9How to fuzz OpenSSL with [libfuzzer](http://llvm.org/docs/LibFuzzer.html), 10starting from a vanilla+OpenSSH server Ubuntu install. 11 12With `clang` from a package manager 13----------------------------------- 14 15Install `clang`, which [ships with `libfuzzer`](http://llvm.org/docs/LibFuzzer.html#fuzzer-usage) 16since version 6.0: 17 18 sudo apt-get install clang 19 20Configure `openssl` for fuzzing. For now, you'll still need to pass in the path 21to the `libFuzzer` library file while configuring; this is represented as 22`$PATH_TO_LIBFUZZER` below. A typical value would be 23`/usr/lib/llvm-7/lib/clang/7.0.1/lib/linux/libclang_rt.fuzzer-x86_64.a`. 24 25 CC=clang ./config enable-fuzz-libfuzzer \ 26 --with-fuzzer-lib=$PATH_TO_LIBFUZZER \ 27 -DPEDANTIC enable-asan enable-ubsan no-shared \ 28 -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION \ 29 -fsanitize=fuzzer-no-link \ 30 enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ 31 enable-weak-ssl-ciphers enable-rc5 enable-md2 \ 32 enable-ssl3 enable-ssl3-method enable-nextprotoneg \ 33 --debug 34 35Compile: 36 37 sudo apt-get install make 38 make clean 39 LDCMD=clang++ make -j4 40 41Finally, perform the actual fuzzing: 42 43 fuzz/helper.py $FUZZER 44 45where $FUZZER is one of the executables in `fuzz/`. 46It will run until you stop it. 47 48If you get a crash, you should find a corresponding input file in 49`fuzz/corpora/$FUZZER-crash/`. 50 51With `clang` from source/pre-built binaries 52------------------------------------------- 53 54You may also wish to use a pre-built binary from the [LLVM Download 55site](http://releases.llvm.org/download.html), or to [build `clang` from 56source](https://clang.llvm.org/get_started.html). After adding `clang` to your 57path and locating the `libfuzzer` library file, the procedure for configuring 58fuzzing is the same, except that you also need to specify 59a `--with-fuzzer-include` option, which should be the parent directory of the 60prebuilt fuzzer library. This is represented as `$PATH_TO_LIBFUZZER_DIR` below. 61 62 CC=clang ./config enable-fuzz-libfuzzer \ 63 --with-fuzzer-include=$PATH_TO_LIBFUZZER_DIR \ 64 --with-fuzzer-lib=$PATH_TO_LIBFUZZER \ 65 -DPEDANTIC enable-asan enable-ubsan no-shared \ 66 -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION \ 67 -fsanitize=fuzzer-no-link \ 68 enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ 69 enable-weak-ssl-ciphers enable-rc5 enable-md2 \ 70 enable-ssl3 enable-ssl3-method enable-nextprotoneg \ 71 --debug 72 73AFL 74--- 75 76This is an alternative to using LibFuzzer. 77 78Configure for fuzzing: 79 80 sudo apt-get install afl-clang 81 CC=afl-clang-fast ./config enable-fuzz-afl no-shared no-module \ 82 -DPEDANTIC enable-tls1_3 enable-weak-ssl-ciphers enable-rc5 \ 83 enable-md2 enable-ssl3 enable-ssl3-method enable-nextprotoneg \ 84 enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ 85 --debug 86 make clean 87 make 88 89The following options can also be enabled: enable-asan, enable-ubsan, enable-msan 90 91Run one of the fuzzers: 92 93 afl-fuzz -i fuzz/corpora/$FUZZER -o fuzz/corpora/$FUZZER/out fuzz/$FUZZER 94 95Where $FUZZER is one of the executables in `fuzz/`. 96 97Reproducing issues 98------------------ 99 100If a fuzzer generates a reproducible error, you can reproduce the problem using 101the fuzz/*-test binaries and the file generated by the fuzzer. They binaries 102don't need to be built for fuzzing, there is no need to set CC or the call 103config with enable-fuzz-* or -fsanitize-coverage, but some of the other options 104above might be needed. For instance the enable-asan or enable-ubsan option might 105be useful to show you when the problem happens. For the client and server fuzzer 106it might be needed to use -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION to 107reproduce the generated random numbers. 108 109To reproduce the crash you can run: 110 111 fuzz/$FUZZER-test $file 112 113To do all the tests of a specific fuzzer such as asn1 you can run 114 115 fuzz/asn1-test fuzz/corpora/asn1 116or 117 make test TESTS=fuzz_test_asn1 118 119To run several fuzz tests you can use for instance: 120 121 make test TESTS='test_fuzz_cmp test_fuzz_cms' 122 123To run all fuzz tests you can use: 124 125 make test TESTS='test_fuzz_*' 126 127Random numbers 128-------------- 129 130The client and server fuzzer normally generate random numbers as part of the TLS 131connection setup. This results in the coverage of the fuzzing corpus changing 132depending on the random numbers. This also has an effect for coverage of the 133rest of the test suite and you see the coverage change for each commit even when 134no code has been modified. 135 136Since we want to maximize the coverage of the fuzzing corpus, the client and 137server fuzzer will use predictable numbers instead of the random numbers. This 138is controlled by the FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION define. 139 140The coverage depends on the way the numbers are generated. We don't disable any 141check of hashes, but the corpus has the correct hash in it for the random 142numbers that were generated. For instance the client fuzzer will always generate 143the same client hello with the same random number in it, and so the server, as 144emulated by the file, can be generated for that client hello. 145 146Coverage changes 147---------------- 148 149Since the corpus depends on the default behaviour of the client and the server, 150changes in what they send by default will have an impact on the coverage. The 151corpus will need to be updated in that case. 152 153Updating the corpus 154------------------- 155 156The client and server corpus is generated with multiple config options: 157 158- The options as documented above 159- Without enable-ec_nistp_64_gcc_128 and without --debug 160- With no-asm 161- Using 32 bit 162- A default config, plus options needed to generate the fuzzer. 163 164The libfuzzer merge option is used to add the additional coverage 165from each config to the minimal set. 166 167Minimizing the corpus 168--------------------- 169 170When you have gathered corpus data from more than one fuzzer run 171or for any other reason want to minimize the data 172in some corpus subdirectory `fuzz/corpora/DIR` this can be done as follows: 173 174 mkdir fuzz/corpora/NEWDIR 175 fuzz/$FUZZER -merge=1 fuzz/corpora/NEWDIR fuzz/corpora/DIR 176