]>
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 | |
a81151bd | 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 | |
a81151bd | 20 | `/usr/lib/llvm-7/lib/clang/7.0.1/lib/linux/libclang_rt.fuzzer-x86_64.a`. |
c38bb727 | 21 | |
a81151bd | 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 | ||
a81151bd DDO |
34 | sudo apt-get install make |
35 | make clean | |
36 | LDCMD=clang++ make -j4 | |
639b53ec BC |
37 | |
38 | Finally, perform the actual fuzzing: | |
39 | ||
a81151bd | 40 | fuzz/helper.py $FUZZER |
c38bb727 | 41 | |
639b53ec | 42 | where $FUZZER is one of the executables in `fuzz/`. |
a81151bd | 43 | It will run until you stop it. |
c38bb727 BL |
44 | |
45 | If you get a crash, you should find a corresponding input file in | |
f8d4b3be | 46 | `fuzz/corpora/$FUZZER-crash/`. |
f59d0131 | 47 | |
639b53ec BC |
48 | With `clang` from source/pre-built binaries |
49 | ------------------------------------------- | |
50 | ||
51 | You may also wish to use a pre-built binary from the [LLVM Download | |
52 | site](http://releases.llvm.org/download.html), or to [build `clang` from | |
53 | source](https://clang.llvm.org/get_started.html). After adding `clang` to your | |
54 | path and locating the `libfuzzer` library file, the procedure for configuring | |
55 | fuzzing is the same, except that you also need to specify | |
56 | a `--with-fuzzer-include` option, which should be the parent directory of the | |
57 | prebuilt fuzzer library. This is represented as `$PATH_TO_LIBFUZZER_DIR` below. | |
58 | ||
a81151bd | 59 | CC=clang ./config enable-fuzz-libfuzzer \ |
639b53ec BC |
60 | --with-fuzzer-include=$PATH_TO_LIBFUZZER_DIR \ |
61 | --with-fuzzer-lib=$PATH_TO_LIBFUZZER \ | |
62 | -DPEDANTIC enable-asan enable-ubsan no-shared \ | |
63 | -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION \ | |
64 | -fsanitize=fuzzer-no-link \ | |
65 | enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ | |
66 | enable-weak-ssl-ciphers enable-rc5 enable-md2 \ | |
67 | enable-ssl3 enable-ssl3-method enable-nextprotoneg \ | |
68 | --debug | |
69 | ||
f59d0131 KR |
70 | AFL |
71 | === | |
72 | ||
a81151bd DDO |
73 | This is an alternative to using LibFuzzer. |
74 | ||
f59d0131 KR |
75 | Configure for fuzzing: |
76 | ||
a81151bd DDO |
77 | sudo apt-get install afl-clang |
78 | CC=afl-clang-fast ./config enable-fuzz-afl no-shared no-module \ | |
deaaac2c MC |
79 | -DPEDANTIC enable-tls1_3 enable-weak-ssl-ciphers enable-rc5 \ |
80 | enable-md2 enable-ssl3 enable-ssl3-method enable-nextprotoneg \ | |
f8d4b3be KR |
81 | enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ |
82 | --debug | |
a81151bd DDO |
83 | make clean |
84 | make | |
f59d0131 | 85 | |
e104d01d KR |
86 | The following options can also be enabled: enable-asan, enable-ubsan, enable-msan |
87 | ||
f59d0131 KR |
88 | Run one of the fuzzers: |
89 | ||
a81151bd | 90 | afl-fuzz -i fuzz/corpora/$FUZZER -o fuzz/corpora/$FUZZER/out fuzz/$FUZZER |
f59d0131 | 91 | |
31b15b9b | 92 | Where $FUZZER is one of the executables in `fuzz/`. |
f8d4b3be KR |
93 | |
94 | Reproducing issues | |
95 | ================== | |
96 | ||
97 | If a fuzzer generates a reproducible error, you can reproduce the problem using | |
98 | the fuzz/*-test binaries and the file generated by the fuzzer. They binaries | |
99 | don't need to be build for fuzzing, there is no need to set CC or the call | |
100 | config with enable-fuzz-* or -fsanitize-coverage, but some of the other options | |
101 | above might be needed. For instance the enable-asan or enable-ubsan option might | |
102 | be useful to show you when the problem happens. For the client and server fuzzer | |
103 | it might be needed to use -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION to | |
104 | reproduce the generated random numbers. | |
105 | ||
106 | To reproduce the crash you can run: | |
107 | ||
a81151bd | 108 | fuzz/$FUZZER-test $file |
f8d4b3be KR |
109 | |
110 | Random numbers | |
111 | ============== | |
112 | ||
113 | The client and server fuzzer normally generate random numbers as part of the TLS | |
114 | connection setup. This results in the coverage of the fuzzing corpus changing | |
115 | depending on the random numbers. This also has an effect for coverage of the | |
116 | rest of the test suite and you see the coverage change for each commit even when | |
117 | no code has been modified. | |
118 | ||
119 | Since we want to maximize the coverage of the fuzzing corpus, the client and | |
120 | server fuzzer will use predictable numbers instead of the random numbers. This | |
121 | is controlled by the FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION define. | |
122 | ||
123 | The coverage depends on the way the numbers are generated. We don't disable any | |
124 | check of hashes, but the corpus has the correct hash in it for the random | |
125 | numbers that were generated. For instance the client fuzzer will always generate | |
126 | the same client hello with the same random number in it, and so the server, as | |
127 | emulated by the file, can be generated for that client hello. | |
128 | ||
129 | Coverage changes | |
130 | ================ | |
131 | ||
132 | Since the corpus depends on the default behaviour of the client and the server, | |
133 | changes in what they send by default will have an impact on the coverage. The | |
134 | corpus will need to be updated in that case. | |
135 | ||
930aa9ee KR |
136 | Updating the corpus |
137 | =================== | |
138 | ||
139 | The client and server corpus is generated with multiple config options: | |
140 | - The options as documented above | |
141 | - Without enable-ec_nistp_64_gcc_128 and without --debug | |
142 | - With no-asm | |
143 | - Using 32 bit | |
144 | - A default config, plus options needed to generate the fuzzer. | |
145 | ||
146 | The libfuzzer merge option is used to add the additional coverage | |
147 | from each config to the minimal set. | |
a81151bd DDO |
148 | |
149 | Minimizing the corpus | |
150 | ===================== | |
151 | ||
152 | When you have gathered corpus data from more than one fuzzer run | |
153 | or for any other reason want to to minimize the data | |
154 | in some corpus subdirectory `fuzz/corpora/DIR` this can be done as follows: | |
155 | ||
156 | mkdir fuzz/corpora/NEWDIR | |
157 | fuzz/$FUZZER -merge=1 fuzz/corpora/NEWDIR fuzz/corpora/DIR |