Merge pull request ruby#688 from junaruga/wip/doc-contributing

CONTRIBUTING.md: Update testing with debugging and FIPS use cases. [ci skip]

.github/workflows/test.yml

@@ -140,12 +140,11 @@ jobs:
       - name: set the open installed directory
         run: >
           sed -e "s|OPENSSL_DIR|$HOME/.openssl/${{ matrix.openssl }}|"
-          test/openssl/fixtures/ssl/openssl_fips.cnf.tmpl >
-          test/openssl/fixtures/ssl/openssl_fips.cnf
+          tool/openssl_fips.cnf.tmpl > tmp/openssl_fips.cnf
         if: matrix.fips-enabled
 
       - name: set openssl config file path for fips.
-        run: echo "OPENSSL_CONF=$(pwd)/test/openssl/fixtures/ssl/openssl_fips.cnf" >> $GITHUB_ENV
+        run: echo "OPENSSL_CONF=$(pwd)/tmp/openssl_fips.cnf" >> $GITHUB_ENV
         if: matrix.fips-enabled
 
       - name: load ruby

CONTRIBUTING.md

@@ -54,27 +54,179 @@ $ bundle exec rake test
 
 ### With different versions of OpenSSL
 
-Ruby OpenSSL supports various versions of OpenSSL library. The test suite needs
-to pass on all supported combinations.
+Ruby OpenSSL supports various versions of the OpenSSL library. The test suite
+needs to pass on all supported combinations.
 
