diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/contents.rst | 1 | ||||
| -rw-r--r-- | doc/manual/fuzzing.rst | 70 |
2 files changed, 71 insertions, 0 deletions
diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst index 23fa218b2..f3b11f7b0 100644 --- a/doc/manual/contents.rst +++ b/doc/manual/contents.rst @@ -36,4 +36,5 @@ Contents cli side_channels packaging + fuzzing support diff --git a/doc/manual/fuzzing.rst b/doc/manual/fuzzing.rst new file mode 100644 index 000000000..b87c6e5e7 --- /dev/null +++ b/doc/manual/fuzzing.rst @@ -0,0 +1,70 @@ +Fuzzing The Library +============================ + +Botan comes with a set of fuzzing endpoints which can be used to test +the library. + +.. highlight:: shell + +Fuzzing with libFuzzer +------------------------ + +To fuzz with libFuzzer (http://llvm.org/docs/LibFuzzer.html), you'll first +need to compile libFuzzer:: + + $ svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk/lib/fuzzer libFuzzer + $ cd libFuzzer && clang -c -g -O2 -std=c++11 *.cpp + $ ar cr libFuzzer.a libFuzzer/*.o + +Then build the fuzzers:: + + $ ./configure.py --with-santitizers --build-fuzzer=libfuzzer --unsafe-fuzzer-mode + $ make fuzzers + +Using `--with-sanitizers` is optional but highly useful. + +The fuzzer binaries will be in `build/fuzzer`. Simply pick one and run it, optionally +also passing a directory containing corpus inputs. + +Using `libfuzzer` build mode implicitly assumes the fuzzers need to +link with `libFuzzer`; if another library is needed (for example in +OSS-Fuzz, which uses `libFuzzingEngine`), use the flag +`--with-fuzzer-lib` to specify the desired name. + +Fuzzing with AFL +-------------------- + +To fuzz with AFL (http://lcamtuf.coredump.cx/afl/):: + + $ ./configure.py --with-sanitizers --build-fuzzer=afl --unsafe-fuzzer-mode --cc-bin=afl-g++ + $ make fuzzers + +You can also use `afl-clang-fast++` or `afl-clang++`. + +The fuzzer binaries will be in `build/fuzzer`. To run them you need to +run under `afl-fuzz`:: + + $ afl-fuzz -i corpus_path -o output_path ./build/fuzzer/binary + +Input Corpus +----------------------- + +AFL requires an input corpus, and libFuzzer can certainly make good +use of it. + +Some crypto corpus repositories include + +* https://github.com/randombit/crypto-corpus +* https://github.com/mozilla/nss-fuzzing-corpus +* https://github.com/google/boringssl/tree/master/fuzz +* https://github.com/openssl/openssl/tree/master/fuzz/corpora + +Adding new fuzzers +--------------------- + +New fuzzers are created by adding a source file to `src/fuzzers` which +have the signature: + +``void fuzz(const uint8_t in[], size_t len)`` + +After adding your fuzzer, rerun `./configure.py` and build. |