==============================================================
 IMMUNIX CANARY LIBRARY -- A buffer overflow exploit detector
==============================================================

This document finalized Monday December 15, 1997.

See "http://www.cse.ogi.edu/DISC/projects/immunix/StackGuard/" for
details.

Send technical comments about this distribution to immunix-request@cse.ogi.edu.

See the stackguard compiler README for gory details.  I've eliminated
replicated material between the two readme's.

---------------
 PREREQUISITES
---------------

You also need the stackguard canary gcc compiler from the same place
as you got this (the library).

This (the library) should be v1.1, so you would be looking for
stackguard_gcc version 1.1.  Its all one superpackage.  (Or the pair
is the package, and this is a subpackage.)

See the stackguard compiler README for gory details.

----------
 OVERVIEW
----------

This is version 1.1 of the IMMUNIX CANARY library.  The library is
architecture independant, the compiler only does canaries for Intel
x86.

See the stackguard compiler README for gory details.

--------------
 INSTALLATION
--------------


(1) Unpack this tarball:

	tar xvvzf stackguard-lib.tar.gz

    This creates a directory named "stackguard-lib".

(2) Go to that directory:

	cd stackguard-lib

(3) Configure it to your installation.  The first line of the makefile
    is:

	ROOT = $(wildcard ~/canary)

    change the "~/canary" part to be whereever the directory where you
    want to install the library (tiny) and the compiler (13 meg).

    The following directions assume that you haven't changed this.

    If you haven't already, do:

	mkdir ~/canary ~/canary/lib

(4) Check and store the dependencies:

	make depend

    This shouldn't produce any error messages.  If it does, then
    you're missing something important.  Let me know
    (wagle@cse.ogi.edu) what problems you have.

(5) Compile the library:

	make

(6) Finally, install it:

	make install

    Now you you need the compiler.

-------------------------------------
 COMPILING AND LINKING WITH CANARIES
-------------------------------------

Go build the stackguard compiler, and read its, more comprehensive,
readme.

---------------------------
 QUICK DESCRIPTION OF MODS
---------------------------

This library defines an printf format (char *canary_abort_message) and
initializes an array of 128 random numbers (long __canary[128]).  The
initializer is done as an __constructor__ (using the gcc __attribute__
feature), which causes it to be called before main() gets called.  The
compiler statically assigns each procedure an index into this array,
and that serves as that procedure's canary value for that particular
execution of the program.

---------------------------
 KNOWN QUIRKS AND PROBLEMS
---------------------------

Go see the readme for the stackguard compiler.