Add some docs about fuzzing

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.