]>
Commit | Line | Data |
---|---|---|
453dfd8d EK |
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 | * ExpectedResult - expected handshake outcome. One of | |
51 | - Success - handshake success | |
52 | - ServerFail - serverside handshake failure | |
53 | - ClientFail - clientside handshake failure | |
54 | - InternalError - some other error | |
55 | ||
56 | * ClientAlert, ServerAlert - expected alert. See `ssl_test_ctx.c` for known | |
57 | values. | |
58 | ||
59 | * Protocol - expected negotiated protocol. One of | |
60 | SSLv3, TLSv1, TLSv1.1, TLSv1.2. | |
61 | ||
a263f320 EK |
62 | * ClientVerifyCallback - the client's custom certificate verify callback. |
63 | Used to test callback behaviour. One of | |
d2b23cd2 | 64 | - None - no custom callback (default) |
a263f320 EK |
65 | - AcceptAll - accepts all certificates. |
66 | - RejectAll - rejects all certificates. | |
67 | ||
74726750 EK |
68 | * Method - the method to test. One of DTLS or TLS. |
69 | ||
81fc33c9 EK |
70 | * ServerName - the server the client should attempt to connect to. One of |
71 | - None - do not use SNI (default) | |
72 | - server1 - the initial context | |
5c753de6 | 73 | - server2 - the secondary context |
d2b23cd2 EK |
74 | - invalid - an unknown context |
75 | ||
76 | * ServerNameCallback - the SNI switching callback to use | |
77 | - None - no callback (default) | |
78 | - IgnoreMismatch - continue the handshake on SNI mismatch | |
79 | - RejectMismatch - abort the handshake on SNI mismatch | |
5c753de6 TS |
80 | |
81 | * SessionTicketExpected - whether or not a session ticket is expected | |
82 | - Ignore - do not check for a session ticket (default) | |
83 | - Yes - a session ticket is expected | |
84 | - No - a session ticket is not expected | |
590ed3d7 EK |
85 | - Broken - a special test case where the session ticket callback does not |
86 | initialize crypto | |
87 | ||
88 | * HandshakeMode - which handshake flavour to test: | |
89 | - Simple - plain handshake (default) | |
90 | - Resume - test resumption | |
91 | - (Renegotiate - test renegotiation, not yet implemented) | |
92 | ||
93 | * ResumptionExpected - whether or not resumption is expected (Resume mode only) | |
94 | - Yes - resumed handshake | |
95 | - No - full handshake (default) | |
96 | ||
97 | When HandshakeMode is Resume or Renegotiate, the original handshake is expected | |
98 | to succeed. All configured test expectations are verified against the second handshake. | |
5c753de6 | 99 | |
ce2cdac2 EK |
100 | * ServerNPNProtocols, Server2NPNProtocols, ClientNPNProtocols, ExpectedNPNProtocol, |
101 | ServerALPNProtocols, Server2ALPNProtocols, ClientALPNProtocols, ExpectedALPNProtocol - | |
102 | NPN and ALPN settings. Server and client protocols can be specified as a comma-separated list, | |
103 | and a callback with the recommended behaviour will be installed automatically. | |
104 | ||
453dfd8d EK |
105 | ## Configuring the client and server |
106 | ||
107 | The client and server configurations can be any valid `SSL_CTX` | |
108 | configurations. For details, see the manpages for `SSL_CONF_cmd`. | |
109 | ||
110 | Give your configurations as a dictionary of CONF commands, e.g. | |
111 | ||
112 | ``` | |
113 | server => { | |
114 | "CipherString" => "DEFAULT", | |
115 | "MinProtocol" => "TLSv1", | |
116 | } | |
117 | ``` | |
118 | ||
590ed3d7 EK |
119 | The following sections may optionally be defined: |
120 | ||
121 | * server2 - this section configures a secondary context that is selected via the | |
122 | ServerName test option. This context is used whenever a ServerNameCallback is | |
123 | specified. If the server2 section is not present, then the configuration | |
124 | matches server. | |
125 | * resume_server - this section configures the client to resume its session | |
126 | against a different server. This context is used whenever HandshakeMode is | |
11279b13 | 127 | Resume. If the resume_server section is not present, then the configuration |
590ed3d7 | 128 | matches server. |
11279b13 EK |
129 | * resume_client - this section configures the client to resume its session with |
130 | a different configuration. In practice this may occur when, for example, | |
131 | upgraded clients reuse sessions persisted on disk. This context is used | |
132 | whenever HandshakeMode is Resume. If the resume_client section is not present, | |
133 | then the configuration matches client. | |
5c753de6 | 134 | |
453dfd8d EK |
135 | ### Default server and client configurations |
136 | ||
137 | The default server certificate and CA files are added to the configurations | |
138 | automatically. Server certificate verification is requested by default. | |
139 | ||
140 | You can override these options by redefining them: | |
141 | ||
142 | ``` | |
143 | client => { | |
144 | "VerifyCAFile" => "/path/to/custom/file" | |
145 | } | |
146 | ``` | |
147 | ||
148 | or by deleting them | |
149 | ||
150 | ``` | |
151 | client => { | |
152 | "VerifyCAFile" => undef | |
153 | } | |
154 | ``` | |
155 | ||
156 | ## Adding a test to the test harness | |
157 | ||
158 | Add your configuration file to `test/recipes/80-test_ssl_new.t`. | |
159 | ||
160 | ## Running the tests with the test harness | |
161 | ||
162 | ``` | |
163 | HARNESS_VERBOSE=yes make TESTS=test_ssl_new test | |
164 | ``` | |
165 | ||
166 | ## Running a test manually | |
167 | ||
168 | These steps are only needed during development. End users should run `make test` | |
169 | or follow the instructions above to run the SSL test suite. | |
170 | ||
171 | To run an SSL test manually from the command line, the `TEST_CERTS_DIR` | |
172 | environment variable to point to the location of the certs. E.g., from the root | |
173 | OpenSSL directory, do | |
174 | ||
175 | ``` | |
176 | $ TEST_CERTS_DIR=test/certs test/ssl_test test/ssl-tests/01-simple.conf | |
177 | ``` | |
178 | ||
179 | or for shared builds | |
180 | ||
181 | ``` | |
182 | $ TEST_CERTS_DIR=test/certs util/shlib_wrap.sh test/ssl_test \ | |
183 | test/ssl-tests/01-simple.conf | |
184 | ``` | |
185 | ||
186 | Note that the test expectations sometimes depend on the Configure settings. For | |
187 | example, the negotiated protocol depends on the set of available (enabled) | |
188 | protocols: a build with `enable-ssl3` has different test expectations than a | |
189 | build with `no-ssl3`. | |
190 | ||
191 | The Perl test harness automatically generates expected outputs, so users who | |
192 | just run `make test` do not need any extra steps. | |
193 | ||
194 | However, when running a test manually, keep in mind that the repository version | |
195 | of the generated `test/ssl-tests/*.conf` correspond to expected outputs in with | |
196 | the default Configure options. To run `ssl_test` manually from the command line | |
197 | in a build with a different configuration, you may need to generate the right | |
198 | `*.conf` file from the `*.conf.in` input first. |