File README-FIPS.txt of Package openssl-1_0_0

README-FIPS.txt - Roman Drahtmueller <draht@suse.de>, June 16 2012

NOTE: Finished the adjustment of DSO path and correct the version
information for SLE 12. Still need to review about AES-NI optimization.
Shawn Chang <shchang@suse.com>, Dec 7 2013.

NOTE: Outdated currently for openSUSE Factory / SLE 12, needs review
and adjustments. But basic settings still are the same.
Marcus Meissner <meissner@suse.de>, 2013/Dec/03.

* general information
* FIPS-140-2 mode of operation
* overview: openssl subpackages on SLES12
==============================================================================

* general information
==============================================================================

Dear user of the SUSE Linux Enterprise Server,

SLES12 comes with openssl of version 1.0.1e, a version upgrade from
0.9.8j that came with earlier revisions of SLES11-SP3.

The new version has support for FIPS-140-2 mode of operation.
FIPS is short for Federal Information Processing Standard.
For more information on FIPS-140-2, please see
http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf
and more publications on the NIST website.

The openssl shared libraries are used by numerous packages in the
SUSE Linux Enterprise Server. If the library runs in FIPS-140-2 mode,
then the binary that links against the library at runtime makes use
of FIPS-140-2 validated cryptography as defined in its cryptographic
module. By consequence, a large number of packages can make a claim
about using FIPS-140-2 validated cryptographical functions.

Both the 64bit and the 32bit shared libraries are supported in FIPS-140-2
mode of operation.
Both in 64bit and in 32bit mode, the AES-NI assembler optimizations are
supported and used, if the used CPU supports the AES-NI instructions. These
assembler optimizations can deliver a substantial performance benefit.
To check if your system's CPU(s) has (have) AES-NI support, have a look 
into the Linux kernel's /proc file /proc/cpuinfo - search it for the "aes"
flag.
AES-NI support can be disabled by setting the environment variable
OPENSSL_DISABLE_AESNI before running binaries that link against openssl.
The "openssl speed" command can give you an idea for the performance
differences.

The cryptographic module as defined for FIPS-140-2 is contained in the files
   /lib64/.libcrypto.so.1.0.0.hmac
   /lib64/.libssl.so.1.0.0.hmac
   /lib64/libcrypto.so.1.0.0
   /lib64/libssl.so.1.0.0
for 64bit operation and
   /lib/.libcrypto.so.1.0.0.hmac
   /lib/.libssl.so.1.0.0.hmac
   /lib/libcrypto.so.1.0.0
   /lib/libssl.so.1.0.0
for 32bit.

The .hmac files contain a HMAC for the internal integrity checking. They 
are contained in the package libopenssl1_0_0-hmac, seperate from the 
libopenssl1_0_0 package. These hashes are produced as one of the last steps 
during the RPM build process.
  If the library starts up in FIPS mode, the .hmac files are read, and the 
checksum is verified against a new self-measurement of the library. 
Essentially, this means that the FIPS mode of operation is not possible
without the .hmac files from the corresponding -hmac package installed.
  If the library starts up in non-FIPS mode, it checks if the .hmac files 
exist, and if so, it runs through the self-tests as if it operates in FIPS 
mode. This self-test in non-FIPS mode is formally mandatory and comes with
a heavy CPU footprint. You can avoid this overhead by un-installing the 
libopenssl1_0_0-hmac package (with the consequence that FIPS mode of 
operation becomes unavailable).

The openssl library operates in non-FIPS mode by default.

* FIPS-140-2 mode of operation
==============================================================================

The openssl library operates in non-FIPS mode by default.

As noted above (* general information), the .hmac files for the integrity 
self-check of the openssl library are contained in their own package. 
Unfortunately, the self-test is mandatory even if the library runs in 
non-FIPS mode, causing a significant CPU consumption during openssl's 
initialization. You can avoid this overhead by de-installing the -hmac 
package if you do not need FIPS mode of operation.

If you DO need to run binaries that are linked against the openssl 
cryptographic library that runs in FIPS mode, you MUST have the 
libopenssl1_0_0-hmac package installed.

!!! If you enable FIPS mode of operation with the methods below, you MUST 
!!! have the libopenssl1_0_0-hmac package installed. Programs that runtime-link 
!!! against openssl will abort if the FIPS self-tests (including the 
!!! integrity check with the .hmac hashes) fail!

There are three ways to switch the shared libraries listed above to
FIPS-140-2 compliant mode:

