diff options
Diffstat (limited to 'lib/crypto/doc')
| -rw-r--r-- | lib/crypto/doc/src/Makefile | 2 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 43 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto_app.xml | 24 | ||||
| -rw-r--r-- | lib/crypto/doc/src/fips.xml | 211 | ||||
| -rw-r--r-- | lib/crypto/doc/src/usersguide.xml | 1 |
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 eda0f7af51..cbf141b3b0 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á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> |