]>
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 | |
64 | - AcceptAll - accepts all certificates. | |
65 | - RejectAll - rejects all certificates. | |
66 | ||
5c753de6 TS |
67 | * ServerName - the server the client is expected to successfully connect to |
68 | - server1 - the initial context (default) | |
69 | - server2 - the secondary context | |
70 | ||
71 | * SessionTicketExpected - whether or not a session ticket is expected | |
72 | - Ignore - do not check for a session ticket (default) | |
73 | - Yes - a session ticket is expected | |
74 | - No - a session ticket is not expected | |
75 | - Broken - a special test case where the session ticket callback does not initialize crypto | |
76 | ||
453dfd8d EK |
77 | ## Configuring the client and server |
78 | ||
79 | The client and server configurations can be any valid `SSL_CTX` | |
80 | configurations. For details, see the manpages for `SSL_CONF_cmd`. | |
81 | ||
82 | Give your configurations as a dictionary of CONF commands, e.g. | |
83 | ||
84 | ``` | |
85 | server => { | |
86 | "CipherString" => "DEFAULT", | |
87 | "MinProtocol" => "TLSv1", | |
88 | } | |
89 | ``` | |
90 | ||
5c753de6 TS |
91 | A server2 section may optionally be defined to configure a secondary |
92 | context that is selected via the ServerName test option. If the server2 | |
93 | section is not configured, then the configuration matches server. | |
94 | ||
453dfd8d EK |
95 | ### Default server and client configurations |
96 | ||
97 | The default server certificate and CA files are added to the configurations | |
98 | automatically. Server certificate verification is requested by default. | |
99 | ||
100 | You can override these options by redefining them: | |
101 | ||
102 | ``` | |
103 | client => { | |
104 | "VerifyCAFile" => "/path/to/custom/file" | |
105 | } | |
106 | ``` | |
107 | ||
108 | or by deleting them | |
109 | ||
110 | ``` | |
111 | client => { | |
112 | "VerifyCAFile" => undef | |
113 | } | |
114 | ``` | |
115 | ||
116 | ## Adding a test to the test harness | |
117 | ||
118 | Add your configuration file to `test/recipes/80-test_ssl_new.t`. | |
119 | ||
120 | ## Running the tests with the test harness | |
121 | ||
122 | ``` | |
123 | HARNESS_VERBOSE=yes make TESTS=test_ssl_new test | |
124 | ``` | |
125 | ||
126 | ## Running a test manually | |
127 | ||
128 | These steps are only needed during development. End users should run `make test` | |
129 | or follow the instructions above to run the SSL test suite. | |
130 | ||
131 | To run an SSL test manually from the command line, the `TEST_CERTS_DIR` | |
132 | environment variable to point to the location of the certs. E.g., from the root | |
133 | OpenSSL directory, do | |
134 | ||
135 | ``` | |
136 | $ TEST_CERTS_DIR=test/certs test/ssl_test test/ssl-tests/01-simple.conf | |
137 | ``` | |
138 | ||
139 | or for shared builds | |
140 | ||
141 | ``` | |
142 | $ TEST_CERTS_DIR=test/certs util/shlib_wrap.sh test/ssl_test \ | |
143 | test/ssl-tests/01-simple.conf | |
144 | ``` | |
145 | ||
146 | Note that the test expectations sometimes depend on the Configure settings. For | |
147 | example, the negotiated protocol depends on the set of available (enabled) | |
148 | protocols: a build with `enable-ssl3` has different test expectations than a | |
149 | build with `no-ssl3`. | |
150 | ||
151 | The Perl test harness automatically generates expected outputs, so users who | |
152 | just run `make test` do not need any extra steps. | |
153 | ||
154 | However, when running a test manually, keep in mind that the repository version | |
155 | of the generated `test/ssl-tests/*.conf` correspond to expected outputs in with | |
156 | the default Configure options. To run `ssl_test` manually from the command line | |
157 | in a build with a different configuration, you may need to generate the right | |
158 | `*.conf` file from the `*.conf.in` input first. |