test/README-external.md

   1 Running external test suites with OpenSSL
   2 =========================================
   3
   4 It is possible to integrate external test suites into OpenSSL's "make test".
   5 This capability is considered a developer option and does not work on all
   6 platforms.
   7
   8
   9
  10 The BoringSSL test suite
  11 ========================
  12
  13 In order to run the BoringSSL tests with OpenSSL, first checkout the BoringSSL
  14 source code into an appropriate directory. This can be done in two ways:
  15
  16 1) Separately from the OpenSSL checkout using:
  17
  18   $ git clone https://boringssl.googlesource.com/boringssl boringssl
  19
  20   The BoringSSL tests are only confirmed to work at a specific commit in the
  21   BoringSSL repository. Later commits may or may not pass the test suite:
  22
  23   $ cd boringssl
  24   $ git checkout 490469f850e
  25
  26 2) Using the already configured submodule settings in OpenSSL:
  27
  28   $ git submodule update --init
  29
  30 Configure the OpenSSL source code to enable the external tests:
  31
  32 $ cd ../openssl
  33 $ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \
  34   enable-external-tests
  35
  36 Note that using other config options than those given above may cause the tests
  37 to fail.
  38
  39 Run the OpenSSL tests by providing the path to the BoringSSL test runner in the
  40 BORING_RUNNER_DIR environment variable:
  41
  42 $ BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make test
  43
  44 Note that the test suite may change directory while running so the path provided
  45 should be absolute and not relative to the current working directory.
  46
  47 To see more detailed output you can run just the BoringSSL tests with the
  48 verbose option:
  49
  50 $ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \
  51   TESTS="test_external_boringssl" test
  52
  53
  54 Test failures and suppressions
  55 ------------------------------
  56
  57 A large number of the BoringSSL tests are known to fail. A test could fail
  58 because of many possible reasons. For example:
  59
  60 - A bug in OpenSSL
  61 - Different interpretations of standards
  62 - Assumptions about the way BoringSSL works that do not apply to OpenSSL
  63 - The test uses APIs added to BoringSSL that are not present in OpenSSL
  64 - etc
  65
  66 In order to provide a "clean" baseline run with all the tests passing a config
  67 file has been provided that suppresses the running of tests that are known to
  68 fail. These suppressions are held in the file "test/ossl_shim/ossl_config.json"
  69 within the OpenSSL source code.
  70
  71 The community is encouraged to contribute patches which reduce the number of
  72 suppressions that are currently present.
  73
  74
  75 Python PYCA/Cryptography test suite
  76 ===================================
  77
  78 This python test suite runs cryptographic tests with a local OpenSSL build as
  79 the implementation.
  80
  81 First checkout the PYCA/Cryptography module into ./pyca-cryptography using:
  82
  83 $ git submodule update --init
  84
  85 Then configure/build OpenSSL compatible with the python module:
  86
  87 $ ./config shared enable-external-tests
  88 $ make
  89
  90 The tests will run in a python virtual environment which requires virtualenv
  91 to be installed.
  92
  93 $ make test VERBOSE=1 TESTS=test_external_pyca
  94
  95 Test failures and suppressions
  96 ------------------------------
  97
  98 Some tests target older (<=1.0.2) versions so will not run. Other tests target
  99 other crypto implementations so are not relevant. Currently no tests fail.
 100
 101
 102 krb5 test suite
 103 ===============
 104
 105 Much like the PYCA/Cryptography test suite, this builds and runs the krb5
 106 tests against the local OpenSSL build.
 107
 108 You will need a git checkout of krb5 at the top level:
 109
 110 $ git clone https://github.com/krb5/krb5
 111
 112 krb5's master has to pass this same CI, but a known-good version is
 113 krb5-1.15.1-final if you want to be sure.
 114
 115 $ cd krb5
 116 $ git checkout krb5-1.15.1-final
 117 $ cd ..
 118
 119 OpenSSL must be built with external tests enabled:
 120
 121 $ ./config enable-external-tests
 122 $ make
 123
 124 krb5's tests will then be run as part of the rest of the suite, or can be
 125 explicitly run (with more debugging):
 126
 127 $ VERBOSE=1 make TESTS=test_external_krb5 test
 128
 129 Test-failures suppressions
 130 --------------------------
 131
 132 krb5 will automatically adapt its test suite to account for the configuration
 133 of your system.  Certain tests may require more installed packages to run.  No
 134 tests are expected to fail.
 135
 136
 137 GOST engine test suite
 138 ===============
 139
 140 Much like the PYCA/Cryptography test suite, this builds and runs the GOST engine
 141 tests against the local OpenSSL build.
 142
 143 You will need a git checkout of gost-engine at the top level:
 144
 145 $ git submodule update --init
 146
 147 Then configure/build OpenSSL enabling external tests:
 148
 149 $ ./config shared enable-external-tests
 150 $ make
 151
 152 GOST engine requires CMake for the build process.
 153
 154 GOST engine tests will then be run as part of the rest of the suite, or can be
 155 explicitly run (with more debugging):
 156
 157 $ make test VERBOSE=1 TESTS=test_external_gost_engine
 158
 159 Updating test suites
 160 ====================
 161
 162 To update the commit for any of the above test suites:
 163
 164 - Make sure the submodules are cloned locally:
 165
 166   $ git submodule update --init --recursive
 167
 168 - Enter subdirectory and pull from the repository (use a specific branch/tag if required):
 169
 170   $ cd <submodule-dir>
 171   $ git pull origin master
 172
 173 - Go to root directory, there should be a new git status:
 174
 175   $ cd ../
 176   $ git status
 177   ...
 178   #       modified:   <submodule-dir> (new commits)
 179   ...
 180
 181 - Add/commit/push the update
 182
 183   git add <submodule-dir>
 184   git commit -m "Updated <submodule> to latest commit"
 185   git push
 186