<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='fipscheck3'>
<refentryinfo><date>16 April 2012</date></refentryinfo>
<refmeta>
<refentrytitle>FIPSCHECK</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class='date'>16 April 2012</refmiscinfo>
<refmiscinfo class='source'>fipscheck</refmiscinfo>
<refmiscinfo class='manual'>fipscheck</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>FIPSCHECK_verify</refname>
<refname>FIPSCHECK_verify_ex</refname>
<refname>FIPSCHECK_verify_files</refname>
<refname>FIPSCHECK_verify_files_ex</refname>
<refname>FIPSCHECK_fips_module_installed</refname>
<refname>FIPSCHECK_get_binary_path</refname>
<refname>FIPSCHECK_get_library_path</refname>
<refname>FIPSCHECK_kernel_fips_mode</refname>
<refname>fipscheck.h</refname>
<refpurpose>Various functions relating to running in FIPS mode</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv id='synopsis'>
<funcsynopsis>
<funcsynopsisinfo>
#include <fipscheck.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>FIPSCHECK_verify</function></funcdef>
<paramdef>const char *<parameter>libname</parameter></paramdef>
<paramdef>const char *<parameter>symbolname</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_verify_ex</function></funcdef>
<paramdef>const char *<parameter>libname</parameter></paramdef>
<paramdef>const char *<parameter>symbolname</parameter></paramdef>
<paramdef>const char *<parameter>hmac_suffix</parameter></paramdef>
<paramdef>int <parameter>fail_if_missing</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_verify_files</function></funcdef>
<paramdef>const char *<parameter>files[]</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_verify_files_ex</function></funcdef>
<paramdef>const char *<parameter>hmac_suffix</parameter></paramdef>
<paramdef>int <parameter>fail_if_missing</parameter></paramdef>
<paramdef>const char *<parameter>files[]</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_fips_module_installed</function></funcdef>
<paramdef>const char *<parameter>libname</parameter></paramdef>
<paramdef>const char *<parameter>symbolname</parameter></paramdef>
<paramdef>const char *<parameter>hmac_suffix</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_get_binary_path</function></funcdef>
<paramdef>char *<parameter>path</parameter></paramdef>
<paramdef>size_t <parameter>pathlen</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_get_library_path</function></funcdef>
<paramdef>const char *<parameter>libname</parameter></paramdef>
<paramdef>const char *<parameter>symbolname</parameter></paramdef>
<paramdef>char *<parameter>path</parameter></paramdef>
<paramdef>size_t <parameter>pathlen</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>FIPSCHECK_kernel_fips_mode</function></funcdef>
<paramdef>void<parameter></parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id='description'><title>DESCRIPTION</title>
<para>The function <function>FIPSCHECK_kernel_fips_mode()</function> tests
for the FIPS-140-2 mode in kernel.
</para>
<para>The function <function>FIPSCHECK_verify()</function> computes and compares
HMAC-SHA256 checksum by spawning the <command>fipscheck</command> command.
The parameters <parameter>libname</parameter> and <parameter>symbolname</parameter>
determine which shared library file loaded into the process space will be checksummed.
If these parameters are set to NULL, the executable of the calling process is
checksummed.
</para>
<para>The function <function>FIPSCHECK_verify_ex()</function> in addition to
the functionality above also allows to specify the full <parameter>hmac_suffix</parameter>
with the default value of .hmac. And will return success if the hmac file is
missing and the <parameter>fail_if_missing</parameter> parameter is set to 0.
</para>
<para>The function <function>FIPSCHECK_verify_files()</function> can be used
to explicitly specify NULL terminated array of file names in the parameter
<parameter>files</parameter> to check.
</para>
<para>Similarly the function <function>FIPSCHECK_verify_files_ex()</function> in addition to
the functionality above also allows to specify the full <parameter>hmac_suffix</parameter>
with the default value of .hmac. And will return success if the first hmac
file is missing and the <parameter>fail_if_missing</parameter> parameter
is set to 0.
</para>
<para>
The checksum file contains the HMAC-SHA256 encoded in hexadecimal notation
using lowercase letters with one EOL character appended at the end.
</para>
<para>The function <function>FIPSCHECK_fips_module_installed()</function>
returns 1 if the hmac checksum file is found and 0 otherwise.
</para>
<para>The functions <function>FIPSCHECK_get_library_path()</function> and
<function>FIPSCHECK_get_binary_path()</function> return the shared library
and executable paths in the <parameter>path</parameter>. The buffer pointed
to by the parameter must be large enough to hold the path otherwise
the path is truncated. The size of the buffer is specified by the
<parameter>pathlen</parameter>.
</para>
</refsect1>
<refsect1 id='returnvalue'><title>RETURN VALUE</title>
<para>The main functions <function>FIPSCHECK_verify()</function> and
<function>FIPSCHECK_verify_files()</function> return 1 when the
verification of the binaries succeeds and 0 otherwise. The function
<function>FIPSCHECK_kernel_fips_mode()</function> returns 1 when the
kernel is in fips mode and 0 otherwise.
</para>
<para>The auxiliary functions <function>FIPSCHECK_get_binary_path()</function>
and <function>FIPSCHECK_get_library_path()</function> return 0 on success
and -1 if the path cannot be determined.
</para>
</refsect1>
<refsect1 id='fips'><title>FIPS MODE</title>
<para>A kernel compiled with CONFIG_CRYPTO_FIPS=y can be booted in fips mode
by specifying fips=1 as kernel parameter. Please refer to the security policy
of the Kernel FIPS module for further details.
</para>
</refsect1>
<refsect1 id='see_also'><title>SEE ALSO</title>
<para><citerefentry><refentrytitle>fipscheck</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>fipshmac</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<ulink url='https://fedorahosted.org/fipscheck/'>https://fedorahosted.org/fipscheck/</ulink></para>
</refsect1>
<refsect1 id='author'><title>AUTHOR</title>
<para>Tomas Mraz <tmraz@redhat.com>.
</para>
<para>Man page authors Paul Wouters <pwouters@redhat.com> and Tomas Mraz <tmraz@redhat.com>.</para>
</refsect1>
<refsect1 id='copyright'><title>COPYRIGHT</title>
<para>Copyright 2008, 2012 Red Hat, Inc. All rights reserved.</para>
<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
</para>
<para>
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.</para><para>
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
</para>
</refsect1>
</refentry>