Document FIPS mode support

5 files changed, 257 insertions, 3 deletions

diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
index e55242d255..9c503b8fe0 100644
--- a/lib/crypto/doc/src/Makefile
+++ b/lib/crypto/doc/src/Makefile
@@ -39,7 +39,7 @@ XML_REF3_FILES = crypto.xml
 XML_REF6_FILES = crypto_app.xml
 
 XML_PART_FILES = release_notes.xml usersguide.xml
-XML_CHAPTER_FILES = notes.xml licenses.xml
+XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml
 
 BOOK_FILES = book.xml
 
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index ce8bf2216a..cbf141b3b0 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -475,6 +475,28 @@
     </func>
 
     <func>
+      <name>info_fips() -> Status</name>
+      <fsummary>Provides information about the FIPS operating status.</fsummary>
+      <type>
+        <v>Status = enabled | not_enabled | not_supported</v>
+      </type>
+      <desc>
+        <p>Provides information about the FIPS operating status of
+        crypto and the underlying OpenSSL library. If crypto was built
+        with FIPS support this can be either <c>enabled</c> (when
+        running in FIPS mode) or <c>not_enabled</c>. For other builds
+        this value is always <c>not_supported</c>.</p>
+        <warning>
+          <p>In FIPS mode all non-FIPS compliant algorithms are
+          disabled and throw exception <c>not_supported</c>. Check
+          <seealso marker="#supports-0">supports</seealso> that in
+          FIPS mode returns the restricted list of available
+          algorithms.</p>
+        </warning>
+      </desc>
+    </func>
+
+    <func>
       <name>info_lib() -> [{Name,VerNum,VerStr}]</name>
       <fsummary>Provides information about the libraries used by crypto.</fsummary>
       <type>
diff --git a/lib/crypto/doc/src/crypto_app.xml b/lib/crypto/doc/src/crypto_app.xml
index 2b9e505988..a958bdfcb7 100644
--- a/lib/crypto/doc/src/crypto_app.xml
+++ b/lib/crypto/doc/src/crypto_app.xml
@@ -41,14 +41,34 @@
   <section>
     <title>DEPENDENCIES</title>
 
-    <p>The current crypto implementation uses nifs to interface OpenSSLs crypto library
-    and requires <em>OpenSSL</em> package version 0.9.8 or higher.</p>
+    <p>The current crypto implementation uses nifs to interface
+    OpenSSLs crypto library and requires <em>OpenSSL</em> package
+    version 0.9.8 or higher. FIPS mode support requires at least
+    version 1.0.1 and a FIPS capable OpenSSL installation.</p>
+
     <p>Source releases of OpenSSL can be downloaded from the <url href="http://www.openssl.org">OpenSSL</url> project home page,
     or mirror sites listed there.
     </p>
     </section>
 
   <section>
+    <title>CONFIGURATION</title>
+    <p>The following configuration parameters are defined for the
+    crypto application. See <c>app(3)</c> for more information about
+    configuration parameters.</p>
+    <taglist>
+      <tag><c>fips_mode = boolean()</c></tag>
+      <item>
+        <p>Specifies whether to run crypto in FIPS mode. This setting
+        will take effect when the nif module is loaded. If FIPS mode
+        is requested but not available at run time the nif module and
+        thus the crypto module will fail to load. This mechanism
+        prevents the accidental use of non-validated algorithms.</p>
+      </item>
+    </taglist>
+  </section>
+
+  <section>
     <title>SEE ALSO</title>
     <p>application(3)</p>
   </section>