-Similarly to when installing `openssl` gem via the `gem` command,
-you can pass a `--with-openssl-dir` argument to `rake compile`
-to specify the OpenSSL library to build against.
+If you want to test, debug, report an issue, or contribute to the Ruby OpenSSL
+or [the OpenSSL project](https://www.openssl.org/) in the non-FIPS or
+the [FIPS](https://github.com/openssl/openssl/blob/master/README-FIPS.md) case,
+compiling OpenSSL from the source by yourself is a good practice.
 
+The following steps are tested in Linux and GCC environment. You can adjust the
+commands in the steps for a different environment.
+
+To download the OpenSSL source from the Git repository, you can run the following
+commands:
+
+```
+$ git clone https://github.com/openssl/openssl.git
+$ cd openssl
+```
+
+You see the `master` branch used as a development branch. Testing against the
+latest OpenSSL master branch is a good practice to report an issue to the
+OpenSSL project.
+
+```
+$ git branch | grep '^*'
+* master
+```
+
+If you test against the latest stable branch, you can run the following command.
+In this example, the `openssl-3.1` branch is the stable branch of OpenSSL 3.1
+series.
+
+```
+$ git checkout openssl-3.1
+```
+
+To configure OpenSSL, you can run the following commands.
+
+In this example, we use the `OPENSSL_DIR` environment variable to specify the
+OpenSSL installed directory for convenience. Including the commit hash in the
+directory name is a good practice.
+
+```
+$ git rev-parse --short HEAD
+0bf18140f4
+
+$ OPENSSL_DIR=$HOME/.openssl/openssl-fips-debug-0bf18140f4
+```
+
+The following configuration options are useful in this case.
+You can check
+[OpenSSL installation document](https://github.com/openssl/openssl/blob/master/INSTALL.md)
+for details.
+
+* `enable-fips`: Add an option to run with the OpenSSL FIPS module.
+* `enable-trace`: Add an option to enabling tracing log. You can trace logs by
+  implementing a code. See the man page
+  [OSSL_TRACE(3)](https://www.openssl.org/docs/man3.0/man3/OSSL_TRACE.html) for
+  details.
+* compiler flags
+  * `-Wl,-rpath,$(LIBRPATH)`: Set the runtime shared library path to run the
+    `openssl` command without the `LD_LIBRARY_PATH`. You can check
+    [this document](https://github.com/openssl/openssl/blob/master/NOTES-UNIX.md)
+    for details.
+  * `-O0 -g3 -ggdb3 -gdwarf-5`: You can set debugging compiler flags.
+
+```
+$ ./Configure \
+  --prefix=$OPENSSL_DIR \
+  --libdir=lib \
+  enable-fips \
+  enable-trace \
+  '-Wl,-rpath,$(LIBRPATH)' \
+  -O0 -g3 -ggdb3 -gdwarf-5
+$ make -j4
+$ make install
 ```
-$ ( curl -OL https://ftp.openssl.org/source/openssl-3.0.1.tar.gz &&
-    tar xf openssl-3.0.1.tar.gz &&
-    cd openssl-3.0.1 &&
-    ./config --prefix=$HOME/.openssl/openssl-3.0.1 --libdir=lib &&
-    make -j4 &&
-    make install )
 
-$ # in Ruby/OpenSSL's source directory
+To print installed OpenSSL version, you can run the following command:
+
+```
+$ $OPENSSL_DIR/bin/openssl version
+OpenSSL 3.2.0-alpha3-dev  (Library: OpenSSL 3.2.0-alpha3-dev )
+```
+
+Change the current working directory into Ruby OpenSSL's source directory.
+
+To compile Ruby OpenSSL, you can run the following commands:
+
+Similarly to when installing `openssl` gem via the `gem` command, you can pass a
+`--with-openssl-dir` argument to `rake compile` to specify the OpenSSL library
+ to build against.
+
+* `MAKEFLAGS="V=1"`: Enable the compiler command lines to print in
+  the log.
+* `RUBY_OPENSSL_EXTCFLAGS`: Set extra compiler flags to compile Ruby OpenSSL.
+
+```
 $ bundle exec rake clean
-$ bundle exec rake compile -- --with-openssl-dir=$HOME/.openssl/openssl-3.0.1
+$ MAKEFLAGS="V=1" \
+  RUBY_OPENSSL_EXTCFLAGS="-O0 -g3 -ggdb3 -gdwarf-5" \
+  bundle exec rake compile -- --with-openssl-dir=$OPENSSL_DIR
+```
+
+#### Testing normally in non-FIPS case
+
+To test Ruby OpenSSL, you can run the following command:
+
+```
 $ bundle exec rake test
 ```
 
+#### Testing in FIPS case
+
+To use OpenSSL 3.0 or later versions in a FIPS-approved manner, you must load the
+`fips` and `base` providers, and also use the property query `fips=yes`. The
+property query is used when fetching cryptographic algorithm implementations.
+This must be done at the startup of a process to avoid implicitly loading the
+`default` provider which has the non-FIPS cryptographic algorithm
+implementations. See also the man page
+[fips_module(7)](https://www.openssl.org/docs/manmaster/man7/fips_module.html).
+
+You can set this in your OpenSSL configuration file by either appropriately
+modifying the default OpenSSL configuration file located at
+`OpenSSL::Config::DEFAULT_CONFIG_FILE` or temporarily overriding it with the
+`OPENSSL_CONF` environment variable.
+
+In this example, we explain on the latter way.
+
+You can create a OpenSSL FIPS config `openssl_fips.cnf` file based on the
+`openssl_fips.cnf.tmpl` file in this repository, and replacing the placeholder
+`OPENSSL_DIR` with your OpenSSL installed directory.
+
+```
+$ sed -e "s|OPENSSL_DIR|$OPENSSL_DIR|" tool/openssl_fips.cnf.tmpl | \
+  tee $OPENSSL_DIR/ssl/openssl_fips.cnf
+```
+
+You can see the base and fips providers by running the following command if you
+setup the OpenSSL FIPS config file properly.
+
+```
+$ OPENSSL_CONF=$OPENSSL_DIR/ssl/openssl_fips.cnf \
+  $OPENSSL_DIR/bin/openssl list -providers
+Providers:
+  base
+    name: OpenSSL Base Provider
+    version: 3.2.0
+    status: active
+  fips
+    name: OpenSSL FIPS Provider
+    version: 3.2.0
+    status: active
+```
+
+You can run the current tests in the FIPS module case used in the GitHub
+Actions file `test.yml` explained in a later sentence.
+
+```
+$ OPENSSL_CONF=$OPENSSL_DIR/ssl/openssl_fips.cnf \
+  bundle exec rake test_fips
+```
+
+You can also run the all the tests in the FIPS module case. You see many
+failures. We are working in progress to fix the failures. Your contribution is
+welcome.
+
+```
+$ OPENSSL_CONF=$OPENSSL_DIR/ssl/openssl_fips.cnf \
+  TEST_RUBY_OPENSSL_FIPS_ENABLED=true \
+  bundle exec rake test
+```
+
 The GitHub Actions workflow file
 [`test.yml`](https://github.com/ruby/openssl/tree/master/.github/workflows/test.yml)
 contains useful information for building OpenSSL/LibreSSL and testing against