1) Start your system with the kernel commandline option "fips=1". To
   change the configuration for your system on a permanent basis, please
   add the command line option to the corresponding line in the bootloader
   configuration, typically /boot/grub/menu.lst .
   You can check if the kernel has accepted the commandline option at boot
   by inspecting the content of the file /proc/sys/crypto/fips_enabled .
     Please note that the fips=1 kernel commandline option switches
   the kernel's crypto API to FIPS mode operation, too. As a consequence,
   some of the in-kernel cryptographical functions may become unavailable.
     As of the writing of this README-FIPS.txt, the kernel's crypto API in
   the SUSE Linux Enterprise Server was NOT FIPS-140-2 validated!

2) set the environment variable OPENSSL_FORCE_FIPS_MODE to "1":

export OPENSSL_FORCE_FIPS_MODE=1

and run your application with this environment variable set.
   The FIPS-140-2 mode of operation is only given in the context of
   processes that have OPENSSL_FORCE_FIPS_MODE set, unless the global
   switch as in 1) above is active.

3) In your program, use the exported function

int FIPS_mode_set(int onoff);

to turn on FIPS-140-2 compliant mode. The library will conduct the
   mandatory self-tests and the integrity check that makes use of the
   .hmac files mentioned above.
   The function

int FIPS_mode(void);

can be used to check if the library operates in FIPS-140-2 compliant
   mode. It returns 1 in FIPS mode, 0 otherwise.

Notes:

- An easy way to verify if your openssl cryptography subsystem operates
  in FIPS-140-2 compliant mode is to look at the output of the

openssl ciphers

command. In FIPS-140-2 compliant mode, the output lists fewer
  algorythms.

- The startup time of programs that initialize the openssl shared libraries
  in FIPS-140-2 compliant mode is considerably longer due to the self-tests
  that are being executed. On fast systems, the startup overhead can be in the 
  range of 0.05-0.3s. The startup time is two orders of a magnitude smaller
  in non-FIPS mode.
  Please note that the self-test overhead only occurs during the 
  initialization of the cryptographic module. There is no other 
  performance impact of FIPS-140-2 compliant operation of the library.

- The environment variable OPENSSL_FIPS can be set to force the 
  /usr/bin/openssl binary to operate in FIPS-140-2 compliant mode:

OPENSSL_FIPS=1 openssl ciphers

The variable OPENSSL_FIPS has an effect on the openssl binary only.

- Services and daemons that make use of the openssl shared libraries in
  FIPS-140-2 compliant mode need to be configured to use algorythms
  from the list of permissable algorythms. If an algorythm is requested
  by an application that is not allowed in FIPS-140-2 compliant mode,
  the application will terminate (abort(3)).
  Please see the FIPS-140-2 Security Policy document for the openssl
  FIPS module on the SUSE Linux Enterprise Server 11 SP1 from the
  SUSE website at http://www.suse.com/ or the NIST website at 
  http://csrc.nist.gov/ for more details.

- If you have any questions about the FIPS-140-2 compliant mode of openssl,
  please send email to security@suse.com.

* overview: openssl subpackages on SLES12
==============================================================================

The openssl package consists of the following RPM package:

openssl

- manual pages
 - the /etc/ssl configuration directory
 - the /usr/bin/openssl program
 - /usr/bin/fips_standalone_hmac, the program used to reproduce
   the integrity HMAC that is contained in the package:

libopenssl1_0_0
 - files:
   /lib64/libcrypto.so.1.0.0
   /lib64/libssl.so.1.0.0
   /lib64/engines
   /lib64/engines/libcapi.so
   /lib64/engines/libgmp.so
   /lib64/engines/libgost.so
   /lib64/engines/libpadlock.so

libopenssl1_0_0-hmac
- files:
   /lib64/.libcrypto.so.1.0.0.hmac
   /lib64/.libssl.so.1.0.0.hmac

libopenssl1_0_0-32bit
 - files as in package libopenssl1_0_0, but in /lib/.
   The .so libraries are for the 32bit compatibility mode of the
   openssl library.

libopenssl1_0_0-hmac-32bit
- files as in package libopenssl1_0_0-hmac, but in /lib/.

libopenssl-devel
 - header files and static libraries for compiling applications with the
   openssl library. Please note that running binaries that are statically
   linked against openssl libraries is not supported in terms of FIPS-140-2
   compliance.

openssl-doc
 - more documentation and manual pages.

openssl-debuginfo
openssl-debugsource
 - packages that provide debugging symbols and debugging source code for
   running binaries (dynamically) linked against libopenssl1_0_0 in a
   debugger.

openssl-certs
 - CA certificate collection in /etc/ssl/certs
   The openssl-certs package is not a subpackage of the openssl package,
   but it merely provides CA certificates where the openssl package
   finds them.