README
FIPSCHECK project
=================

This package contains library (libfipscheck) and helper binaries which
implement the integrity check of libraries and binaries as required by
FIPS-140-2 validated modules.

The integrity check is only one of many requirements needed for validation
of a software cryptographic module.

Dependencies
============

The package depends on the OpenSSL library for its operation.

Commands
========

fipshmac [-d <path-to-destination-dir>] [-s <hmac-suffix>] <filenames-to-be-checksummed>

This command will create a checksum file in the same directory as the file
which is being checksummed. It will prepend '.' and append <hmac-suffix> to the
original file name. If the suffix is not specified '.hmac' is used.

* return values (exit codes): 0 - OK
  2 - Missing filename
  3 - Cannot open the checksum file
  4 - Cannot read the file to be checksummed, or the checksum computation failed
  5 - Memory allocation error
  6,7 - Cannot write to the checksum file

If invoked correctly the fipshmac command will not print anything to the
standard output or error. Otherwise it will print an error message to stderr.

If destination directory is specified with -d the resulting files will be put
into it and '.' will not be prepended to the file names.

fipscheck [-s <hmac-suffix>] <filenames-to-be-checksummed>

This command will verify a checksum of a file. The file containing the checksum
value is first looked up in the /usr/lib{64,}/fipscheck directory and if not
found there in the same directory as the file which is being checksummed.
The checksum file must have '.' prepended and <hmac-suffix> appended to the original
file name. The '.' must not be prepended to the file names in the
/usr/lib{64,}/fipscheck directory. If the suffix is not specified '.hmac' is used.

* return values (exit codes): 0 - OK
  1 - Checksum mismatch
  2 - Missing filename
  3 - Cannot open the checksum file
  4 - Cannot read the file to be checksummed, or the checksum computation failed
  5 - Memory allocation error
  10 and higher - Failure during self-checking the libfipscheck.so shared library
  20 and higher - Failure during self-checking the fipscheck binary

If invoked correctly the fipscheck command will not print anything to the
standard output or error. If you set an environment variable FIPSCHECK_DEBUG to
value "syslog", it will send eventual error messages to the syslog. If you set
it to value "error", it will send them to the stderr.

Library API
===========

See man 3 fipscheck.h manual page for description of the fipscheck library API. 

Format of the checksum file
===========================

The file contains HMAC-SHA256 encoded in hexadecimal notation with
lowercase letters with one EOL character appended.