Caradoc - a PDF parser and validator
Caradoc is a parser and validator of PDF files written in OCaml. This is version 0.3 (beta).
Caradoc provides many commands to analyze PDFs, as well as an interactive user interface in console.
Caradoc was presented at the the third Workshop on Language-Theoretic Security (LangSec) in May 2016. More information is available on the website of the conference.
Along with an OCaml compiler, this program depends on the following libraries :
menhir, the parser generator that we use to convert PDF grammar into OCaml code ;
ounit, to manage unit tests ;
cryptokit, to handle the decoding of Deflate streams in PDF files ;
curses, for the console UI.
Additionally, CryptoKit relies on the
libgmp-dev Debian packages, and OCaml may require
m4 as well.
The prefered way to install dependencies is via opam, the OCaml package manager. You can use the following commands.
apt-get install ocaml opam apt-get install zlib1g-dev libgmp-dev pkg-config m4 opam init opam install ocamlfind opam install cryptokit ounit menhir curses
It is also possible to use the corresponding Debian packages.
apt-get install ocaml zlib1g-dev ocaml-findlib libcryptokit-ocaml-dev libounit-ocaml-dev libcurses-ocaml-dev menhir
After installing the dependencies, just type
make to compile the code.
You may want to run
make test to check that the program runs properly on your architecture and versions of OCaml and OPAM.
To obtain simple statistics on a PDF file, just type :
caradoc stats path/to/your/input.pdf
To validate a PDF file, check the exit code of :
caradoc stats --strict path/to/your/input.pdf
To normalize a PDF file into the strict syntax :
caradoc cleanup path/to/your/input.pdf --out path/to/your/output.pdf
To print the xref table(s) :
caradoc xref path/to/your/input.pdf
To print the trailer(s) :
caradoc trailer path/to/your/input.pdf
To extract a specific object, given its object number (and generation number, defaulted to zero) :
caradoc object --num 2 path/to/your/input.pdf caradoc object --num 2 --gen 5 path/to/your/input.pdf
To extract complex data in a single command (xref table, dump of all objects, list of types, graph of references) :
caradoc extract --xref <xref output file> --dump <objects output file> --types <types output file> --dot <graph output file> path/to/your/input.pdf
To print the list of PDF types handled by this version of Caradoc :
To find all references to an object, given its object number (and generation number, defaulted to zero) :
caradoc findref --num 2 input.pdf caradoc findref --num 2 --gen 5 --show --highlight input.pdf
To find all occurrences of a PDF name :
caradoc findname --name Page input.pdf caradoc findname --name Resources --show --highlight input.pdf
You can also try the interactive user interface in console :
caradoc ui path/to/your/input.pdf
Ad-hoc parser options
You can specify an option file as parameter of most commands in the relaxed parser mode :
caradoc stats --options path/to/option/file input.pdf
You need to put one option per line in the option file.
The following options are defined, to cope with common errors produced by various PDF software.
allow-invalid-version: allow the header of the PDF file to be ill-formed. However, the file must begin with
allow-dict-duplicates: allow a PDF dictionary to contain several times the same key. In that case, the last occurrence of the key is kept as the actual value.
zero-offset-as-free: treat an xref table entry with an offset of zero as a free object. Some software produce such ill-formed PDFs.
undefined-ref-as-null: treat a reference to an undeclared object as the null object. By default, such references trigger an error.
allow-nonascii-in-names: allow non-ASCII characters in PDF names, even when they are not represented by an escape sequence. By default, non-ASCII characters are only allowed in the form of an escape sequence.
allow-overlaps: allow several objects to overlap in a file, according to the positions declared in xref tables.
xref-stream-default-zero: when the last field is not present in a xref stream (i.e. the /W value for this field is 0), use a default value of 0. The specification defines a default value only for entries of type 1, this option extends it to all types.
allow-arbitrary-info: allow the Info dictionary to contain arbitrary (metadata) keys. Otherwise, unknown keys trigger an error in the type checker.
Structure of the code
The source code is organized as follows :
src/: source code of
src/contentstream/: decoding and validation of content streams ;
src/crypto/: decoding of encrypted files ;
src/data/: modules to represent PDF data (e.g. object, xref table, PDF document) ;
src/graph/: graph checker ;
src/parser/: core parsing code (for the strict and the relaxed parser) ;
src/parser/relaxed/: specific parsing code of the relaxed parser (to fetch objects from xref tables) ;
src/stats/: modules to store statistics about a PDF file ;
src/stream/: decoding of PDF streams ;
src/tools/: various PDF tools (e.g. search in a file) ;
src/type/: code of the type checker ;
src/type/pdf/: definitions of PDF types ;
src/ui/: console user interface ;
src/util/: various helper modules ;
test/: unit tests ;
test_files/: examples of valid and corrupted PDF files.