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 Python PYCA/Cryptography test suite
   9 ===================================
  10
  11 This python test suite runs cryptographic tests with a local OpenSSL build as
  12 the implementation.
  13
  14 First checkout the `PYCA/Cryptography` module into `./pyca-cryptography` using:
  15
  16     $ git submodule update --init
  17
  18 Then configure/build OpenSSL compatible with the python module:
  19
  20     $ ./config shared enable-external-tests
  21     $ make
  22
  23 The tests will run in a python virtual environment which requires virtualenv
  24 to be installed.
  25
  26     $ make test VERBOSE=1 TESTS=test_external_pyca
  27
  28 Test failures and suppressions
  29 ------------------------------
  30
  31 Some tests target older (<=1.0.2) versions so will not run. Other tests target
  32 other crypto implementations so are not relevant. Currently no tests fail.
  33
  34 krb5 test suite
  35 ===============
  36
  37 Much like the PYCA/Cryptography test suite, this builds and runs the krb5
  38 tests against the local OpenSSL build.
  39
  40 You will need a git checkout of krb5 at the top level:
  41
  42     $ git clone https://github.com/krb5/krb5
  43
  44 krb5's master has to pass this same CI, but a known-good version is
  45 krb5-1.15.1-final if you want to be sure.
  46
  47     $ cd krb5
  48     $ git checkout krb5-1.15.1-final
  49     $ cd ..
  50
  51 OpenSSL must be built with external tests enabled:
  52
  53     $ ./config enable-external-tests
  54     $ make
  55
  56 krb5's tests will then be run as part of the rest of the suite, or can be
  57 explicitly run (with more debugging):
  58
  59     $ VERBOSE=1 make TESTS=test_external_krb5 test
  60
  61 Test-failures suppressions
  62 --------------------------
  63
  64 krb5 will automatically adapt its test suite to account for the configuration
  65 of your system.  Certain tests may require more installed packages to run.  No
  66 tests are expected to fail.
  67
  68 GOST engine test suite
  69 ===============
  70
  71 Much like the PYCA/Cryptography test suite, this builds and runs the GOST engine
  72 tests against the local OpenSSL build.
  73
  74 You will need a git checkout of gost-engine at the top level:
  75
  76     $ git submodule update --init
  77
  78 Then configure/build OpenSSL enabling external tests:
  79
  80     $ ./config shared enable-external-tests
  81     $ make
  82
  83 GOST engine requires CMake for the build process.
  84
  85 GOST engine tests will then be run as part of the rest of the suite, or can be
  86 explicitly run (with more debugging):
  87
  88     $ make test VERBOSE=1 TESTS=test_external_gost_engine
  89
  90 OQSprovider test suite
  91 ======================
  92
  93 Much like the PYCA/Cryptography test suite, this builds and runs the OQS
  94 (OpenQuantumSafe -- www.openquantumsafe.org) provider tests against the
  95 local OpenSSL build.
  96
  97 You will need a git checkout of oqsprovider at the top level:
  98
  99     $ git submodule update --init
 100
 101 Then configure/build OpenSSL enabling external tests:
 102
 103     $ ./config shared enable-external-tests
 104     $ make
 105
 106 oqsprovider requires CMake for the build process.
 107
 108 OQSprovider tests will then be run as part of the rest of the suite, or can be
 109 explicitly run (with more debugging):
 110
 111     $ make test VERBOSE=1 TESTS=test_external_oqsprovider
 112
 113 The environment variable `OQS_SKIP_TESTS` can be set to select tests and
 114 algorithms to be skipped. If not set, the "rainbow" algorithm set as well as
 115 the (OQS-)OpenSSL1.1.1 compatibility tests will not be executed. So, for
 116 example to exclude the "mceliece" and "kyber" algorithms execute
 117
 118     OQS_SKIP_TESTS=mceliece,kyber make test TESTS=test_external_oqsprovider
 119
 120 The names of all supported quantum-safe algorithms are available at
 121 <https://github.com/open-quantum-safe/openssl#supported-algorithms>
 122
 123 Updating test suites
 124 ====================
 125
 126 To update the commit for any of the above test suites:
 127
 128 - Make sure the submodules are cloned locally:
 129
 130     $ git submodule update --init --recursive
 131
 132 - Enter subdirectory and pull from the repository (use a specific branch/tag if required):
 133
 134     $ cd `<submodule-dir>`
 135     $ git pull origin master
 136
 137 - Go to root directory, there should be a new git status:
 138
 139     $ cd ../
 140     $ git status
 141       ...
 142       #       modified:   `<submodule-dir>` (new commits)
 143       ...
 144
 145 - Add/commit/push the update
 146
 147     $ git add `<submodule-dir>`
 148     $ git commit -m `"Updated <submodule> to latest commit"`
 149     $ git push