diff options
Diffstat (limited to 'lib/crypto/doc/src/fips.xml')
| -rw-r--r-- | lib/crypto/doc/src/fips.xml | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/lib/crypto/doc/src/fips.xml b/lib/crypto/doc/src/fips.xml new file mode 100644 index 0000000000..3e5c2db1e0 --- /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><year>2017</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á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> + <warning><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></warning> + + <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> |