[couchdb-documentation] 05/18: Add troubleshooting information for FIPS mode and workaround (#1171)

[wo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch 2.2.0-release-notes
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 2e555aff9c49508581806a1ec002c40132a8ffce
Author: rokek <82...@users.noreply.github.com>
AuthorDate: Mon Jul 16 16:37:02 2018 -0400

    Add troubleshooting information for FIPS mode and workaround (#1171)
    
    Fix formatting for troubleshooting FIPS mode error
    
    Fix formatting for troubleshooting FIPS mode error
    
    Fix formatting for troubleshooting FIPS mode error
    
    Fix formatting for troubleshooting FIPS mode error
    
    Fix formatting for troubleshooting FIPS mode error
---
 src/install/troubleshooting.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/install/troubleshooting.rst b/src/install/troubleshooting.rst
index 408d607..5d17dd4 100644
--- a/src/install/troubleshooting.rst
+++ b/src/install/troubleshooting.rst
@@ -276,6 +276,33 @@ the relevant CouchDB and then compact prior to replicating.
 Alternatively, if the number of documents impacted is small, use filtered
 replication to exclude only those documents.
 
+FIPS mode
+---------
+
+Operating systems can be configured to disallow the use of OpenSSL MD5 hash 
+functions in order to prevent use of MD5 for cryptographic purposes. CouchDB 
+makes use of MD5 hashes for verifying the integrity of data (and not for 
+cryptography) and will not run without the ability to use MD5 hashes.
+
+The message below indicates that the operating system is running in "FIPS mode," 
+which among other restrictions does not allow the use of OpenSSL's MD5 funtions:
+
+.. code-block:: text
+
+    md5_dgst.c(82): OpenSSL internal error, assertion failed: Digest MD5 forbidden in FIPS mode!
+    [os_mon] memory supervisor port (memsup): Erlang has closed
+    [os_mon] cpu supervisor port (cpu_sup): Erlang has closed
+    Aborted
+
+A workaround for this is provided with the ``--erlang-md5`` compile flag. Use of 
+the flag results in CouchDB substituting the OpenSSL MD5 function calls with 
+equivalent calls to Erlang's built-in library ``erlang:md5.`` NOTE: there may be
+a performance penalty associated with this workaround.
+
+Because CouchDB does not make use of MD5 hashes for cryptographic purposes, this 
+workaround does not defeat the purpose of "FIPS mode," provided that the system 
+owner is aware of and consents to its use.
+
 macOS Known Issues
 ====================
 undefined error, exit_status 134