doc: provided basic documentation of the FIPS140-2 mode [ci skip]

Resolves #332

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

3 files changed, 41 insertions, 4 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 3dda329e7a..99bda239b8 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -205,7 +205,7 @@ CPU. The currently available options are:
 @end itemize
 
 @item @code{GNUTLS_FORCE_FIPS_MODE}
-@tab In setups where GnuTLS is compiled with support for FIPS140-2 (see --enable-fips140-mode in configure), that option if set to one enforces the FIPS140 mode.
+@tab In setups where GnuTLS is compiled with support for FIPS140-2 (see @ref{FIPS140-2 mode}).
 
 @end multitable
 @caption{Environment variables used by the library.}
diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
index 4cb3364d8c..9c74a24114 100644
--- a/doc/cha-internals.texi
+++ b/doc/cha-internals.texi
@@ -14,6 +14,7 @@ happens inside the black box.
 * TLS Extension Handling::
 * Cryptographic Backend::
 * Random Number Generators-internals::
+* FIPS140-2 mode::
 @end menu
 
 @node The TLS Protocol
@@ -661,3 +662,40 @@ two distinct times, and being able to recover the state at the third time
 after observing the output of the PRNG. Given the approach described
 on the above paragraph, all levels are immune to such attack.
 
+@node FIPS140-2 mode
+@section FIPS140-2 mode
+
+GnuTLS can operate in a special mode for FIPS140-2. That mode of operation
+is for the conformance to NIST's FIPS140-2 publication, which consists of policies
+for cryptographic modules (such as software libraries). Its implementation in
+GnuTLS is designed for Red Hat Enterprise Linux, and can only be enabled
+when the library is explicitly compiled with the '--enable-fips140-mode'
+configure option. The operation of the library is then modified, as follows.
+
+@itemize
+@item FIPS140-2 mode is enabled when @code{/proc/sys/crypto/fips_enabled} contains '1' and @code{/etc/system-fips} is present.
+@item Only approved by FIPS140-2 algorithms are enabled
+@item Only approved by FIPS140-2 key lengths are allowed for key generation
+@item The random generator used switches to DRBG-AES
+@item The integrity of the GnuTLS and dependent libraries is checked on startup
+@item Algorithm self-tests are run on library load
+@item Any cryptographic operation will be refused if any of the self-tests failed
+@end itemize
+
+There is a 'zombie' FIPS140-2 mode which is enabled when only one of the files
+described in the first step is available. In that case the self tests will
+be performed without affecting the operation of the library.
+
+The integrity checks for the dependent libraries and GnuTLS are performed
+using '.hmac' files which are present at the same path as the library. The
+key for the operations can be provided on compile-time with the configure
+option '--with-fips140-key'. The MAC algorithm used is HMAC-SHA256.
+
+There are also few environment variables which modify that operation. The
+environment variable @code{GNUTLS_SKIP_FIPS_INTEGRITY_CHECKS} will disable
+the library integrity tests on startup, and the variable
+@code{GNUTLS_FORCE_FIPS_MODE} when set to '1' will enable the FIPS140-2
+mode, when set to '0' will force a disable of it.
+
+On runtime an application can verify whether the library is in FIPS140-2
+using the @funcref{gnutls_fips140_mode_enabled} function.
diff --git a/doc/cha-support.texi b/doc/cha-support.texi
index aecd0f7df9..9ae104f641 100644
--- a/doc/cha-support.texi
+++ b/doc/cha-support.texi
@@ -138,6 +138,5 @@ specific product using the library, and typically in the case of software they a
 @item Common Criteria for Information Technology Security Evaluation (CC), an international standard for verification of elaborate security claims (see @url{http://en.wikipedia.org/wiki/Common_Criteria}).
 @end itemize
 
-Obtaining such a certification is an expensive and elaborate job that has no immediate value for a continuously developed free software library (as the certification is tied to the
-particular version tested). While, as a free software project, we are not actively pursuing this kind of certification, GnuTLS has been FIPS-140-2 certified in several systems by
-third parties. If you are, interested, see @ref{Commercial Support}.
+GnuTLS has support for FIPS 140-2 under Red Hat Enterprise Linux.
+See @ref{FIPS140-2 mode} for more information.