This directory contains a number of small examples to try analyzing
with cqual.

There is a brief walkthrough of the taint0.c/taint1.c example at the
end of this file.

Tainted/untainted examples (use gcqual)
--------------------------

taint0.c	A short, unannotated program with a format-string bug
taint1.c	taint0.c with annotations
taint2.c	A more complicated taint-flow path
taint-cast.c	Shows how taint interacts with casting, when 
                the partial order is not specified as [casts-preserve].
taint-const-subtyping.c
		Shows how const improves the analysis precision
taint-poly.c	Demonstrates how polymorphism works
taint-varargs.c	Shows how `...' can be annotated with a qualifier

User/kernel examples (use kqual, for convenience)
--------------------
user0.c         A short example using structural constraints
user1.c         A longer example derived from a real kernel bug
                found by cqual

Locked/unlocked examples (not currently supported)
------------------------

lock.c		A simple program that changes the state of a lock
lock2.c		lock.c rewritten to use change_type
lock3.c		locks used in function calls
linux-lock.{c,i}  checking for simple deadlocks in the linux kernel
linux-lock2.{c,i} checking for simple deadlocks in the linux kernel
		-- in both these examples we inline the definition of
		   spin_lock and spin_unlock, because we do not
		   have polymorphism in the flow-sensitive system

Y2K examples (use gcqual)
------------

The remaining examples in this directory show how cqual can be used to
find Y2K bugs in C programs, like Carillon.  To try these examples you
need to un-comment out the Y2K qualiifers in the default lattice
file.  Note that the path browsing in PAM mode doesn't work correctly
with these qualifiers.

Note:  To run these examples, disable -fflow-sensitive in your .emacs file.

y2k1.c		A short, unannotated program with a Y2K bug (from Carillon)
y2k2.c		The annotated version of y2k1.c (from Carillon)
y2k3.c		A program showing how the sometimes non-intuitive flow
		of the Y2K qualifiers
y2k4.c		An example showing how to add qualifiers to the *
		operator
rcs[1-3].c	A more complicated example with a Y2K bug (from Carillon)

===========================================================================

WALKTHROUGH
-----------

Here is a walkthrough of the taint0/taint1.c example.  This
explanation also appears in user-guide.{ps,pdf}.

============================================================================

In this section we present a small example showing how to use cqual
to find a potential format-string vulnerability in a C program.
Consider the following program, which is included in the distribution
as examples/taint0.c:

	char *getenv(const char *name);
	int printf(const char *fmt, ...);

	int main(void)
	{
	  char *s, *t;
	  s = getenv("LD_LIBRARY_PATH");
	  t = s;
	  printf(t);
	}

This program reads the value of LD_LIBRARY_PATH from the environment
and passes it to printf as a format string.  If an untrusted user can
control the environment in which this program is run, then this
program may have a format-string vulnerability.  For example, if the
user sets LD_LIBRARY_PATH to a long sequence of %s's, the program will
likely seg fault.

By default cqual assumes nothing about the behavior of your
program.  (Cqual comes with some default configuration files
for checking for format-string vulnerabilities; more on this below.)
In order to start checking for bugs, we need to annotate the program
with extra type qualifiers.  For this example we will use two
qualifiers.  We will annotate untrusted strings as tainted, and we
will require that printf take untainted data:

	$tainted char *getenv(const char *name);
	int printf($untainted const char *fmt, ...);

	int main(void)
	{
	  char *s, *t;
	  s = getenv("LD_LIBRARY_PATH");
	  t = s;
	  printf(t);
	}

In cqual all user-defined qualifiers, which we will refer to constant
qualifiers or partial order elements, begin with dollar signs.  Notice
that we only need to annotate getenv and printf with type qualifiers.
For this example cqual will infer that s and t must also be tainted,
and hence will signal a type error: tainted data is being passed to
printf, which requires untainted data.  The presence of a type error
indicates a potential format-string vulnerability.

Running cqual
-------------

Assuming that cqual is already installed as described above, you can
run cqual on this example program to see what happens.  From within
emacs type M-x cqual and press return.  Enter the file name
examples/taint1.c (assuming you are in the top-level cqual directory)
and press return.

cqual analyzes the file and brings up a window listing the input
files and the analysis results.  In this case, cqual complains

/tmp/mKh48NWKA2:8  (.../examples/taint1.c)
incompatible types in assignment

*s:  $tainted $untainted

$tainted <= *getenv_ret
         <= *getenv_ret@8
         <= *s
         <= *t
         <= *printf_arg1@10
         <= *printf_arg1
         <= $untainted

The user interface used to display the analysis results is Program
Analysis Mode (pam), a generic interface for marking up programs in
emacs.  Middle-clicking on a hyperlink with the mouse or moving the
cursor over a hyperlink and pressing C-c C-l will follow that link.
Error messages are linked to the position in the file where the error
was generated.

If you middle-click on the error message link you will see a marked-up
display of taint1.c.  Identifiers are colored according to their
inferred qualifiers.  In the default configuration file, tainted
identifiers are colored red, untainted identifiers are colored green,
and identifiers that may contribute to a type error are colored
purple.

Each marked-up identifier is also a hyperlink.  Middle-clicking on an
identifier will show you the type of the identifier, fully annotated
with qualifiers.  For example, middle-clicking on t should bring up a
window showing

	t: &t ptr (t ptr (*t char))

The name of the identifier is shown to the left of the colon, and its
inferred types are shown to the right of the colon.

Here t has the type pointer to pointer to character.  (See the user
guide for an explanation.)  Notice that cqual writes types from
left-to-right using ptr as a type constructor.

The three hyperlinked names in the type are qualifier
  variables.  In this case the qualifier variable t'' (throughout
this document we italicize qualifier variables) is colored purple
because it has been inferred to be both tainted and untainted, an
error.

Middle-clicking on a qualifier variable will show you the inferred
value of the qualifier variable and the shortest path on which it was
inferred to have its value.  For example, if you click on
*t, you should see the following result:

*t:  $tainted $untainted

$tainted <= *getenv_ret
         <= *getenv_ret@8
         <= *s
         <= *t
         <= *printf_arg1@10
         <= *printf_arg1
         <= $untainted

The first line tells us that *t is both tainted and untainted, an
error.  The remaining lines show us an erroneous path.  We see that
*t was tainted from *s, which was tainted from the return type of
getenv.  We also see that the error arises because *t taints the
parameter to printf, which must be untainted.

Middle-clicking on a <= will jump to the source location where that
constraint was generated.  Middle-clicking an a qualifier we compute
the shortest path by which that qualifier was inferred to have its
value.  And shift-middle-clicking on a qualifier will jump to the
source location where the identifier corresponding to that qualifier
was defined.

You can also run cqual on the command line.  If you do so with the
appropriate configuration arguments then cqual will generate the
same error messages, but you will be unable to interactively explore
the analysis results:


  [jfoster@lagaffe cqual]$ gcqual examples/taint1.c
  examples/taint1.c:7 incompatible types in assignment
  *s: $tainted $untainted 
  /usr/local/share/cqual/prelude.cq:58     $tainted <= *getenv_ret
                  examples/taint1.c:7               <= *s
                  examples/taint1.c:8               <= *t
                  examples/taint1.c:9               <= *printf_arg1
  /usr/local/share/cqual/prelude.cq:33              <= $untainted


Cqual comes with a standard prelude file that contains declarations of
standard-library functions that have been annotated with tainted and
untainted.  See the user guide for more discussion.
