FIPS doc page updated

Author: kvakvs

lib/crypto/doc/guides/fips.md

@@ -38,39 +38,69 @@ Erlang code (like SRP) are disabled.
 
 ## Enabling FIPS mode
 
-1. 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](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf)
-and [User Guide](https://www.openssl.org/docs/fips/UserGuide-2.0.pdf).
-
 > #### Warning {: .warning }
 >
 > 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.
+> the source, all OpenSSL versions support FIPS. However any version _does not_ 
+> qualify as FIPS 140-2 or FIPS 140-3 validated if the numerous restrictions in
+> the Security Policy are not properly followed, the version also must be listed
+> on the NIST website as validated.
+
+### Build FIPS-enabled OpenSSL
+
+For a proper FIPS-compliant build you should read and precisely follow the instructions 
+of the [Security Policy 140-2](https://csrc.nist.gov/pubs/fips/140-2/upd2/final)
+superceded by [Security Policy 140-3](https://csrc.nist.gov/pubs/fips/140-3/final)
+and [User Guide](https://docs.openssl.org/),
+but to get quick results which allow you to continue development, read on...
+
+Build is performed in 2 steps (for Windows follow the steps in `NOTES-WINDOWS.md`):
+1. Define, where you will put the compiled OpenSSL files, this will be your `SSLDIR`.
+   ```bash
+   export SSLDIR=...
+   ```
+2. Configure the library. Run once (requires Perl):
+   ```bash
+   export OPENSSL_CONF=${SSLDIR}/openssl.cnf
+   ./Configure shared enable-fips --prefix=${SSLDIR} --openssldir=${SSLDIR}
+   ```
+3. Build the library
+   ```bash
+   make -j && make install install_fips
+   ```
+
+### Configuring OpenSSL for FIPS
+
+Now that the `make install` has finished and the `${SSLDIR}` contains your ready 
+to use copy of OpenSSL, it is time to configure it for FIPS mode.
+
+1. Edit the `openssl.cnf`
+    1. Find `.include fipsmodule.cnf` and edit it to include the full path to the `.cnf` file. 
+    2. Find `fips = fips_sect` and uncomment
+2. Inside `${SSLDIR}` copy or link two files found `lib/ossl-modules/` 
+   (`fips.so` or `fips.dylib`, and `legacy.so` or `legacy.dylib`) to be found in `${SSLDIR}/lib`. 
+3. You can verify that OpenSSL was configured correctly by invoking it from `${SSLDIR}`:
+   ```bash
+   bin/openssl list -providers
+   ```
+   You should expect to see both `default` and `fips` providers, both having
+   `status: active`. The `default` can be disabled in `openssl.cnf` in the
+   `[default]` section.
+
+### Building Erlang with FIPS
 
 1. Configure and build Erlang/OTP with FIPS support:
-
-```text
-$ 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.
-
-1. 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.
-
-1. 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`.
+   ```bash
+   export ERL_TOP=`pwd` # where your Erlang source is located
+   ./otp_build setup -a --enable-fips --with-ssl=${SSLDIR}
+   ```
+2. Set the `fips_mode` configuration setting of the `crypto` application to `true`
+   _before starting the `crypto` application_.
+   The best place to do so is in the `sys.config` system configuration file of the release, 
+   but for development you can create your own `fips.config` file and provide it to Erlang.
+3. Start and use the crypto application as usual. However any attempt to use
+   non-FIPS validated algorithms will end with a `not_supported` exception.
+4. Verify that FIPS was enabled by calling `crypto:info_fips()` and `crypto:supports()`.
 
 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
@@ -125,7 +155,7 @@ 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
+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