'\" t
.\"     Title: FIPSCHECK
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 16 April 2012
.\"    Manual: fipscheck
.\"    Source: fipscheck
.\"  Language: English
.\"
.TH "FIPSCHECK" "3" "16 April 2012" "fipscheck" "fipscheck"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
FIPSCHECK_verify, FIPSCHECK_verify_ex, FIPSCHECK_verify_files, FIPSCHECK_verify_files_ex, FIPSCHECK_fips_module_installed, FIPSCHECK_get_binary_path, FIPSCHECK_get_library_path, FIPSCHECK_kernel_fips_mode, fipscheck.h \- Various functions relating to running in FIPS mode
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <fipscheck\&.h>

.fi
.ft
.HP \w'int\ FIPSCHECK_verify('u
.BI "int FIPSCHECK_verify(const\ char\ *" "libname" ", const\ char\ *" "symbolname" ");"
.HP \w'int\ FIPSCHECK_verify_ex('u
.BI "int FIPSCHECK_verify_ex(const\ char\ *" "libname" ", const\ char\ *" "symbolname" ", const\ char\ *" "hmac_suffix" ", int\ " "fail_if_missing" ");"
.HP \w'int\ FIPSCHECK_verify_files('u
.BI "int FIPSCHECK_verify_files(const\ char\ *" "files[]" ");"
.HP \w'int\ FIPSCHECK_verify_files_ex('u
.BI "int FIPSCHECK_verify_files_ex(const\ char\ *" "hmac_suffix" ", int\ " "fail_if_missing" ", const\ char\ *" "files[]" ");"
.HP \w'int\ FIPSCHECK_fips_module_installed('u
.BI "int FIPSCHECK_fips_module_installed(const\ char\ *" "libname" ", const\ char\ *" "symbolname" ", const\ char\ *" "hmac_suffix" ");"
.HP \w'int\ FIPSCHECK_get_binary_path('u
.BI "int FIPSCHECK_get_binary_path(char\ *" "path" ", size_t\ " "pathlen" ");"
.HP \w'int\ FIPSCHECK_get_library_path('u
.BI "int FIPSCHECK_get_library_path(const\ char\ *" "libname" ", const\ char\ *" "symbolname" ", char\ *" "path" ", size_t\ " "pathlen" ");"
.HP \w'int\ FIPSCHECK_kernel_fips_mode('u
.BI "int FIPSCHECK_kernel_fips_mode(void" "" ");"
.SH "DESCRIPTION"
.PP
The function
\fBFIPSCHECK_kernel_fips_mode()\fR
tests for the FIPS\-140\-2 mode in kernel\&.
.PP
The function
\fBFIPSCHECK_verify()\fR
computes and compares HMAC\-SHA256 checksum by spawning the
\fBfipscheck\fR
command\&. The parameters
\fIlibname\fR
and
\fIsymbolname\fR
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\&.
.PP
The function
\fBFIPSCHECK_verify_ex()\fR
in addition to the functionality above also allows to specify the full
\fIhmac_suffix\fR
with the default value of \&.hmac\&. And will return success if the hmac file is missing and the
\fIfail_if_missing\fR
parameter is set to 0\&.
.PP
The function
\fBFIPSCHECK_verify_files()\fR
can be used to explicitly specify NULL terminated array of file names in the parameter
\fIfiles\fR
to check\&.
.PP
Similarly the function
\fBFIPSCHECK_verify_files_ex()\fR
in addition to the functionality above also allows to specify the full
\fIhmac_suffix\fR
with the default value of \&.hmac\&. And will return success if the first hmac file is missing and the
\fIfail_if_missing\fR
parameter is set to 0\&.
.PP
The checksum file contains the HMAC\-SHA256 encoded in hexadecimal notation using lowercase letters with one EOL character appended at the end\&.
.PP
The function
\fBFIPSCHECK_fips_module_installed()\fR
returns 1 if the hmac checksum file is found and 0 otherwise\&.
.PP
The functions
\fBFIPSCHECK_get_library_path()\fR
and
\fBFIPSCHECK_get_binary_path()\fR
return the shared library and executable paths in the
\fIpath\fR\&. 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
\fIpathlen\fR\&.
.SH "RETURN VALUE"
.PP
The main functions
\fBFIPSCHECK_verify()\fR
and
\fBFIPSCHECK_verify_files()\fR
return 1 when the verification of the binaries succeeds and 0 otherwise\&. The function
\fBFIPSCHECK_kernel_fips_mode()\fR
returns 1 when the kernel is in fips mode and 0 otherwise\&.
.PP
The auxiliary functions
\fBFIPSCHECK_get_binary_path()\fR
and
\fBFIPSCHECK_get_library_path()\fR
return 0 on success and \-1 if the path cannot be determined\&.
.SH "FIPS MODE"
.PP
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\&.
.SH "SEE ALSO"
.PP
\fBfipscheck\fR(8),
\fBfipshmac\fR(8),
\m[blue]\fBhttps://fedorahosted\&.org/fipscheck/\fR\m[]
.SH "AUTHOR"
.PP
Tomas Mraz <tmraz@redhat\&.com>\&.
.PP
Man page authors Paul Wouters <pwouters@redhat\&.com> and Tomas Mraz <tmraz@redhat\&.com>\&.
.SH "COPYRIGHT"
.PP
Copyright 2008, 2012 Red Hat, Inc\&. All rights reserved\&.
.PP
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
.PP
1\&. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer\&.
.PP
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\&.