ref: 6bda921da0f996fc389caac77950d39cd05c855e
parent: bcf618b256c101e9f4a47af77541a559bb8bb44d
author: Werner Lemberg <[email protected]>
date: Mon Nov 2 01:53:48 EST 2015
[ftfuzzer] Update README file.
--- a/src/tools/ftfuzzer/README
+++ b/src/tools/ftfuzzer/README
@@ -1,23 +1,60 @@
ftfuzzer
---------
+========
-ftfuzzer.cc contains a target function for FreeType fuzzing.
-It can be used with libFuzzer (http://llvm.org/docs/LibFuzzer.html)
-or potentially any other similar fuzzer.
+ftfuzzer.cc
+-----------
+
+This file contains a target function for FreeType fuzzing. It can be used
+with libFuzzer (http://llvm.org/docs/LibFuzzer.html) or potentially any
+other similar fuzzer.
+
Usage:
- 1. Build libfreetype.a and ftfuzzer.cc using the most recent clang compiler
- with these flags:
- -fsanitize-coverage=edge,8bit-counters # for fuzzer coverage feedback
- -fsanitize=address,signed-integer-overflow,shift # for bug checking
- 2. Link with libFuzzer (it contains main()).
+
+ 1. Build `libfreetype.a' and `ftfuzzer.cc' using the most recent clang
+ compiler with these flags:
+
+ -fsanitize-coverage=edge,8bit-counters # for fuzzer coverage feedback
+ -fsanitize=address,signed-integer-overflow,shift # for bug checking
+
+ You also need the header files from `libarchive' for handling tar files
+ (see `ftmutator.cc' below for more).
+
+ 2. Link with `libFuzzer' (it contains main()) and `libarchive'.
+
3. Run the fuzzer on some test corpus.
The exact flags and commands may vary.
-There is a continuous fuzzing bot that runs ftfuzzer:
-https://github.com/google/libfuzzer-bot/tree/master/freetype.
-Check the bot confituration for the most current settings.
-runinput.cc contains a convenience main() function to run the target function
-on a set of input files. Link it with ftfuzzer.cc and libfreetype.a
-and run like "./a.out my_tests_inputs/*"
+
+There is a continuous fuzzing bot that runs ftfuzzer.
+
+ https://github.com/google/libfuzzer-bot/tree/master/freetype
+
+Check the bot configuration for the most current settings.
+
+
+ftmutator.cc
+------------
+
+FreeType has the ability to `attach' auxiliary files to a font file,
+providing additional information. The main usage is to load AFM files for
+PostScript Type 1 fonts.
+
+However, libFuzzer currently only supports mutation of a single input file.
+For this reason, `ftmutator.cc' contains a custom fuzzer mutator that uses
+an uncompressed tar file archive as the input. The first file in such a
+tarball gets opened by FreeType as a font, all other files are treated as
+input for `FT_Attach_Stream'.
+
+Compilation is similar to `ftfuzzer.c'.
+
+
+runinput.cc
+-----------
+
+To run the target function on a set of input files, this file contains a
+convenience main() function. Link it with `ftfuzzer.cc', `libfreetype.a',
+and `libarchive' and run like
+
+ ./a.out my_tests_inputs/*