| 1 | Fuzzing OpenSSL
|
|---|
| 2 | ===============
|
|---|
| 3 |
|
|---|
| 4 | OpenSSL can use either LibFuzzer or AFL to do fuzzing.
|
|---|
| 5 |
|
|---|
| 6 | LibFuzzer
|
|---|
| 7 | ---------
|
|---|
| 8 |
|
|---|
| 9 | How to fuzz OpenSSL with [libfuzzer](http://llvm.org/docs/LibFuzzer.html),
|
|---|
| 10 | starting from a vanilla+OpenSSH server Ubuntu install.
|
|---|
| 11 |
|
|---|
| 12 | With `clang` from a package manager
|
|---|
| 13 | -----------------------------------
|
|---|
| 14 |
|
|---|
| 15 | Install `clang`, which [ships with `libfuzzer`](http://llvm.org/docs/LibFuzzer.html#fuzzer-usage)
|
|---|
| 16 | since version 6.0:
|
|---|
| 17 |
|
|---|
| 18 | sudo apt-get install clang
|
|---|
| 19 |
|
|---|
| 20 | Configure `openssl` for fuzzing. For now, you'll still need to pass in the path
|
|---|
| 21 | to 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 |
|
|---|
| 35 | Compile:
|
|---|
| 36 |
|
|---|
| 37 | sudo apt-get install make
|
|---|
| 38 | make clean
|
|---|
| 39 | LDCMD=clang++ make -j4
|
|---|
| 40 |
|
|---|
| 41 | Finally, perform the actual fuzzing:
|
|---|
| 42 |
|
|---|
| 43 | fuzz/helper.py $FUZZER
|
|---|
| 44 |
|
|---|
| 45 | where $FUZZER is one of the executables in `fuzz/`.
|
|---|
| 46 | It will run until you stop it.
|
|---|
| 47 |
|
|---|
| 48 | If you get a crash, you should find a corresponding input file in
|
|---|
| 49 | `fuzz/corpora/$FUZZER-crash/`.
|
|---|
| 50 |
|
|---|
| 51 | With `clang` from source/pre-built binaries
|
|---|
| 52 | -------------------------------------------
|
|---|
| 53 |
|
|---|
| 54 | You may also wish to use a pre-built binary from the [LLVM Download
|
|---|
| 55 | site](http://releases.llvm.org/download.html), or to [build `clang` from
|
|---|
| 56 | source](https://clang.llvm.org/get_started.html). After adding `clang` to your
|
|---|
| 57 | path and locating the `libfuzzer` library file, the procedure for configuring
|
|---|
| 58 | fuzzing is the same, except that you also need to specify
|
|---|
| 59 | a `--with-fuzzer-include` option, which should be the parent directory of the
|
|---|
| 60 | prebuilt 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 |
|
|---|
| 73 | AFL
|
|---|
| 74 | ---
|
|---|
| 75 |
|
|---|
| 76 | This is an alternative to using LibFuzzer.
|
|---|
| 77 |
|
|---|
| 78 | Configure 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 |
|
|---|
| 89 | The following options can also be enabled: enable-asan, enable-ubsan, enable-msan
|
|---|
| 90 |
|
|---|
| 91 | Run one of the fuzzers:
|
|---|
| 92 |
|
|---|
| 93 | afl-fuzz -i fuzz/corpora/$FUZZER -o fuzz/corpora/$FUZZER/out fuzz/$FUZZER
|
|---|
| 94 |
|
|---|
| 95 | Where $FUZZER is one of the executables in `fuzz/`.
|
|---|
| 96 |
|
|---|
| 97 | Reproducing issues
|
|---|
| 98 | ------------------
|
|---|
| 99 |
|
|---|
| 100 | If a fuzzer generates a reproducible error, you can reproduce the problem using
|
|---|
| 101 | the fuzz/*-test binaries and the file generated by the fuzzer. They binaries
|
|---|
| 102 | don't need to be built for fuzzing, there is no need to set CC or the call
|
|---|
| 103 | config with enable-fuzz-* or -fsanitize-coverage, but some of the other options
|
|---|
| 104 | above might be needed. For instance the enable-asan or enable-ubsan option might
|
|---|
| 105 | be useful to show you when the problem happens. For the client and server fuzzer
|
|---|
| 106 | it might be needed to use -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION to
|
|---|
| 107 | reproduce the generated random numbers.
|
|---|
| 108 |
|
|---|
| 109 | To reproduce the crash you can run:
|
|---|
| 110 |
|
|---|
| 111 | fuzz/$FUZZER-test $file
|
|---|
| 112 |
|
|---|
| 113 | To do all the tests of a specific fuzzer such as asn1 you can run
|
|---|
| 114 |
|
|---|
| 115 | fuzz/asn1-test fuzz/corpora/asn1
|
|---|
| 116 | or
|
|---|
| 117 | make test TESTS=fuzz_test_asn1
|
|---|
| 118 |
|
|---|
| 119 | To run several fuzz tests you can use for instance:
|
|---|
| 120 |
|
|---|
| 121 | make test TESTS='test_fuzz_cmp test_fuzz_cms'
|
|---|
| 122 |
|
|---|
| 123 | To run all fuzz tests you can use:
|
|---|
| 124 |
|
|---|
| 125 | make test TESTS='test_fuzz_*'
|
|---|
| 126 |
|
|---|
| 127 | Random numbers
|
|---|
| 128 | --------------
|
|---|
| 129 |
|
|---|
| 130 | The client and server fuzzer normally generate random numbers as part of the TLS
|
|---|
| 131 | connection setup. This results in the coverage of the fuzzing corpus changing
|
|---|
| 132 | depending on the random numbers. This also has an effect for coverage of the
|
|---|
| 133 | rest of the test suite and you see the coverage change for each commit even when
|
|---|
| 134 | no code has been modified.
|
|---|
| 135 |
|
|---|
| 136 | Since we want to maximize the coverage of the fuzzing corpus, the client and
|
|---|
| 137 | server fuzzer will use predictable numbers instead of the random numbers. This
|
|---|
| 138 | is controlled by the FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION define.
|
|---|
| 139 |
|
|---|
| 140 | The coverage depends on the way the numbers are generated. We don't disable any
|
|---|
| 141 | check of hashes, but the corpus has the correct hash in it for the random
|
|---|
| 142 | numbers that were generated. For instance the client fuzzer will always generate
|
|---|
| 143 | the same client hello with the same random number in it, and so the server, as
|
|---|
| 144 | emulated by the file, can be generated for that client hello.
|
|---|
| 145 |
|
|---|
| 146 | Coverage changes
|
|---|
| 147 | ----------------
|
|---|
| 148 |
|
|---|
| 149 | Since the corpus depends on the default behaviour of the client and the server,
|
|---|
| 150 | changes in what they send by default will have an impact on the coverage. The
|
|---|
| 151 | corpus will need to be updated in that case.
|
|---|
| 152 |
|
|---|
| 153 | Updating the corpus
|
|---|
| 154 | -------------------
|
|---|
| 155 |
|
|---|
| 156 | The 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 |
|
|---|
| 164 | The libfuzzer merge option is used to add the additional coverage
|
|---|
| 165 | from each config to the minimal set.
|
|---|
| 166 |
|
|---|
| 167 | Minimizing the corpus
|
|---|
| 168 | ---------------------
|
|---|
| 169 |
|
|---|
| 170 | When you have gathered corpus data from more than one fuzzer run
|
|---|
| 171 | or for any other reason want to minimize the data
|
|---|
| 172 | in 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
|
|---|
