-# SSL tests
+SSL tests
+=========
SSL testcases are configured in the `ssl-tests` directory.
For more details, see `ssl-tests/01-simple.cnf.in` for an example.
-## Configuring the test
+Configuring the test
+--------------------
First, give your test a name. The names do not have to be unique.
An example test input looks like this:
-```
{
name => "test-default",
server => { "CipherString" => "DEFAULT" },
client => { "CipherString" => "DEFAULT" },
test => { "ExpectedResult" => "Success" },
}
-```
The test section supports the following options
If this is "empty" the list is expected to be empty otherwise it is a file
of certificates whose subject names form the list.
-## Configuring the client and server
+Configuring the client and server
+---------------------------------
The client and server configurations can be any valid `SSL_CTX`
configurations. For details, see the manpages for `SSL_CONF_cmd`.
Give your configurations as a dictionary of CONF commands, e.g.
-```
-server => {
- "CipherString" => "DEFAULT",
- "MinProtocol" => "TLSv1",
-}
-```
+ server => {
+ "CipherString" => "DEFAULT",
+ "MinProtocol" => "TLSv1",
+ }
The following sections may optionally be defined:
Additional handshake settings can be configured in the `extra` section of each
client and server:
-```
-client => {
- "CipherString" => "DEFAULT",
- extra => {
- "ServerName" => "server2",
+ client => {
+ "CipherString" => "DEFAULT",
+ extra => {
+ "ServerName" => "server2",
+ }
}
-}
-```
#### Supported client-side options
You can override these options by redefining them:
-```
-client => {
- "VerifyCAFile" => "/path/to/custom/file"
-}
-```
+ client => {
+ "VerifyCAFile" => "/path/to/custom/file"
+ }
or by deleting them
-```
-client => {
- "VerifyCAFile" => undef
-}
-```
+ client => {
+ "VerifyCAFile" => undef
+ }
-## Adding a test to the test harness
+Adding a test to the test harness
+---------------------------------
1. Add a new test configuration to `test/ssl-tests`, following the examples of
existing `*.cnf.in` files (for example, `01-simple.cnf.in`).
2. Generate the generated `*.cnf` test input file. You can do so by running
`generate_ssl_tests.pl`:
-```
-$ ./config
-$ cd test
-$ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl ssl-tests/my.cnf.in \
- > ssl-tests/my.cnf
-```
+ $ ./config
+ $ cd test
+ $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \
+ ssl-tests/my.cnf.in default > ssl-tests/my.cnf
-where `my.cnf.in` is your test input file.
+where `my.cnf.in` is your test input file and `default` is the provider to use.
+For all the pre-generated test files you should use the default provider.
For example, to generate the test cases in `ssl-tests/01-simple.cnf.in`, do
-```
-$ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl ssl-tests/01-simple.cnf.in > ssl-tests/01-simple.cnf
-```
+ $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \
+ ssl-tests/01-simple.cnf.in default > ssl-tests/01-simple.cnf
Alternatively (hackish but simple), you can comment out
-```
-unlink glob $tmp_file;
-```
+ unlink glob $tmp_file;
in `test/recipes/80-test_ssl_new.t` and run
-```
-$ make TESTS=test_ssl_new test
-```
+ $ make TESTS=test_ssl_new test
This will save the generated output in a `*.tmp` file in the build directory.
the test suite has any skip conditions, update those too (see
`test/recipes/80-test_ssl_new.t` for details).
-## Running the tests with the test harness
+Running the tests with the test harness
+---------------------------------------
-```
-HARNESS_VERBOSE=yes make TESTS=test_ssl_new test
-```
+ HARNESS_VERBOSE=yes make TESTS=test_ssl_new test
-## Running a test manually
+Running a test manually
+-----------------------
These steps are only needed during development. End users should run `make test`
or follow the instructions above to run the SSL test suite.
environment variable to point to the location of the certs. E.g., from the root
OpenSSL directory, do
-```
-$ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs test/ssl_test \
- test/ssl-tests/01-simple.cnf
-```
+ $ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs test/ssl_test \
+ test/ssl-tests/01-simple.cnf
or for shared builds
-```
-$ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs \
- util/wrap.pl test/ssl_test test/ssl-tests/01-simple.cnf
-```
+ $ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs \
+ util/wrap.pl test/ssl_test test/ssl-tests/01-simple.cnf
Note that the test expectations sometimes depend on the Configure settings. For
example, the negotiated protocol depends on the set of available (enabled)