diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 04f0e0d05..353464f3e 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9e3b5505..afc6d932b 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/test/openssl/fixtures/ssl/openssl_fips.cnf.tmpl b/tool/openssl_fips.cnf.tmpl similarity index 100% rename from test/openssl/fixtures/ssl/openssl_fips.cnf.tmpl rename to tool/openssl_fips.cnf.tmpl