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