			integrit version 1.06
			  -----------------

BUILD:

To build integrit the following commands should usually suffice:

    ./configure && make

If GNU make is called "gmake" on your system, use gmake instead of
make in the above commands.  See INSTALL for more information.

To build the auxiliary programs, use "make aux" or "gmake aux".


FEATURES include:

* small memory footprint that doesn't grow during runtime

  (cdb's use of mmap makes integrit look bigger than it really is on
  some systems when integrit is doing a check)

* can do simultaneous check against a known-state database and update
  (generating a new current-state database)

* uses up-to-date one-way hash algorithms, like the 160-bit Secure
  Hash Algorithm, by way of openssl's crypto library.

* prints checksum of current-state database 

  (important when running unattended, so that the user can verify that
  the new database hasn't been modified since its creation.)

* simple design means a smaller learning curve for users

* clear terminology based on the concept of known state versus current
  state 

* intuitive cascading rulesets for paths in configuration file

* an option to reset the file access time of selected files after
  checksumming

* XML output option for easy parsing of integrit's output

* fast compile time

  (not a priority, but a perk of integrit's simplicity ;)

* standalone auxiliary programs that you can ignore safely or use if
  you need them.


PROC:

Avoid running integrit on /proc or other virtual filesystems that look
like files and really read information from the kernel.

Use a rule in your configuration file like this:

    !/proc

... because doing something like 'find /proc -type f | xargs grep foo'
or running integrit on /proc does weird and sometimes bad things.


NFS MOUNTED FILESYSTEMS:

Avoid running integrit on nfs mounted filesystems, unless you're
feeling really adventurous and cocky.  If you are, then read the next
paragraph; otherwise, put a rule in the configuration file like this
to ignore each nfs-mounted filesystem:

    !/mnt/nfsdir

Keep in mind that resetting the access time (default integrit behavior
is NOT to reset the access time) on remote files via NFS may cause
problems if root-squashing is in effect.  Also, running integrit on
NFS-mounted filesystems is really inefficient.


LIBRARIES:

integrit uses the openssl (http://www.openssl.org/) library for
cryptographic checksums and the Boehm garbage collection library
(http://reality.sgi.com/boehm/gc.html) for memory leak detection, not
for garbage collection, though.  You don't need the Boehm GC library
unless you want to build the memory-leak detecting version of integrit
(like if you're an integrit developer).  You'll need to be able to do
static linking against your openssl libcrypto library.

Advantages of using openssl include greater peer-review audience of
cryptographic code (lots of people use and scrutinize openssl) and
consequent high-quality code.

The only disadvantages I can think of are that you need a trusted
openssl installation and you need to be able to link statically
against libcrypto (maybe confusing ?).

integrit's general hash table code is included as a standalone library
that can be used in any application that uses hash tables.


HOWTO:

There is some information on how to use integrit on the web:

      http://integrit.sourceforge.net/howto.html

usage:

      integrit -C conffile [-x] [-u] [-c]
      integrit -V
      integrit -h

options:
	
      -C	specify configuration file
      -x	use XML output instead of human-readable output
      -u	do update: create current state database
      -c	do check: verify current state against known db
      -V	show integrit version and exit
      -h	show this help      


CDB:

This distribution includes an unaltered cdb distribution, possible
both by virtue of D.J. Bernstein's generosity and by virtue of cdb's
small code size.

From the cdb homepage at http://cr.yp.to/cdb.html:

    cdb is a fast, reliable, simple package for creating and reading
    constant databases. Its database structure provides several
    features:
    
    	  Fast lookups: A successful lookup in a large database
    	  normally takes just two disk accesses. An unsuccessful
    	  lookup takes only one.

    	  Low overhead: A database uses 2048 bytes, plus 24 bytes per
    	  record, plus the space for keys and data.

    	  No random limits: cdb can handle any database up to 4
    	  gigabytes. There are no other restrictions; records don't
    	  even have to fit into memory. Databases are stored in a
    	  machine-independent format.

    	  Fast atomic database replacement: cdbmake can rewrite an
    	  entire database two orders of magnitude faster than other
    	  hashing packages.

    	  Fast database dumps: cdbdump prints the contents of a
    	  database in cdbmake-compatible format.
    
I'm using cdb because the databases are purported to be more reliable
than Berkley databases, and (more importantly since I don't know that
for myself) cdb databases are about half the size of Berkley
databases. 


CHECKSUM ALGORITHMS:

integrit uses SHA-1 as the only cryptographically-secure checksum
(MDC, or Manipulation Detection Code) algorithm.  That may come as a
surprise to someone who has used tripwire, which has nine or so
algorithms, plus a hook for a user-supplied algorithm.

The reason for this limitation is simple: there is no advantage to
using more than one algorithm.  SHA-1 (Secure Hash Algorithm 1)
produces a 160-bit checksum.  Since there are no known weaknesses in
SHA-1, to find a file with the same checksum as a given file on your
machine with certainty, an attacker would have to make as many
different files with as many different file contents as there are
different values that could fit in a 160-bit binary number (two to the
power of 160).  

On average, though, the attacker would only have to try half as many
times, (half of two to the power of 160 is two to the power of 159).
That number is so mind-whoppingly huge that the experts agree that
such an attack would never work today or in the near future.  Someday,
big advances in mathematics and hardware capabilities may make such an
attack feasible, but by that time there will be better checksum
algorithms.

It would be easy to add more algorithms to integrit, but the databases
would be bigger, runtime would be longer, and there would be no gains.
If there were runtime options for the additional algorithms, that
would mean more complexity for the user, again with no additional
benefit.


CONFIGURATION FILE:

integrit requires a configuration file at runtime.  One way to do this
securely is to copy the configuration file to a secure medium (e.g. a
trusted, very tight machine; or a CD-ROM) that is available to the
host where you're running the check (e.g. via read-only NFS or
one-command ssh keys).

(Ask me about one-command ssh keys.  It's a really nice technique if
you're comfortable with ssh.)

The syntax of the file is pretty simple and should be familiar to
users of tripwire and the like.  The known-state database and the
current-state database are specified, as well as the root directory of
the integrit search.  See usr.conf for an example.

Next come rules that govern the way integrit should treat files and
directories it encounters on its search.  An exclamation point means
that the file or directory is passed over entirely.  An equal sign
before a directory means that integrit's search should not descend
into the subdirectories of that directory.

The checks that integrit should perform on a file are given in
one-letter options after the file name.  A lowercase letter turns on
an option and uppercase turns the option off.  e.g., the following
lines mean that there won't be a checksum done on /var/log/messages,
but there will be on /etc/shadow:

     /var/log/messages S
     /etc/shadow s

In addition to options for checks, there's another option, "r", which
requests that integrit reset the file access time if integrit does a
checksum of the file.

The default checks are: checksum; inode; permissions; number of links,
uid, gid, mtime (siplugZAm).  

NOTE: Since version 1.01, Access times are NOT reset by default.

      One reason is that resetting the access time (atime) means that
      the ctime is updated.  That causes incompatibilities with other
      file integrity verification systems.

      Also, it takes more runtime and is not always necessary, so
      making it an option makes sense.

      Also, on some systems you can't reset the atime of certain
      files.  FreeBSD, for instance.

If needed, you can override the default option set by providing a
checkset containing all the switches for the integrit root directory
in the conf file.

Here's a table of letters and the corresponding options:

        s	checksum
        i	inode
        p	permissions
        l	number of links
        u	uid
        g	gid
        z	file size (redundant if checksums are on)
        a	access time (atime)
        m	modification time
	c	change file info time (ctime)
	r	reset access time

NOTE: As a convenience to the user, on files you have opted to reset
      the atime, integrit will always ignore the ctime, since
      resetting the atime always updates the ctime.


EXAMPLES:

There's an "examples" directory with some ideas for how to use
integrit. 


AUXILIARY PROGRAMS:

You don't need to use these programs in order to use integrit.  If you
are starting out with integrit, you can safely ignore them.  Later
they may come in handy.

New in version 1.03, there's a simple viewer for integrit databases,
"i-viewdb".  Anyone familiar with the human-readable output syntax
described in the integrit manpage should have no trouble understanding
its output.

Call i-viewdb with no arguments for a brief synopsis of its usage.

New in version 1.05, there's a standalone program, "i-ls", that can
display the same stat and checksum information that integrit looks at
for *live files* or all the files in a directory.  e.g., 

    ecashin@nilda integrit$ aux/i-ls -s main.c
    main.c   i(127479) p(644) l(1) u(1001) g(1001) z(5391) \
     a(20010110-220035) m(20001231-171729) c(20010108-232929) \
     s(d6ad9708aab5ebe019629d5bf349b01d8dc1a2ad) 

That's a lot of information for one line, but it's kind of nice to be
able to see all the information integrit uses for live files.  I think
it's especially neat that you can get a quick SHA-1 checksum this way
(with the -s switch).

Call i-ls with no arguments for a brief synopsis of its usage.


HASHTBL:

integrit uses and includes the hashtbl hash table library, and as of
version 1.04, hashtbl is a standalone library.  You can use as many
hashtbl objects as you want in a program.  You can store any data you
want in a hashtbl by way of a void pointer.  See the README file in
the hashtbl directory for more info.


CONTACT INFORMATION:

Please write with feedback, either on a mailing list or directly.
Many people download integrit, but the ones who have provided feedback
are the ones who have helped integrit graduate from my own personal
solution to a tool for everyone.

There are two mailing lists: integrit-users (discussion of using
integrit) and integrit-devel (discussion of integrit's design and
development) at lists.sourceforge.net.  You can join or read the
archives at the following URL:

    http://sourceforge.net/mail/?group_id=15369

You can also contact me directly:

    Ed L Cashin <ecashin@users.sourceforge.net>
  
    P.O. Box 2457
    Athens GA 30612

