README

			integrit version 4.2
			  ----------------

BUILD:

To build integrit the following commands should usually suffice:

    ./configure && make

If you are not using a distribution tarball but building from the
sources in git, you will need to first generate configure and
test/test:

    autoconf
    (cd test && m4 test.m4 > test && chmod 755 test)

To build the auxiliary programs, use "make utils".

If you have any trouble, please see the TROUBLESHOOTING section of
INSTALL for more information.


FEATURES include:

* small memory footprint that doesn't grow during runtime

  (reading a cdb database using 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 RipeMD160.

* 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.


NEW IN 4.0:

RipeMD160 is now used for both current-state reports and file
checksums instead of MD5 and SHA1 respectively.

The reasons for this choice are: small checksum size (same db size),
speed (as fast as SHA1), well-tested algorithm and implementation
(RipeMD160 has been around for years), no known weakness to date (both
MD5 and SHA1 are broken).

integrit 4.0 breaks db compatibility with old versions and we've
chosen not to support previous formats for the sake of simplicity. If
you need to compare old dbs you are required to keep a 3.x version of
integrit for that purpose.

Migration to 4.0 can be performed safely with a two-cycle update:
create a new integrit 4.0 db with the same configuration file but
different db locations, check-update the old db with integrit 3 and
double-check for changes. The old integrit 3 db can now be removed.

Apart from the bundled i-ls, both gpg (gpg --print-md ripemd160) and
openssl (openssl rmd160) offer commands to calculate RipeMD160 hashes
to compare the reports generated by integrit.

integrit 4.0 supports delayed failures with a new stop_on_err
directive (defaulting to old behavior).

integrit 4.0 output for new file checksums changed from:

  new: ...
  changed: s(zeroes:...)

to

  new: ...
  new: s(...)

to be more consistent.


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 inefficient and insecure.


LARGE FILE SUPPORT:

Many Operating Systems are in the process of developing support for
large files.  If you see integrit fail when it encounters large files,
then large file support is what you need.  

Since version 3.02, integrit builds with large file support turned on
by default when the host platform supports it.  Please see the
integrit FAQ for more information.  It's in the texinfo documentation
included here and also on the web:

  http://integrit.sourceforge.net/texinfo/integrit.html#FAQ


LIBRARIES:

integrit no longer uses the openssl (http://www.openssl.org/) library
for cryptographic checksums.  (The openssl core team was unresponsive
when consulted about licensing issues, and many users had trouble
installing or linking statically against openssl.)  Now the code for
cryptographic checksums is part of integrit, with implementations from
the GPL'ed GNU Privacy Guard.

integrit uses 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).  

integrit's general hash table code is included as a handy standalone
library that can be used in any application that uses hash tables.
See hashtbl/README for more information.


HOWTO:

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

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

Invoke integrit with the "-h" option for a brief summary of
command-line options.


CDB:

This distribution includes files adapted from those files in Dan
J. Bernstein's cdb-0.75 that are public domain.  

For more info see the cdb homepage at "http://cr.yp.to/cdb.html".
    
I'm using the cdb format because the databases are reliable, cross-
platform, fast, and cdb databases are about half the size of Berkley
databases.


CHECKSUM ALGORITHMS:

integrit uses RipeMD160 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 real advantage
to using more than one secure algorithm. Since there are no known
weaknesses in RipeMD160, 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).  A better way is to use something like
FreeBSD's kernel-based secure levels feature or Linux's capabilities
feature in conjunction with immutable flags in the filesystem.

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$ utils/i-ls 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 checksum this way
(the checksum may be suppressed via the -s switch).

Do "i-ls -h" 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.


BUILDING IN SEPARATE DIRECTORY:

Since version three, integrit supports building in a directory other
than the source directory.  Here's an example:

  mkdir integrit-build
  tar xvfz ~/packages/integrit-x.xx.xx.tar.gz
  cd integrit-build
  ../integrit-x.xx/configure && make

(where x.xx.xx is the integrit version number).  


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

Please try to use the integrit-users mailing list, since it helps
others who may have problems similar to yours.  If you contact me
directly I will probably copy my response to the mailing list unless
you ask me not to.

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

If you'd like to give me money, you can do it easily through paypal.
The integrit homepage has a link, or you can use this one:

    https://www.paypal.com/xclick/business=ecashin%40safe-mail.net&item_name=integrit+donations&item_number=integrit