1 SSL tests 2 ========= 3 4 SSL testcases are configured in the `ssl-tests` directory. 5 6 Each `ssl_*.cnf.in` file contains a number of test configurations. These files 7 are used to generate testcases in the OpenSSL CONF format. 8 9 The precise test output can be dependent on the library configuration. The test 10 harness generates the output files on the fly. 11 12 However, for verification, we also include checked-in configuration outputs 13 corresponding to the default configuration. These testcases live in 14 `test/ssl-tests/*.cnf` files. 15 16 For more details, see `ssl-tests/01-simple.cnf.in` for an example. 17 18 Configuring the test 19 -------------------- 20 21 First, give your test a name. The names do not have to be unique. 22 23 An example test input looks like this: 24 25 { 26 name => "test-default", 27 server => { "CipherString" => "DEFAULT" }, 28 client => { "CipherString" => "DEFAULT" }, 29 test => { "ExpectedResult" => "Success" }, 30 } 31 32 The test section supports the following options 33 34 ### Test mode 35 36 * Method - the method to test. One of DTLS or TLS. 37 38 * HandshakeMode - which handshake flavour to test: 39 - Simple - plain handshake (default) 40 - Resume - test resumption 41 - RenegotiateServer - test server initiated renegotiation 42 - RenegotiateClient - test client initiated renegotiation 43 44 When HandshakeMode is Resume or Renegotiate, the original handshake is expected 45 to succeed. All configured test expectations are verified against the second 46 handshake. 47 48 * ApplicationData - amount of application data bytes to send (integer, defaults 49 to 256 bytes). Applies to both client and server. Application data is sent in 50 64kB chunks (but limited by MaxFragmentSize and available parallelization, see 51 below). 52 53 * MaxFragmentSize - maximum send fragment size (integer, defaults to 512 in 54 tests - see `SSL_CTX_set_max_send_fragment` for documentation). Applies to 55 both client and server. Lowering the fragment size will split handshake and 56 application data up between more `SSL_write` calls, thus allowing to exercise 57 different code paths. In particular, if the buffer size (64kB) is at least 58 four times as large as the maximum fragment, interleaved multi-buffer crypto 59 implementations may be used on some platforms. 60 61 ### Test expectations 62 63 * ExpectedResult - expected handshake outcome. One of 64 - Success - handshake success 65 - ServerFail - serverside handshake failure 66 - ClientFail - clientside handshake failure 67 - InternalError - some other error 68 69 * ExpectedClientAlert, ExpectedServerAlert - expected alert. See 70 `test/helpers/ssl_test_ctx.c` for known values. Note: the expected alert is currently 71 matched against the _last_ received alert (i.e., a fatal alert or a 72 `close_notify`). Warning alert expectations are not yet supported. (A warning 73 alert will not be correctly matched, if followed by a `close_notify` or 74 another alert.) 75 76 * ExpectedProtocol - expected negotiated protocol. One of 77 SSLv3, TLSv1, TLSv1.1, TLSv1.2. 78 79 * SessionTicketExpected - whether or not a session ticket is expected 80 - Ignore - do not check for a session ticket (default) 81 - Yes - a session ticket is expected 82 - No - a session ticket is not expected 83 84 * SessionIdExpected - whether or not a session id is expected 85 - Ignore - do not check for a session id (default) 86 - Yes - a session id is expected 87 - No - a session id is not expected 88 89 * ResumptionExpected - whether or not resumption is expected (Resume mode only) 90 - Yes - resumed handshake 91 - No - full handshake (default) 92 93 * ExpectedNPNProtocol, ExpectedALPNProtocol - NPN and ALPN expectations. 94 95 * ExpectedTmpKeyType - the expected algorithm or curve of server temp key 96 97 * ExpectedServerCertType, ExpectedClientCertType - the expected algorithm or 98 curve of server or client certificate 99 100 * ExpectedServerSignHash, ExpectedClientSignHash - the expected 101 signing hash used by server or client certificate 102 103 * ExpectedServerSignType, ExpectedClientSignType - the expected 104 signature type used by server or client when signing messages 105 106 * ExpectedClientCANames - for client auth list of CA names the server must 107 send. If this is "empty" the list is expected to be empty otherwise it 108 is a file of certificates whose subject names form the list. 109 110 * ExpectedServerCANames - list of CA names the client must send, TLS 1.3 only. 111 If this is "empty" the list is expected to be empty otherwise it is a file 112 of certificates whose subject names form the list. 113 114 Configuring the client and server 115 --------------------------------- 116 117 The client and server configurations can be any valid `SSL_CTX` 118 configurations. For details, see the manpages for `SSL_CONF_cmd`. 119 120 Give your configurations as a dictionary of CONF commands, e.g. 121 122 server => { 123 "CipherString" => "DEFAULT", 124 "MinProtocol" => "TLSv1", 125 } 126 127 The following sections may optionally be defined: 128 129 * server2 - this section configures a secondary context that is selected via the 130 ServerName test option. This context is used whenever a ServerNameCallback is 131 specified. If the server2 section is not present, then the configuration 132 matches server. 133 * resume_server - this section configures the client to resume its session 134 against a different server. This context is used whenever HandshakeMode is 135 Resume. If the resume_server section is not present, then the configuration 136 matches server. 137 * resume_client - this section configures the client to resume its session with 138 a different configuration. In practice this may occur when, for example, 139 upgraded clients reuse sessions persisted on disk. This context is used 140 whenever HandshakeMode is Resume. If the resume_client section is not present, 141 then the configuration matches client. 142 143 ### Configuring callbacks and additional options 144 145 Additional handshake settings can be configured in the `extra` section of each 146 client and server: 147 148 client => { 149 "CipherString" => "DEFAULT", 150 extra => { 151 "ServerName" => "server2", 152 } 153 } 154 155 #### Supported client-side options 156 157 * ClientVerifyCallback - the client's custom certificate verify callback. 158 Used to test callback behaviour. One of 159 - None - no custom callback (default) 160 - AcceptAll - accepts all certificates. 161 - RejectAll - rejects all certificates. 162 163 * ServerName - the server the client should attempt to connect to. One of 164 - None - do not use SNI (default) 165 - server1 - the initial context 166 - server2 - the secondary context 167 - invalid - an unknown context 168 169 * CTValidation - Certificate Transparency validation strategy. One of 170 - None - no validation (default) 171 - Permissive - SSL_CT_VALIDATION_PERMISSIVE 172 - Strict - SSL_CT_VALIDATION_STRICT 173 174 #### Supported server-side options 175 176 * ServerNameCallback - the SNI switching callback to use 177 - None - no callback (default) 178 - IgnoreMismatch - continue the handshake on SNI mismatch 179 - RejectMismatch - abort the handshake on SNI mismatch 180 181 * BrokenSessionTicket - a special test case where the session ticket callback 182 does not initialize crypto. 183 - No (default) 184 - Yes 185 186 #### Mutually supported options 187 188 * NPNProtocols, ALPNProtocols - NPN and ALPN settings. Server and client 189 protocols can be specified as a comma-separated list, and a callback with the 190 recommended behaviour will be installed automatically. 191 192 * SRPUser, SRPPassword - SRP settings. For client, this is the SRP user to 193 connect as; for server, this is a known SRP user. 194 195 ### Default server and client configurations 196 197 The default server certificate and CA files are added to the configurations 198 automatically. Server certificate verification is requested by default. 199 200 You can override these options by redefining them: 201 202 client => { 203 "VerifyCAFile" => "/path/to/custom/file" 204 } 205 206 or by deleting them 207 208 client => { 209 "VerifyCAFile" => undef 210 } 211 212 Adding a test to the test harness 213 --------------------------------- 214 215 1. Add a new test configuration to `test/ssl-tests`, following the examples of 216 existing `*.cnf.in` files (for example, `01-simple.cnf.in`). 217 218 2. Generate the generated `*.cnf` test input file. You can do so by running 219 `generate_ssl_tests.pl`: 220 221 $ ./config 222 $ cd test 223 $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \ 224 ssl-tests/my.cnf.in default > ssl-tests/my.cnf 225 226 where `my.cnf.in` is your test input file and `default` is the provider to use. 227 For all the pre-generated test files you should use the default provider. 228 229 For example, to generate the test cases in `ssl-tests/01-simple.cnf.in`, do 230 231 $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \ 232 ssl-tests/01-simple.cnf.in default > ssl-tests/01-simple.cnf 233 234 Alternatively (hackish but simple), you can comment out 235 236 unlink glob $tmp_file; 237 238 in `test/recipes/80-test_ssl_new.t` and run 239 240 $ make TESTS=test_ssl_new test 241 242 This will save the generated output in a `*.tmp` file in the build directory. 243 244 3. Update the number of tests planned in `test/recipes/80-test_ssl_new.t`. If 245 the test suite has any skip conditions, update those too (see 246 `test/recipes/80-test_ssl_new.t` for details). 247 248 Running the tests with the test harness 249 --------------------------------------- 250 251 HARNESS_VERBOSE=yes make TESTS=test_ssl_new test 252 253 Running a test manually 254 ----------------------- 255 256 These steps are only needed during development. End users should run `make test` 257 or follow the instructions above to run the SSL test suite. 258 259 To run an SSL test manually from the command line, the `TEST_CERTS_DIR` 260 environment variable to point to the location of the certs. E.g., from the root 261 OpenSSL directory, do 262 263 $ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs test/ssl_test \ 264 test/ssl-tests/01-simple.cnf default 265 266 or for shared builds 267 268 $ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs \ 269 util/wrap.pl test/ssl_test test/ssl-tests/01-simple.cnf default 270 271 In the above examples, `default` is the provider to use. 272 273 Note that the test expectations sometimes depend on the Configure settings. For 274 example, the negotiated protocol depends on the set of available (enabled) 275 protocols: a build with `enable-ssl3` has different test expectations than a 276 build with `no-ssl3`. 277 278 The Perl test harness automatically generates expected outputs, so users who 279 just run `make test` do not need any extra steps. 280 281 However, when running a test manually, keep in mind that the repository version 282 of the generated `test/ssl-tests/*.cnf` correspond to expected outputs in with 283 the default Configure options. To run `ssl_test` manually from the command line 284 in a build with a different configuration, you may need to generate the right 285 `*.cnf` file from the `*.cnf.in` input first. 286
Indexes created Tue Mar 03 05:31:39 UTC 2026