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

[va...@apache.org]

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

vatamane pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 221446968f2c279b95f6884c322ce05180c8430e
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