test/README.ssltest.md

   1 # SSL tests
   2
   3 SSL testcases are configured in the `ssl-tests` directory.
   4
   5 Each `ssl_*.conf.in` file contains a number of test configurations. These files
   6 are used to generate testcases in the OpenSSL CONF format.
   7
   8 The precise test output can be dependent on the library configuration. The test
   9 harness generates the output files on the fly.
  10
  11 However, for verification, we also include checked-in configuration outputs
  12 corresponding to the default configuration. These testcases live in
  13 `test/ssl-tests/*.conf` files. Therefore, whenever you're adding or updating a
  14 generated test, you should run
  15
  16 ```
  17 $ ./config
  18 $ cd test
  19 $ TOP=.. perl -I testlib/ generate_ssl_tests.pl ssl-tests/my.conf.in \
  20   > ssl-tests/my.conf
  21 ```
  22
  23 where `my.conf.in` is your test input file.
  24
  25 For example, to generate the test cases in `ssl-tests/01-simple.conf.in`, do
  26
  27 ```
  28 $ TOP=.. perl generate_ssl_tests.pl ssl-tests/01-simple.conf.in > ssl-tests/01-simple.conf
  29 ```
  30
  31 For more details, see `ssl-tests/01-simple.conf.in` for an example.
  32
  33 ## Configuring the test
  34
  35 First, give your test a name. The names do not have to be unique.
  36
  37 An example test input looks like this:
  38
  39 ```
  40     {
  41         name => "test-default",
  42         server => { "CipherString" => "DEFAULT" },
  43         client => { "CipherString" => "DEFAULT" },
  44         test   => { "ExpectedResult" => "Success" },
  45     }
  46 ```
  47
  48 The test section supports the following options
  49
  50 ### Test mode
  51
  52 * Method - the method to test. One of DTLS or TLS.
  53
  54 * HandshakeMode - which handshake flavour to test:
  55   - Simple - plain handshake (default)
  56   - Resume - test resumption
  57   - (Renegotiate - test renegotiation, not yet implemented)
  58
  59 When HandshakeMode is Resume or Renegotiate, the original handshake is expected
  60 to succeed. All configured test expectations are verified against the second
  61 handshake.
  62
  63 ### Test expectations
  64
  65 * ExpectedResult - expected handshake outcome. One of
  66   - Success - handshake success
  67   - ServerFail - serverside handshake failure
  68   - ClientFail - clientside handshake failure
  69   - InternalError - some other error
  70
  71 * ExpectedClientAlert, ExpectedServerAlert - expected alert. See
  72   `ssl_test_ctx.c` for known values.
  73
  74 * ExpectedProtocol - expected negotiated protocol. One of
  75   SSLv3, TLSv1, TLSv1.1, TLSv1.2.
  76
  77 * SessionTicketExpected - whether or not a session ticket is expected
  78   - Ignore - do not check for a session ticket (default)
  79   - Yes - a session ticket is expected
  80   - No - a session ticket is not expected
  81
  82 * ResumptionExpected - whether or not resumption is expected (Resume mode only)
  83   - Yes - resumed handshake
  84   - No - full handshake (default)
  85
  86 * ExpectedNPNProtocol, ExpectedALPNProtocol - NPN and ALPN expectations.
  87
  88 ## Configuring the client and server
  89
  90 The client and server configurations can be any valid `SSL_CTX`
  91 configurations. For details, see the manpages for `SSL_CONF_cmd`.
  92
  93 Give your configurations as a dictionary of CONF commands, e.g.
  94
  95 ```
  96 server => {
  97     "CipherString" => "DEFAULT",
  98     "MinProtocol" => "TLSv1",
  99 }
 100 ```
 101
 102 The following sections may optionally be defined:
 103
 104 * server2 - this section configures a secondary context that is selected via the
 105   ServerName test option. This context is used whenever a ServerNameCallback is
 106   specified. If the server2 section is not present, then the configuration
 107   matches server.
 108 * resume_server - this section configures the client to resume its session
 109   against a different server. This context is used whenever HandshakeMode is
 110   Resume. If the resume_server section is not present, then the configuration
 111   matches server.
 112 * resume_client - this section configures the client to resume its session with
 113   a different configuration. In practice this may occur when, for example,
 114   upgraded clients reuse sessions persisted on disk.  This context is used
 115   whenever HandshakeMode is Resume. If the resume_client section is not present,
 116   then the configuration matches client.
 117
 118 ### Configuring callbacks and additional options
 119
 120 Additional handshake settings can be configured in the `extra` section of each
 121 client and server:
 122
 123 ```
 124 client => {
 125     "CipherString" => "DEFAULT",
 126     extra => {
 127         "ServerName" => "server2",
 128     }
 129 }
 130 ```
 131
 132 #### Supported client-side options
 133
 134 * ClientVerifyCallback - the client's custom certificate verify callback.
 135   Used to test callback behaviour. One of
 136   - None - no custom callback (default)
 137   - AcceptAll - accepts all certificates.
 138   - RejectAll - rejects all certificates.
 139
 140 * ServerName - the server the client should attempt to connect to. One of
 141   - None - do not use SNI (default)
 142   - server1 - the initial context
 143   - server2 - the secondary context
 144   - invalid - an unknown context
 145
 146 #### Supported server-side options
 147
 148 * ServerNameCallback - the SNI switching callback to use
 149   - None - no callback (default)
 150   - IgnoreMismatch - continue the handshake on SNI mismatch
 151   - RejectMismatch - abort the handshake on SNI mismatch
 152
 153 * BrokenSessionTicket - a special test case where the session ticket callback
 154   does not initialize crypto.
 155   - No (default)
 156   - Yes
 157
 158 #### Mutually supported options
 159
 160 * NPNProtocols, ALPNProtocols - NPN and ALPN settings. Server and client
 161   protocols can be specified as a comma-separated list, and a callback with the
 162   recommended behaviour will be installed automatically.
 163
 164 ### Default server and client configurations
 165
 166 The default server certificate and CA files are added to the configurations
 167 automatically. Server certificate verification is requested by default.
 168
 169 You can override these options by redefining them:
 170
 171 ```
 172 client => {
 173     "VerifyCAFile" => "/path/to/custom/file"
 174 }
 175 ```
 176
 177 or by deleting them
 178
 179 ```
 180 client => {
 181     "VerifyCAFile" => undef
 182 }
 183 ```
 184
 185 ## Adding a test to the test harness
 186
 187 Add your configuration file to `test/recipes/80-test_ssl_new.t`.
 188
 189 ## Running the tests with the test harness
 190
 191 ```
 192 HARNESS_VERBOSE=yes make TESTS=test_ssl_new test
 193 ```
 194
 195 ## Running a test manually
 196
 197 These steps are only needed during development. End users should run `make test`
 198 or follow the instructions above to run the SSL test suite.
 199
 200 To run an SSL test manually from the command line, the `TEST_CERTS_DIR`
 201 environment variable to point to the location of the certs. E.g., from the root
 202 OpenSSL directory, do
 203
 204 ```
 205 $ TEST_CERTS_DIR=test/certs test/ssl_test test/ssl-tests/01-simple.conf
 206 ```
 207
 208 or for shared builds
 209
 210 ```
 211 $ TEST_CERTS_DIR=test/certs util/shlib_wrap.sh test/ssl_test \
 212   test/ssl-tests/01-simple.conf
 213 ```
 214
 215 Note that the test expectations sometimes depend on the Configure settings. For
 216 example, the negotiated protocol depends on the set of available (enabled)
 217 protocols: a build with `enable-ssl3` has different test expectations than a
 218 build with `no-ssl3`.
 219
 220 The Perl test harness automatically generates expected outputs, so users who
 221 just run `make test` do not need any extra steps.
 222
 223 However, when running a test manually, keep in mind that the repository version
 224 of the generated `test/ssl-tests/*.conf` correspond to expected outputs in with
 225 the default Configure options. To run `ssl_test` manually from the command line
 226 in a build with a different configuration, you may need to generate the right
 227 `*.conf` file from the `*.conf.in` input first.