Self Test Failures

The OpenSSL library includes a test suite that exercises components from both libcrypto.a and libssl.a. Ensuring the library builds and executes its tests properly is a keystone to using the library.

This page will show you how to isolate the test and the cause under many conditions. The more information you can supply with a bug report or pull request, the easier it is for the team to identify the failure or accept proposed changes.

Generally speaking, there are two generations of self tests. The first generation is from OpenSSL 1.0.2 and below. The second generation is from OpenSSL 1.1.0 and above. This page focuses on the second generation, or OpenSSL 1.1.0 and above.

You can sometimes isolate a bug with no-asm, and sometimes with -O0 or -O1. Ideally the bug will be present with no optimizations (-O0), but sometimes it takes some compiler analysis to tickle it (-O1).

Debug Build

The first thing you should do after verifying the bug is to create a debug build of the OpenSSL library and attempt to reproduce it. Creating a debug build is as easy as using -d configure argument. In the output below, notice -d caused the library to reduce optimizations (-O0) and increase debugging information (-g). However, the debugging information will lack symbolic constants because -g3 was not used:

$ ./config -d
Operating system: i86pc-whatever-solaris2
Configuring for solaris64-x86_64-gcc
...
CC            =gcc
CFLAG         =-m64 -Wall -DL_ENDIAN -O0 -g -pthread -DFILIO_H  -Wa,--noexecstack
...

To ensure most of your preferred flags are used, perform the following. Not all flags will be honored, but its an improvement over -d. The -DNDEBUG is used to ensure Posix's assert does not crash your program while under the debugger.

$ ./config no-asm -DNDEBUG -g3 -O0 -fno-omit-frame-pointer
Operating system: i86pc-whatever-solaris2
Configuring for solaris64-x86_64-gcc
...
CC            =gcc
CFLAG         =-m64 -Wall -DL_ENDIAN -O3 -pthread -DFILIO_H  -g3 -O0 -fno-omit-frame-pointer
...

After configuring, run make as usual.

Build the Test

You typically run make test to validate the library after make'ing. Since you already know there's a problem, you can build the problem test with the following. The command below is an example for tracking down a failure in the HMAC test suite

$ VERBOSE=1 make TESTS="test_hmac" test
...

( cd test; \
  SRCTOP=../. \
  BLDTOP=../. \
  PERL="/usr/local/bin/perl" \
  EXE_EXT= \
  OPENSSL_ENGINES=.././engines \
    /usr/local/bin/perl .././test/run_tests.pl test_hmac )
../test/recipes/05-test_hmac.t .. 
1..1
test 0 ok
test 1 ok
test 2 ok
test 3 ok
test 4 ok
test 5 ok
test 6 ok
../util/shlib_wrap.sh ./hmactest => 0
ok 1 - running hmactest
ok
All tests successful.
Files=1, Tests=1,  0 wallclock secs ( 0.03 usr  0.01 sys +  0.06 cusr  0.02 csys =  0.12 CPU)
Result: PASS
`test' is up to date.

Execute the Test

The executable for test_hmac is created from the source 05-test_hmac.t, and it will be located at ./test/buildtest_hmac:

$ file ./test/buildtest_hmac
./test/buildtest_hmac:  ELF 64-bit LSB executable AMD64 Version 1, dynamically linked, not stripped

You can manually execute the test with the following:

TODO

And you can run the test under a debugger with the following:

TODO

Debug an Engine

If you are testing an OpenSSL engine, then the procedures and paths are slightly different.

You manually build the engine with:

$ cd test
$ make test/afalgtest

You can run the engine test under a debugger with the following:

$ OPENSSL_ENGINES=../engines/afalg gdb ./afalgtest