]>
Commit | Line | Data |
---|---|---|
257e9d03 RS |
1 | Fuzzing OpenSSL |
2 | =============== | |
3 | ||
4 | OpenSSL can use either LibFuzzer or AFL to do fuzzing. | |
c38bb727 | 5 | |
f59d0131 | 6 | LibFuzzer |
257e9d03 | 7 | --------- |
f59d0131 | 8 | |
639b53ec BC |
9 | How to fuzz OpenSSL with [libfuzzer](http://llvm.org/docs/LibFuzzer.html), |
10 | starting from a vanilla+OpenSSH server Ubuntu install. | |
c38bb727 | 11 | |
639b53ec BC |
12 | With `clang` from a package manager |
13 | ----------------------------------- | |
c38bb727 | 14 | |
639b53ec BC |
15 | Install `clang`, which [ships with `libfuzzer`](http://llvm.org/docs/LibFuzzer.html#fuzzer-usage) |
16 | since version 6.0: | |
c38bb727 | 17 | |
a81151bd | 18 | sudo apt-get install clang |
c38bb727 | 19 | |
639b53ec BC |
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 | |
a81151bd | 23 | `/usr/lib/llvm-7/lib/clang/7.0.1/lib/linux/libclang_rt.fuzzer-x86_64.a`. |
c38bb727 | 24 | |
a81151bd | 25 | CC=clang ./config enable-fuzz-libfuzzer \ |
639b53ec | 26 | --with-fuzzer-lib=$PATH_TO_LIBFUZZER \ |
3a9b9b2d | 27 | -DPEDANTIC enable-asan enable-ubsan no-shared \ |
0282aeb6 | 28 | -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION \ |
639b53ec BC |
29 | -fsanitize=fuzzer-no-link \ |
30 | enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ | |
e104d01d | 31 | enable-weak-ssl-ciphers enable-rc5 enable-md2 \ |
f8d4b3be KR |
32 | enable-ssl3 enable-ssl3-method enable-nextprotoneg \ |
33 | --debug | |
639b53ec BC |
34 | |
35 | Compile: | |
36 | ||
a81151bd DDO |
37 | sudo apt-get install make |
38 | make clean | |
39 | LDCMD=clang++ make -j4 | |
639b53ec BC |
40 | |
41 | Finally, perform the actual fuzzing: | |
42 | ||
a81151bd | 43 | fuzz/helper.py $FUZZER |
c38bb727 | 44 | |
639b53ec | 45 | where $FUZZER is one of the executables in `fuzz/`. |
a81151bd | 46 | It will run until you stop it. |
c38bb727 BL |
47 | |
48 | If you get a crash, you should find a corresponding input file in | |
f8d4b3be | 49 | `fuzz/corpora/$FUZZER-crash/`. |
f59d0131 | 50 | |
639b53ec BC |
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 | ||
a81151bd | 62 | CC=clang ./config enable-fuzz-libfuzzer \ |
639b53ec BC |
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 | ||
f59d0131 | 73 | AFL |
257e9d03 | 74 | --- |
f59d0131 | 75 | |
a81151bd DDO |
76 | This is an alternative to using LibFuzzer. |
77 | ||
f59d0131 KR |
78 | Configure for fuzzing: |
79 | ||
a81151bd DDO |
80 | sudo apt-get install afl-clang |
81 | CC=afl-clang-fast ./config enable-fuzz-afl no-shared no-module \ | |
deaaac2c MC |
82 | -DPEDANTIC enable-tls1_3 enable-weak-ssl-ciphers enable-rc5 \ |
83 | enable-md2 enable-ssl3 enable-ssl3-method enable-nextprotoneg \ | |
f8d4b3be KR |
84 | enable-ec_nistp_64_gcc_128 -fno-sanitize=alignment \ |
85 | --debug | |
a81151bd DDO |
86 | make clean |
87 | make | |
f59d0131 | 88 | |
e104d01d KR |
89 | The following options can also be enabled: enable-asan, enable-ubsan, enable-msan |
90 | ||
f59d0131 KR |
91 | Run one of the fuzzers: |
92 | ||
a81151bd | 93 | afl-fuzz -i fuzz/corpora/$FUZZER -o fuzz/corpora/$FUZZER/out fuzz/$FUZZER |
f59d0131 | 94 | |
31b15b9b | 95 | Where $FUZZER is one of the executables in `fuzz/`. |
f8d4b3be KR |
96 | |
97 | Reproducing issues | |
257e9d03 | 98 | ------------------ |
f8d4b3be KR |
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 build 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 | ||
a81151bd | 111 | fuzz/$FUZZER-test $file |
f8d4b3be KR |
112 | |
113 | Random numbers | |
257e9d03 | 114 | -------------- |
f8d4b3be KR |
115 | |
116 | The client and server fuzzer normally generate random numbers as part of the TLS | |
117 | connection setup. This results in the coverage of the fuzzing corpus changing | |
118 | depending on the random numbers. This also has an effect for coverage of the | |
119 | rest of the test suite and you see the coverage change for each commit even when | |
120 | no code has been modified. | |
121 | ||
122 | Since we want to maximize the coverage of the fuzzing corpus, the client and | |
123 | server fuzzer will use predictable numbers instead of the random numbers. This | |
124 | is controlled by the FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION define. | |
125 | ||
126 | The coverage depends on the way the numbers are generated. We don't disable any | |
127 | check of hashes, but the corpus has the correct hash in it for the random | |
128 | numbers that were generated. For instance the client fuzzer will always generate | |
129 | the same client hello with the same random number in it, and so the server, as | |
130 | emulated by the file, can be generated for that client hello. | |
131 | ||
132 | Coverage changes | |
257e9d03 | 133 | ---------------- |
f8d4b3be KR |
134 | |
135 | Since the corpus depends on the default behaviour of the client and the server, | |
136 | changes in what they send by default will have an impact on the coverage. The | |
137 | corpus will need to be updated in that case. | |
138 | ||
930aa9ee | 139 | Updating the corpus |
257e9d03 | 140 | ------------------- |
930aa9ee KR |
141 | |
142 | The client and server corpus is generated with multiple config options: | |
257e9d03 | 143 | |
930aa9ee KR |
144 | - The options as documented above |
145 | - Without enable-ec_nistp_64_gcc_128 and without --debug | |
146 | - With no-asm | |
147 | - Using 32 bit | |
148 | - A default config, plus options needed to generate the fuzzer. | |
149 | ||
150 | The libfuzzer merge option is used to add the additional coverage | |
151 | from each config to the minimal set. | |
a81151bd DDO |
152 | |
153 | Minimizing the corpus | |
257e9d03 | 154 | --------------------- |
a81151bd DDO |
155 | |
156 | When you have gathered corpus data from more than one fuzzer run | |
157 | or for any other reason want to to minimize the data | |
158 | in some corpus subdirectory `fuzz/corpora/DIR` this can be done as follows: | |
159 | ||
160 | mkdir fuzz/corpora/NEWDIR | |
161 | fuzz/$FUZZER -merge=1 fuzz/corpora/NEWDIR fuzz/corpora/DIR |