diff --git a/lib/crypto/doc/src/fips.xml b/lib/crypto/doc/src/fips.xml
new file mode 100644
index 0000000000..243f0da031
--- /dev/null
+++ b/lib/crypto/doc/src/fips.xml
@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2014</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>FIPS mode</title>
+    <prepared>D&aacute;niel Szoboszlay</prepared>
+    <docno></docno>
+    <date>2014-05-12</date>
+    <rev>A</rev>
+    <file>fips.xml</file>
+  </header>
+  <p>
+    <marker id="fips"></marker>
+    This chapter describes FIPS mode support in the crypto application.
+  </p>
+
+  <section>
+    <title>Background</title>
+    <p>OpenSSL can be built to provide FIPS 140-2 validated
+    cryptographic services. It is not the OpenSSL application that is
+    validated, but a special software component called the OpenSSL
+    FIPS Object Module. However applications do not use this Object
+    Module directly, but through the regular API of the OpenSSL
+    library.</p>
+    <p>The crypto application supports using OpenSSL in FIPS mode. In
+    this scenario only the validated algorithms provided by the Object
+    Module are accessible, other algorithms usually available in
+    OpenSSL (like md5) or implemented in the Erlang code (like SRP)
+    are disabled.</p>
+  </section>
+
+  <section>
+    <title>Enabling FIPS mode</title>
+    <list type="ordered">
+      <item>
+        <p>Build or install the FIPS Object Module and a FIPS enabled
+        OpenSSL library.</p>
+        <p>You should read and precisely follow the instructions of
+        the <url
+        href="http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf">Security
+        Policy</url> and <url
+        href="https://www.openssl.org/docs/fips/UserGuide-2.0.pdf">User
+        Guide</url>.</p>
+        <warning><p>It is very easy to build a working OpenSSL FIPS
+        Object Module and library from the source. However it <em>does
+        not</em> qualify as FIPS 140-2 validated if the numerous
+        restrictions in the Security Policy are not properly
+        followed.</p></warning>
+      </item>
+      <item>
+        <p>Configure and build Erlang/OTP with FIPS support:</p>
+        <pre>
+$ <input>cd $ERL_TOP</input>
+$ <input>./otp_build configure --enable-fips</input>
+...
+checking for FIPS_mode_set... yes
+...
+$ <input>make</input>
+        </pre>
+        <p>If <c>FIPS_mode_set</c> returns <c>no</c> the OpenSSL
+        library is not FIPS enabled and crypto won't support FIPS mode
+        either.</p>
+      </item>
+      <item>
+        <p>Set the <c>fips_mode</c> configuration setting of the
+        crypto application to <c>true</c> <em>before loading the
+        crypto module</em>.</p>
+        <p>The best place is in the <c>sys.config</c> system
+        configuration file of the release.</p>
+      </item>
+      <item>
+        Start and use the crypto application as usual. However take
+        care to avoid the non-FIPS validated algorithms, they will all
+        throw exception <c>not_supported</c>.
+      </item>
+    </list>
+    <p>Entering and leaving FIPS mode on a node already running crypto
+    is not supported. The reason is that OpenSSL is designed to
+    prevent an application requesting FIPS mode to end up accidentally
+    running in non-FIPS mode. If entering FIPS mode fails (e.g. the
+    Object Module is not found or is compromised) any subsequent use
+    of the OpenSSL API would terminate the emulator.</p>
+    <p>An on-the-fly FIPS mode change would thus have to be performed
+    in a critical section protected from any concurrently running
+    crypto operations. Furthermore in case of failure all crypto calls
+    would have to be disabled from the Erlang or nif code. This would
+    be too much effort put into this not too important feature.</p>
+  </section>
+
+  <section>
+    <title>Incompatibilities with regular builds</title>
+    <p>The Erlang API of the crypto application is identical
+    regardless of building with or without FIPS support. However the
+    nif code internally uses a different OpenSSL API.</p>
+    <p>This means that the context (an opaque type) returned from
+    streaming crypto functions (<c>hash_(init|update|final)</c>,
+    <c>hmac_(init|update|final)</c> and
+    <c>stream_(init|encrypt|decrypt)</c>) is different and
+    incompatible with regular builds when compiling crypto with FIPS
+    support.</p>
+  </section>
+
+  <section>
+    <title>Common caveats</title>
+    <p>In FIPS mode non-validated algorithms are disabled. This may
+    cause some unexpected problems in application relying on
+    crypto.</p>
+    <warn><p>Do not try to work around these problems by using
+    alternative implementations of the missing algorithms! An
+    application can only claim to be using a FIPS 140-2 validated
+    cryptographic module if it uses it exclusively for every
+    cryptographic operation.</p></warn>
+
+    <section>
+      <title>Restrictions on key sizes</title>
+      <p>Although public key algorithms are supported in FIPS mode
+      they can only be used with secure key sizes. The Security Policy
+      requires the following minimum values:
+      </p>
+      <taglist>
+        <tag>RSA</tag><item>1024 bit</item>
+        <tag>DSS</tag><item>1024 bit</item>
+        <tag>EC algorithms</tag><item>160 bit</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>Restrictions on elliptic curves</title>
+      <p>The Erlang API allows using arbitrary curve parameters, but
+      in FIPS mode only those allowed by the Security Policy shall be
+      used.</p>
+    </section>
+
+    <section>
+      <title>Avoid md5 for hashing</title>
+      <p>Md5 is a popular choice as a hash function, but it is not
+      secure enough to be validated. Try to use sha instead wherever
+      possible.</p>
+      <p>For exceptional, non-cryptographic use cases one may consider
+      switching to <c>erlang:md5/1</c> as well.</p>
+    </section>
+
+    <section>
+      <title>Certificates and encrypted keys</title>
+      <p>As md5 is not available in FIPS mode it is only possible to
+      use certificates that were signed using sha hashing. When
+      validating an entire certificate chain all certificates
+      (including the root CA's) must comply with this rule.</p>
+      <p>For similar dependency on the md5 and des algorithms most
+      encrypted private keys in PEM format do not work
+      either. However, the PBES2 encryption scheme allows the use of
+      stronger FIPS verified algorithms which is a viable
+      alternative.</p>
+    </section>
+
+    <section>
+      <title>SNMP v3 limitations</title>
+      <p>It is only possible to use <c>usmHMACSHAAuthProtocol</c> and
+      <c>usmAesCfb128Protocol</c> for authentication and privacy
+      respectively in FIPS mode. The snmp application however won't
+      restrict selecting disabled protocols in any way, and using them
+      would result in run time crashes.</p>
+    </section>
+
+    <section>
+      <title>TLS 1.2 is required</title>
+      <p>All SSL and TLS versions prior to TLS 1.2 use a combination
+      of md5 and sha1 hashes in the handshake for various purposes:</p>
+      <list>
+        <item>Authenticating the integrity of the handshake
+        messages.</item>
+        <item>In the exchange of DH parameters in cipher suites
+        providing non-anonymous PFS (perfect forward secrecy).</item>
+        <item>In the PRF (pseud-random function) to generate keying
+        materials in cipher suites not using PFS.</item>
+      </list>
+      <p>OpenSSL handles these corner cases in FIPS mode, however the
+      Erlang crypto and ssl applications are not prepared for them and
+      therefore you are limited to TLS 1.2 in FIPS mode.</p>
+      <p>On the other hand it worth mentioning that at least all
+      cipher suites that would rely on non-validated algorithms are
+      automatically disabled in FIPS mode.</p>
+      <note><p>Certificates using weak (md5) digests may also cause
+      problems in TLS. Although TLS 1.2 has an extension for
+      specifying which type of signatures are accepted, and in FIPS
+      mode the ssl application will use it properly, most TLS
+      implementations ignore this extension and simply send whatever
+      certificates they were configured with.</p></note>
+    </section>
+
+  </section>
+</chapter>
diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml
index fb088a8285..7971aefff4 100644
--- a/lib/crypto/doc/src/usersguide.xml
+++ b/lib/crypto/doc/src/usersguide.xml
@@ -47,5 +47,6 @@
       </p>
   </description>
   <xi:include href="licenses.xml"/>
+  <xi:include href="fips.xml"/>
 </part>