aboutsummaryrefslogtreecommitdiffstats
path: root/lib/crypto/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/crypto/doc')
-rw-r--r--lib/crypto/doc/src/Makefile2
-rw-r--r--lib/crypto/doc/src/crypto.xml43
-rw-r--r--lib/crypto/doc/src/crypto_app.xml24
-rw-r--r--lib/crypto/doc/src/fips.xml211
-rw-r--r--lib/crypto/doc/src/usersguide.xml1
5 files changed, 278 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 b6a1371154..a4b34657ba 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -41,6 +41,9 @@
<p>Hmac functions - <url href="http://www.ietf.org/rfc/rfc2104.txt"> Keyed-Hashing for Message Authentication (RFC 2104) </url></p>
</item>
<item>
+ <p>Cmac functions - <url href="http://www.ietf.org/rfc/rfc4493.txt">The AES-CMAC Algorithm (RFC 4493)</url></p>
+ </item>
+ <item>
<p>Block ciphers - <url href="http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html"> </url> DES and AES in
Block Cipher Modes - <url href="http://csrc.nist.gov/groups/ST/toolkit/BCM/index.html"> ECB, CBC, CFB, OFB, CTR and GCM </url></p>
</item>
@@ -454,6 +457,46 @@
</func>
<func>
+ <name>cmac(Type, Key, Data) -> Mac</name>
+ <name>cmac(Type, Key, Data, MacLength) -> Mac</name>
+ <fsummary>Calculates the Cipher-based Message Authentication Code.</fsummary>
+ <type>
+ <v>Type = block_cipher()</v>
+ <v>Key = iodata()</v>
+ <v>Data = iodata()</v>
+ <v>MacLength = integer()</v>
+ <v>Mac = binary()</v>
+ </type>
+ <desc>
+ <p>Computes a CMAC of type <c>Type</c> from <c>Data</c> using
+ <c>Key</c> as the authentication key.</p> <p><c>MacLength</c>
+ will limit the size of the resultant <c>Mac</c>.</p>
+ </desc>
+ </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..a6ed95bf5e
--- /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>
+ <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>
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>