# Ruby and OpenSSL FIPS This document is related to the issue ticket is [Being a co-maintainer of the ruby/openssl for the OpenSSL FIPS mode](https://bugs.ruby-lang.org/issues/19608). See also "What is FIPS". ## How to debug with OpenSSL 3 FIPS Below are the steps to debug Ruby OpenSSL binding (ruby/openssl) with OpenSSL 3 with FIPS enabled. ### Install OpenSSL from the source Build and install OpenSSL from the source with the FIPS option. See [the official configuration options document](https://github.com/openssl/openssl/blob/master/INSTALL.md#configuration-options) for details. * `--libdir=lib`: This option changes the default library directory name "lib64" in x86_64 to "lib". It's useful when you access from the Ruby OpenSSL binding. Because the `mkmf#dir_config` executed by `--with-openssl-dir=<path>` in the later step below expects the "lib" as a default. See [the code](https://github.com/ruby/ruby/blob/v3_2_2/lib/mkmf.rb#L1813). * `enable-fips`: Enabling FIPS * `enable-trace`: Enabling tracing option. You can trace logs in a specific category. See the [example](https://github.com/junaruga/openssl-test/blob/main/trace.c). It's helpful to debug. * `-O0 -g3 -ggdb3 -gdwarf-5`: debugging flags for GCC ``` $ git clone https://github.com/openssl/openssl.git $ cd openssl $ git checkout openssl-3.0.8 $ ./Configure \ --prefix=${HOME}/.local/openssl-3.0.8-fips-debug \ --libdir=lib \ shared \ enable-fips \ enable-trace \ -O0 -g3 -ggdb3 -gdwarf-5 $ make -j$(nproc) $ make install $ LD_LIBRARY_PATH=${HOME}/.local/openssl-3.0.8-fips-debug/lib/ \ ${HOME}/.local/openssl-3.0.8-fips-debug/bin/openssl version -a OpenSSL 3.0.8 7 Feb 2023 (Library: OpenSSL 3.0.8 7 Feb 2023) built on: Tue Apr 25 14:23:34 2023 UTC platform: linux-x86_64 options: bn(64,64) compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -Wall -O3 -O0 -g3 -ggdb3 -gdwarf-5 -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_BUILDING_OPENSSL -DNDEBUG OPENSSLDIR: "/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl" ENGINESDIR: "/home/jaruga/.local/openssl-3.0.8-fips-debug/lib/engines-3" MODULESDIR: "/home/jaruga/.local/openssl-3.0.8-fips-debug/lib/ossl-modules" Seeding source: os-specific CPUINFO: OPENSSL_ia32cap=0x7ffaf3ffffebffff:0x29c67af ``` ### Test OpenSSL FIPS with a testing program written in C language The program is <https://github.com/junaruga/openssl-test>. You can see how to use the program and test it to check if the used OpenSSL is FIPS or not. The FIPS needs to set the "fips" provider and `default_properties = fips=yes`. Prepare a config file to run OpenSSL with FIPS. ``` $ cat ${HOME}/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf config_diagnostics = 1 openssl_conf = openssl_init # Need to set the absolute path of the fipsmodule.cnf. # https://github.com/openssl/openssl/issues/17704 .include /home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/fipsmodule.cnf #.include fipsmodule.cnf [openssl_init] providers = provider_sect alg_section = algorithm_sect [provider_sect] fips = fips_sect base = base_sect [base_sect] activate = 1 [algorithm_sect] default_properties = fips=yes ``` Compile the testing program. ``` $ gcc \ -I /home/jaruga/.local/openssl-3.0.8-fips-debug/include \ -L /home/jaruga/.local/openssl-3.0.8-fips-debug/lib \ -lcrypto \ -o fips \ fips.c ``` Run the program. ``` $ LD_LIBRARY_PATH=${HOME}/.local/openssl-3.0.8-fips-debug/lib/ \ OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ ./fips Loaded providers: fips base FIPS enabled: yes ``` ### Debug ruby/openssl with an OpenSSL FIPS #### Build ruby/openssl with an OpenSSL FIPS Install. ``` $ git clone https://github.com/ruby/openssl.git $ cd openssl $ bundle install --standalone ``` Compile with the debug flags. If your OpenSSL's library name is "lib64", you need the `--with-openssl-lib=$HOME/.local/openssl-3.0.8-fips-debug/lib64` option too. The `MAKEFLAGS="V=1"` is to print the compiler (`gcc`) command lines if your Ruby is not configured with `./configure --enable-mkmf-verbose` option. You can also use the `bundle exec rake compile -- --with-verbose` option on this purpose in the Ruby on the master branch. ``` $ MAKEFLAGS="V=1" \ RUBY_OPENSSL_EXTCFLAGS="-O0 -g3 -ggdb3 -gdwarf-5" \ bundle exec rake compile -- \ --enable-debug \ --with-openssl-dir=$HOME/.local/openssl-3.0.8-fips-debug ``` #### Clean the built files Note the `bundle exec rake clean` doesn't do this. ``` $ rm -rf tmp $ rm lib/openssl.so ``` #### Run a program to print the used Ruby and OpenSSL versions ``` $ LD_LIBRARY_PATH=$HOME/.local/openssl-3.0.8-fips-debug/lib/ \ bundle exec rake debug /usr/local/ruby-3.2.1/bin/ruby -I./lib -ropenssl -ve'puts OpenSSL::OPENSSL_VERSION, OpenSSL::OPENSSL_LIBRARY_VERSION' ruby 3.2.1 (2023-02-08 revision 31819e82c8) [x86_64-linux] OpenSSL 3.0.8 7 Feb 2023 OpenSSL 3.0.8 7 Feb 2023 ``` #### Run the unit test You see many failures and errors on the current master branch (`037c181ddf30ed7576eba7d14b95c3742449bf63`) in the ruby/openssl. ``` $ LD_LIBRARY_PATH=$HOME/.local/openssl-3.0.8-fips-debug/lib/ \ OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ bundle exec rake test ... 510 tests, 1943 assertions, 14 failures, 331 errors, 0 pendings, 0 omissions, 0 notifications 32.3529% passed ... ``` #### Debug Let me explain you how to debug with the following tools with an example: reading an encriped .pem file. Create a testing .pem file. ``` $ openssl genrsa -out key.pem 4096 $ ls -l key.pem -rw-------. 1 jaruga jaruga 3272 May 2 19:40 key.pem ``` Run a program to read the .pem file. ``` $ LD_LIBRARY_PATH=$HOME/.local/openssl-3.0.8-fips-debug/lib/ \ OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ ruby -I lib -e "require 'openssl'; OpenSSL::PKey.read(File.read('key.pem'))" ``` ##### GDB Make sure you set the `LD_LIBRARY_PATH` in the GDB prompt to prevent overriding the system OpenSSL that is a depenency of the GDB. ``` $ OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ gdb --args ruby -I lib -e "require 'openssl'; OpenSSL::PKey.read(File.read('key.pem'))" (gdb) set environment LD_LIBRARY_PATH /home/jaruga/.local/openssl-3.0.8-fips-debug/lib ``` ##### ltrace ``` $ LD_LIBRARY_PATH=$HOME/.local/openssl-3.0.8-fips-debug/lib/ \ OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ ltrace -ttt -f -l openssl.so -l libssl.so.3 -l libcrypto.so.3 \ ruby -I lib -e "require 'openssl'; OpenSSL::PKey.read(File.read('key.pem'))" ``` ##### strace ``` $ LD_LIBRARY_PATH=$HOME/.local/openssl-3.0.8-fips-debug/lib OPENSSL_CONF=/home/jaruga/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ strace -f \ ruby -I lib -e "require 'openssl'; OpenSSL::PKey.read(File.read('key.pem'))" ``` ##### SystemTap (stap) Debug with the `stap` command, [SystemTap](https://sourceware.org/systemtap/index.html). [Here](https://hackmd.io/c87t7RNBTgKE8gICpJ70Ww?view) is how to set up SystemTap in Fedora Linux as a reference. Prepare the following bash script. ```bash $ cat test.sh #! /bin/bash LD_LIBRARY_PATH=${HOME}/.local/openssl-3.0.8-fips-debug/lib/ \ OPENSSL_CONF=${HOME}/.local/openssl-3.0.8-fips-debug/ssl/openssl_fips.cnf \ ruby -I lib -e "require 'openssl'; OpenSSL::PKey.read(File.read('key.pem'))" ``` ``` $ chmod +x test.sh $ ./test.sh ``` Run the SystemTap scritpt for the Ruby OpenSSL binding library (`lib/openssl.so`) below. This command only traces all the methods in the .so file. ``` $ stap --example para-callgraph.stp \ 'process("lib/openssl.so").function("*")' \ -c "./test.sh > /dev/null" ``` Another example of the SystemTap script for the OpenSSL library `libcrypto.so`. It takes a long time. ``` $ stap --example para-callgraph.stp \ 'process("/home/jaruga/.local/openssl-3.0.8-fips-debug/lib/libcrypto.so.3").function("*")' \ -c "./test.sh > /dev/null" ```
Last changed by  
 
Jun Aruga
456

Read more

OpenSSL FIPS on Feodra

You can check the used compiler and the flags.

6/23/2023
DevConf CZ 2023 summary

3 OpenSSL related talks

6/21/2023
How to debug a unit test with debug gem

Way 1 Build the Ruby. $ cd ~/git/ruby/ruby $ ./configure ... $ make -j$(nproc) Run a unit test with RUN_OPTS=-rdebug/start.

5/25/2023
Set up SystemTap on Fedora

The document is here. The installation document is here. This document is created in Feodra Linux 37. $ sudo dnf install systemtap systemtap-runtime $ sudo stap-prep $ cat ~/script/stap/hello.stp #! /usr/bin/env stap probe oneshot { println("Hello!") } $ sudo stap ~/script/stap/hello.stp Hello! Add groups to run a stap script by a regular user

5/4/2023
Read more from Jun Aruga
Published on HackMD