AnonymousFox

//usr/share/doc/fipscheck-1.2.0/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 <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' to the
original file name.

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

fipscheck <filenames-to-be-checksummed>

This command will verify a checksum stored in the file in the same directory
as the file which is being checksummed. The checksum file must have '.'
prepended and '.hmac' appended to the original file name.

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

int FIPSCHECK_verify(const char *libname, const char *symbolname)

This will invoke fipscheck on either a shared library if both libname and
symbolname are not NULL or on the executable binary from which the
FIPSCHECK_verify was called. Possible causes of the failed checks are
the shared library/executable cannot be read, the checksum is missing
or unreadable, or the checksum is wrong. Note that prelink will break the
checksums so it must be disabled when fipscheck is used to verify the
integrity of fips validated libraries/executables.

* return values: 0 - failure
  1 - success

int FIPSCHECK_verify_files(const char *files[])

This will invoke fipscheck to verify the HMAC checksums of the files in
the NULL terminated array of pointers. The same pitfalls which might
cause verification errors apply as above.

* return values: 0 - failure
  1 - success

int FIPSCHECK_get_binary_path(char *path, size_t pathlen)

Auxiliary function - returns path pointing to the executable file which is
being run. The path buffer must be large enough to hold the path, otherwise
it is truncated.

* return values: 0 - success
  -1 - failure

int FIPSCHECK_get_library_path(const char *libname, const char *symbolname, char *path, size_t pathlen)

Auxiliary function - returns path pointing to the shared library file with
a name libname and containing a symbol symbolname. The path buffer must be
large enough to hold the path, otherwise it is truncated.

* return values: 0 - success
  -1 - failure

int FIPSCHECK_kernel_fips_mode(void)

Auxiliary function - returns the value of the kernel fips mode flag.

* return values: 0 - the kernel fips mode flag is 0 or unreadable
  1 - the kernel fips mode flag is 1

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

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