From cbc937f1c16964669a6d4865aeda2fcdeef9df0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1niel=20Szoboszlay?= Date: Tue, 13 May 2014 10:39:36 +0200 Subject: Document FIPS mode support --- lib/crypto/doc/src/Makefile | 2 +- lib/crypto/doc/src/crypto.xml | 22 ++++ lib/crypto/doc/src/crypto_app.xml | 24 ++++- lib/crypto/doc/src/fips.xml | 211 ++++++++++++++++++++++++++++++++++++++ lib/crypto/doc/src/usersguide.xml | 1 + 5 files changed, 257 insertions(+), 3 deletions(-) create mode 100644 lib/crypto/doc/src/fips.xml (limited to 'lib/crypto') 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 @@ -474,6 +474,28 @@ + + info_fips() -> Status + Provides information about the FIPS operating status. + + Status = enabled | not_enabled | not_supported + + +

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 enabled (when + running in FIPS mode) or not_enabled. For other builds + this value is always not_supported.

+ +

In FIPS mode all non-FIPS compliant algorithms are + disabled and throw exception not_supported. Check + supports that in + FIPS mode returns the restricted list of available + algorithms.

+ + + + info_lib() -> [{Name,VerNum,VerStr}] Provides information about the libraries used by crypto. 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,13 +41,33 @@
DEPENDENCIES -

The current crypto implementation uses nifs to interface OpenSSLs crypto library - and requires OpenSSL package version 0.9.8 or higher.

+

The current crypto implementation uses nifs to interface + OpenSSLs crypto library and requires OpenSSL package + version 0.9.8 or higher. FIPS mode support requires at least + version 1.0.1 and a FIPS capable OpenSSL installation.

+

Source releases of OpenSSL can be downloaded from the OpenSSL project home page, or mirror sites listed there.

+
+ CONFIGURATION +

The following configuration parameters are defined for the + crypto application. See app(3) for more information about + configuration parameters.

+ + fips_mode = boolean() + +

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.

+ + +
+
SEE ALSO

application(3)

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 @@ + + + + +
+ + 2014 + Ericsson AB. All Rights Reserved. + + + 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. + + + + FIPS mode + Dániel Szoboszlay + + 2014-05-12 + A + fips.xml +
+

+ + This chapter describes FIPS mode support in the crypto application. +

+ +
+ Background +

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.

+

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.

+
+ +
+ Enabling FIPS mode + + +

Build or install the FIPS Object Module and a FIPS enabled + OpenSSL library.

+

You should read and precisely follow the instructions of + the Security + Policy and User + Guide.

+

It is very easy to build a working OpenSSL FIPS + Object Module and library from the source. However it does + not qualify as FIPS 140-2 validated if the numerous + restrictions in the Security Policy are not properly + followed.

 + + +

Configure and build Erlang/OTP with FIPS support:

+ 
+$ cd $ERL_TOP
+$ ./otp_build configure --enable-fips
+...
+checking for FIPS_mode_set... yes
+...
+$ make
+
+

If FIPS_mode_set returns no the OpenSSL + library is not FIPS enabled and crypto won't support FIPS mode + either.

+ + +

Set the fips_mode configuration setting of the + crypto application to true before loading the + crypto module.

+

The best place is in the sys.config system + configuration file of the release.

+ + + Start and use the crypto application as usual. However take + care to avoid the non-FIPS validated algorithms, they will all + throw exception not_supported. + + +

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.

+

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.

+
+ +
+ Incompatibilities with regular builds +

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.

+

This means that the context (an opaque type) returned from + streaming crypto functions (hash_(init|update|final), + hmac_(init|update|final) and + stream_(init|encrypt|decrypt)) is different and + incompatible with regular builds when compiling crypto with FIPS + support.

+
+ +
+ Common caveats +

In FIPS mode non-validated algorithms are disabled. This may + cause some unexpected problems in application relying on + crypto.

+

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.

 + +
+ Restrictions on key sizes +

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: +

+ + RSA1024 bit + DSS1024 bit + EC algorithms160 bit + +
+ +
+ Restrictions on elliptic curves +

The Erlang API allows using arbitrary curve parameters, but + in FIPS mode only those allowed by the Security Policy shall be + used.

+
+ +
+ Avoid md5 for hashing +

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.

+

For exceptional, non-cryptographic use cases one may consider + switching to erlang:md5/1 as well.

+
+ +
+ Certificates and encrypted keys +

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.

+

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.

+
+ +
+ SNMP v3 limitations +

It is only possible to use usmHMACSHAAuthProtocol and + usmAesCfb128Protocol 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.

+
+ +
+ TLS 1.2 is required +

All SSL and TLS versions prior to TLS 1.2 use a combination + of md5 and sha1 hashes in the handshake for various purposes:

+ + Authenticating the integrity of the handshake + messages. + In the exchange of DH parameters in cipher suites + providing non-anonymous PFS (perfect forward secrecy). + In the PRF (pseud-random function) to generate keying + materials in cipher suites not using PFS. + +

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.

+

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.

+

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.

 +
+ +
+ 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 @@

+ -- cgit v1.2.3