openssl/sme8/README.FIPS

User guide for the FIPS Red Hat Enterprise Linux - OpenSSL Module
=================================================================

This package contains libraries which comprise the FIPS 140-2
Red Hat Enterprise Linux - OPENSSL Module.

The module files
================
/lib[64]/libcrypto.so.0.9.8e
/lib[64]/libssl.so.0.9.8e
/lib[64]/.libcrypto.so.0.9.8e.hmac
/lib[64]/.libssl.so.0.9.8e.hmac

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

The approved mode of operation requires kernel with /dev/urandom RNG running
with properties as defined in the security policy of the module. This is
provided by kernel packages with validated Red Hat Enterprise Linux - IPSec
Crytographic Module.

Installation
============

The RPM package of the module can be installed by standard tools recommended
for installation of RPM packages on the Red Hat Enterprise Linux system (yum,
rpm, RHN remote management tool).

For proper operation of the in-module integrity verification the prelink has to
be disabled. This can be done with setting PRELINKING=no in the
/etc/sysconfig/prelink configuration file. If the libraries were already
prelinked the prelink should be undone on all the system files with the
'prelink -u -a' command.

Usage and API
=============

The module respects kernel command line FIPS setting. If the kernel command
line contains option fips=1 the module will initialize in the FIPS approved
mode of operation automatically. To allow for the automatic initialization the
application using the module has to call one of the following API calls:

- void OPENSSL_init(void) - this will do only a basic initialization of the
library and does initialization of the FIPS approved mode without setting up
EVP API with supported algorithms.

- void OPENSSL_add_all_algorithms(void) - this API function calls
OPENSSL_init() implicitly and also adds all approved algorithms to the EVP API
in the approved mode 

- void SSL_library_init(void) - it calls OPENSSL_init() implicitly and also
adds algorithms which are necessary for TLS protocol support and initializes
the SSL library.

To explicitely put the library to the approved mode the application can call
the following function:

- int FIPS_mode_set(int on) - if called with 1 as a parameter it will switch
the library from the non-approved to the approved mode. If any of the selftests
and integrity verification tests fail, the library is put into the error state
and 0 is returned. If they succeed the return value is 1.

To query the module whether it is in the approved mode or not:

- int FIPS_mode(void) - returns 1 if the module is in the approved mode,
0 otherwise.

To query whether the module is in the error state:

- int FIPS_selftest_failed(void) - returns 1 if the module is in the error
state, 0 otherwise.

To zeroize the FIPS RNG key and internal state the application calls:

- void RAND_cleanup(void)

Possible error states of the OpenSSL FIPS module
================================================

The effects of self-test failures in the OpenSSL module differ depending
on the type of self-test that failed.  
The FIPS_mode_set() function verifies the integrity of the runtime executable
using a HMAC SHA-256 digest, which is computed at build time. If this computed
HMAC SHA-256 digest matches the stored, known digest, then the power-up
self-test (consisting of the algorithm-specific Pairwise Consistency and Known
Answer tests) is performed.

Non-fatal self-test errors transition the module into an error state. The
application must be restarted to recover from these errors. The non-fatal
self-test errors are:
FIPS_R_FINGERPRINT_DOES_NOT_MATCH - the integrity verification check failed
FIPS_R_FIPS_SELFTEST_FAILED - a known answer test failed
FIPS_R_PAIRWISE_TEST_FAILED – a pairwise consistency test during DSA or RSA
                              key generation failed
FIPS_R_FIPS_MODE_ALREADY_SET - the application tries to initialize the FIPS
                               approved mode when it is already initialized
These errors are reported through the regular ERR interface of the OpenSSL
library and can be queried by functions such as ERR_get_error(). See the
OpenSSL manual page for the function description.

