From 257e9d03b028402089c9f98f3acb25ba668c09af Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 7 May 2020 13:44:01 +0200 Subject: Fix issues reported by markdownlint Reviewed-by: Tomas Mraz Reviewed-by: Matthias St. Pierre (Merged from https://github.com/openssl/openssl/pull/11739) --- test/README.ssltest.md | 97 +++++++++++++++++++++----------------------------- 1 file changed, 40 insertions(+), 57 deletions(-) (limited to 'test/README.ssltest.md') diff --git a/test/README.ssltest.md b/test/README.ssltest.md index 42a25189a2..6ae10fdc18 100644 --- a/test/README.ssltest.md +++ b/test/README.ssltest.md @@ -1,4 +1,5 @@ -# SSL tests +SSL tests +========= SSL testcases are configured in the `ssl-tests` directory. @@ -14,20 +15,19 @@ corresponding to the default configuration. These testcases live in 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 @@ -111,19 +111,18 @@ handshake. 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: @@ -146,14 +145,12 @@ 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 @@ -202,21 +199,18 @@ automatically. Server certificate verification is requested by default. 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`). @@ -224,33 +218,26 @@ client => { 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 default \ - > 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 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 default > 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. @@ -258,13 +245,13 @@ 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. @@ -273,17 +260,13 @@ To run an SSL test manually from the command line, the `TEST_CERTS_DIR` 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) -- cgit v1.2.3