A fatal error occurs only when the module is already in the error state
(a self test has failed) and the application calls a crypto function of
the module that cannot return an error in normal circumstances (void return
functions). The error message: 'FATAL FIPS SELFTEST FAILURE' is printed to
stderr and the application is terminated with the abort() call.
The only way to recover from a fatal error is to restart the application.
If failures persist, you must reinstall the Module. If you downloaded the
software, verify the package hash to confirm a proper download.
1	wellsi	1.1	User guide for the FIPS Red Hat Enterprise Linux - OpenSSL Module
2			=================================================================
3
4			This package contains libraries which comprise the FIPS 140-2
5			Red Hat Enterprise Linux - OPENSSL Module.
6
7			The module files
8			================
9			/lib[64]/libcrypto.so.0.9.8e
10			/lib[64]/libssl.so.0.9.8e
11			/lib[64]/.libcrypto.so.0.9.8e.hmac
12			/lib[64]/.libssl.so.0.9.8e.hmac
13
14			Dependencies
15			============
16
17			The approved mode of operation requires kernel with /dev/urandom RNG running
18			with properties as defined in the security policy of the module. This is
19			provided by kernel packages with validated Red Hat Enterprise Linux - IPSec
20			Crytographic Module.
21
22			Installation
23			============
24
25			The RPM package of the module can be installed by standard tools recommended
26			for installation of RPM packages on the Red Hat Enterprise Linux system (yum,
27			rpm, RHN remote management tool).
28
29			For proper operation of the in-module integrity verification the prelink has to
30			be disabled. This can be done with setting PRELINKING=no in the
31			/etc/sysconfig/prelink configuration file. If the libraries were already
32			prelinked the prelink should be undone on all the system files with the
33			'prelink -u -a' command.
34
35			Usage and API
36			=============
37
38			The module respects kernel command line FIPS setting. If the kernel command
39			line contains option fips=1 the module will initialize in the FIPS approved
40			mode of operation automatically. To allow for the automatic initialization the
41			application using the module has to call one of the following API calls:
42
43			- void OPENSSL_init(void) - this will do only a basic initialization of the
44			library and does initialization of the FIPS approved mode without setting up
45			EVP API with supported algorithms.
46
47			- void OPENSSL_add_all_algorithms(void) - this API function calls
48			OPENSSL_init() implicitly and also adds all approved algorithms to the EVP API
49			in the approved mode
50
51			- void SSL_library_init(void) - it calls OPENSSL_init() implicitly and also
52			adds algorithms which are necessary for TLS protocol support and initializes
53			the SSL library.
54
55			To explicitely put the library to the approved mode the application can call
56			the following function:
57
58			- int FIPS_mode_set(int on) - if called with 1 as a parameter it will switch
59			the library from the non-approved to the approved mode. If any of the selftests
60			and integrity verification tests fail, the library is put into the error state
61			and 0 is returned. If they succeed the return value is 1.
62
63			To query the module whether it is in the approved mode or not:
64
65			- int FIPS_mode(void) - returns 1 if the module is in the approved mode,
66			0 otherwise.
67
68			To query whether the module is in the error state:
69
70			- int FIPS_selftest_failed(void) - returns 1 if the module is in the error
71			state, 0 otherwise.
72
73			To zeroize the FIPS RNG key and internal state the application calls:
74
75			- void RAND_cleanup(void)
76
77			Possible error states of the OpenSSL FIPS module
78			================================================
79
80			The effects of self-test failures in the OpenSSL module differ depending
81			on the type of self-test that failed.
82			The FIPS_mode_set() function verifies the integrity of the runtime executable
83			using a HMAC SHA-256 digest, which is computed at build time. If this computed
84			HMAC SHA-256 digest matches the stored, known digest, then the power-up
85			self-test (consisting of the algorithm-specific Pairwise Consistency and Known
86			Answer tests) is performed.
87
88			Non-fatal self-test errors transition the module into an error state. The
89			application must be restarted to recover from these errors. The non-fatal
90			self-test errors are:
91			FIPS_R_FINGERPRINT_DOES_NOT_MATCH - the integrity verification check failed
92			FIPS_R_FIPS_SELFTEST_FAILED - a known answer test failed
93			FIPS_R_PAIRWISE_TEST_FAILED – a pairwise consistency test during DSA or RSA
94			key generation failed
95			FIPS_R_FIPS_MODE_ALREADY_SET - the application tries to initialize the FIPS
96			approved mode when it is already initialized
97			These errors are reported through the regular ERR interface of the OpenSSL
98			library and can be queried by functions such as ERR_get_error(). See the
99			OpenSSL manual page for the function description.
100
101			A fatal error occurs only when the module is already in the error state
102			(a self test has failed) and the application calls a crypto function of
103			the module that cannot return an error in normal circumstances (void return
104			functions). The error message: 'FATAL FIPS SELFTEST FAILURE' is printed to
105			stderr and the application is terminated with the abort() call.
106			The only way to recover from a fatal error is to restart the application.
107			If failures persist, you must reinstall the Module. If you downloaded the
108			software, verify the package hash to confirm a proper download.