]>
Commit | Line | Data |
---|---|---|
c3ed3b6e DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | s_client - SSL/TLS client program | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<s_client> | |
a32fc687 | 11 | [B<-connect host:port>] |
fc1d88f0 | 12 | [B<-servername name>] |
b46c3e9b | 13 | [B<-verify depth>] |
4e6c12f3 | 14 | [B<-verify_return_error>] |
c3ed3b6e | 15 | [B<-cert filename>] |
826a42a0 | 16 | [B<-certform DER|PEM>] |
c3ed3b6e | 17 | [B<-key filename>] |
826a42a0 DSH |
18 | [B<-keyform DER|PEM>] |
19 | [B<-pass arg>] | |
c3ed3b6e DSH |
20 | [B<-CApath directory>] |
21 | [B<-CAfile filename>] | |
6d3d5793 | 22 | [B<-trusted_first>] |
e42d84be HK |
23 | [B<-attime timestamp>] |
24 | [B<-check_ss_sig>] | |
25 | [B<-crl_check>] | |
26 | [B<-crl_check_all>] | |
27 | [B<-explicit_policy>] | |
28 | [B<-extended_crl>] | |
29 | [B<-ignore_critical>] | |
30 | [B<-inhibit_any>] | |
31 | [B<-inhibit_map>] | |
32 | [B<-issuer_checks>] | |
33 | [B<-partial_chain>] | |
34 | [B<-policy arg>] | |
35 | [B<-policy_check>] | |
36 | [B<-policy_print>] | |
37 | [B<-purpose purpose>] | |
38 | [B<-suiteB_128>] | |
39 | [B<-suiteB_128_only>] | |
40 | [B<-suiteB_192>] | |
41 | [B<-trusted_first>] | |
42 | [B<-use_deltas>] | |
43 | [B<-verify_depth num>] | |
44 | [B<-verify_email email>] | |
45 | [B<-verify_hostname hostname>] | |
46 | [B<-verify_ip ip>] | |
47 | [B<-verify_name name>] | |
48 | [B<-x509_strict>] | |
c3ed3b6e DSH |
49 | [B<-reconnect>] |
50 | [B<-pause>] | |
51 | [B<-showcerts>] | |
52 | [B<-debug>] | |
1d8634b1 | 53 | [B<-msg>] |
c3ed3b6e DSH |
54 | [B<-nbio_test>] |
55 | [B<-state>] | |
56 | [B<-nbio>] | |
57 | [B<-crlf>] | |
ce301b6b | 58 | [B<-ign_eof>] |
fc1d88f0 | 59 | [B<-no_ign_eof>] |
c3ed3b6e DSH |
60 | [B<-quiet>] |
61 | [B<-ssl2>] | |
62 | [B<-ssl3>] | |
63 | [B<-tls1>] | |
64 | [B<-no_ssl2>] | |
65 | [B<-no_ssl3>] | |
66 | [B<-no_tls1>] | |
67 | [B<-bugs>] | |
68 | [B<-cipher cipherlist>] | |
fc1d88f0 | 69 | [B<-serverpref>] |
e986704d | 70 | [B<-starttls protocol>] |
b98af49d | 71 | [B<-xmpphost hostname>] |
5270e702 | 72 | [B<-engine id>] |
d24a9c8f DSH |
73 | [B<-tlsextdebug>] |
74 | [B<-no_ticket>] | |
75 | [B<-sess_out filename>] | |
76 | [B<-sess_in filename>] | |
52b621db | 77 | [B<-rand file(s)>] |
9cd50f73 | 78 | [B<-serverinfo types>] |
cba3f1c7 | 79 | [B<-status>] |
7efd0e77 | 80 | [B<-nextprotoneg protocols>] |
c3ed3b6e DSH |
81 | |
82 | =head1 DESCRIPTION | |
83 | ||
84 | The B<s_client> command implements a generic SSL/TLS client which connects | |
85 | to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for | |
86 | SSL servers. | |
87 | ||
88 | =head1 OPTIONS | |
89 | ||
765b4137 DSH |
90 | In addition to the options below the B<s_client> utility also supports the |
91 | common and client only options documented in the | |
13cfb043 DSH |
92 | in the L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)/SUPPORTED COMMAND LINE COMMANDS> |
93 | manual page. | |
765b4137 | 94 | |
c3ed3b6e DSH |
95 | =over 4 |
96 | ||
97 | =item B<-connect host:port> | |
98 | ||
99 | This specifies the host and optional port to connect to. If not specified | |
100 | then an attempt is made to connect to the local host on port 4433. | |
101 | ||
fc1d88f0 RS |
102 | =item B<-servername name> |
103 | ||
104 | Set the TLS SNI (Server Name Indication) extension in the ClientHello message. | |
105 | ||
c3ed3b6e DSH |
106 | =item B<-cert certname> |
107 | ||
108 | The certificate to use, if one is requested by the server. The default is | |
109 | not to use a certificate. | |
110 | ||
826a42a0 DSH |
111 | =item B<-certform format> |
112 | ||
113 | The certificate format to use: DER or PEM. PEM is the default. | |
114 | ||
c3ed3b6e DSH |
115 | =item B<-key keyfile> |
116 | ||
117 | The private key to use. If not specified then the certificate file will | |
118 | be used. | |
119 | ||
826a42a0 DSH |
120 | =item B<-keyform format> |
121 | ||
122 | The private format to use: DER or PEM. PEM is the default. | |
123 | ||
124 | =item B<-pass arg> | |
125 | ||
126 | the private key password source. For more information about the format of B<arg> | |
127 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. | |
128 | ||
c3ed3b6e DSH |
129 | =item B<-verify depth> |
130 | ||
131 | The verify depth to use. This specifies the maximum length of the | |
132 | server certificate chain and turns on server certificate verification. | |
133 | Currently the verify operation continues after errors so all the problems | |
134 | with a certificate chain can be seen. As a side effect the connection | |
135 | will never fail due to a server certificate verify failure. | |
136 | ||
4e6c12f3 DSH |
137 | =item B<-verify_return_error> |
138 | ||
139 | Return verification errors instead of continuing. This will typically | |
140 | abort the handshake with a fatal error. | |
141 | ||
c3ed3b6e DSH |
142 | =item B<-CApath directory> |
143 | ||
144 | The directory to use for server certificate verification. This directory | |
145 | must be in "hash format", see B<verify> for more information. These are | |
146 | also used when building the client certificate chain. | |
147 | ||
148 | =item B<-CAfile file> | |
149 | ||
150 | A file containing trusted certificates to use during server authentication | |
151 | and to use when attempting to build the client certificate chain. | |
152 | ||
e42d84be HK |
153 | =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, |
154 | B<explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, | |
155 | B<-inhibit_map>, B<-issuer_checks>, B<-partial_chain>, B<-policy>, | |
156 | B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, | |
157 | B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, | |
158 | B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>, | |
159 | B<-verify_name>, B<-x509_strict> | |
e5fa864f | 160 | |
6d3d5793 | 161 | Set various certificate chain valiadition options. See the |
e5fa864f DSH |
162 | L<B<verify>|verify(1)> manual page for details. |
163 | ||
c3ed3b6e DSH |
164 | =item B<-reconnect> |
165 | ||
166 | reconnects to the same server 5 times using the same session ID, this can | |
167 | be used as a test that session caching is working. | |
168 | ||
169 | =item B<-pause> | |
170 | ||
171 | pauses 1 second between each read and write call. | |
172 | ||
173 | =item B<-showcerts> | |
174 | ||
175 | display the whole server certificate chain: normally only the server | |
176 | certificate itself is displayed. | |
177 | ||
178 | =item B<-prexit> | |
179 | ||
180 | print session information when the program exits. This will always attempt | |
181 | to print out information even if the connection fails. Normally information | |
182 | will only be printed out once if the connection succeeds. This option is useful | |
183 | because the cipher in use may be renegotiated or the connection may fail | |
184 | because a client certificate is required or is requested only after an | |
185 | attempt is made to access a certain URL. Note: the output produced by this | |
186 | option is not always accurate because a connection might never have been | |
187 | established. | |
188 | ||
189 | =item B<-state> | |
190 | ||
191 | prints out the SSL session states. | |
192 | ||
193 | =item B<-debug> | |
194 | ||
195 | print extensive debugging information including a hex dump of all traffic. | |
196 | ||
1d8634b1 BM |
197 | =item B<-msg> |
198 | ||
199 | show all protocol messages with hex dump. | |
200 | ||
8dbeb110 DSH |
201 | =item B<-trace> |
202 | ||
203 | show verbose trace output of protocol messages. OpenSSL needs to be compiled | |
204 | with B<enable-ssl-trace> for this option to work. | |
205 | ||
206 | =item B<-msgfile> | |
207 | ||
208 | file to send output of B<-msg> or B<-trace> to, default standard output. | |
209 | ||
c3ed3b6e DSH |
210 | =item B<-nbio_test> |
211 | ||
657e60fa | 212 | tests non-blocking I/O |
c3ed3b6e DSH |
213 | |
214 | =item B<-nbio> | |
215 | ||
657e60fa | 216 | turns on non-blocking I/O |
c3ed3b6e DSH |
217 | |
218 | =item B<-crlf> | |
219 | ||
220 | this option translated a line feed from the terminal into CR+LF as required | |
221 | by some servers. | |
222 | ||
ce301b6b RL |
223 | =item B<-ign_eof> |
224 | ||
225 | inhibit shutting down the connection when end of file is reached in the | |
226 | input. | |
227 | ||
c3ed3b6e DSH |
228 | =item B<-quiet> |
229 | ||
3b80e3aa | 230 | inhibit printing of session and certificate information. This implicitly |
ce301b6b | 231 | turns on B<-ign_eof> as well. |
c3ed3b6e | 232 | |
fc1d88f0 RS |
233 | =item B<-no_ign_eof> |
234 | ||
235 | shut down the connection when end of file is reached in the input. | |
236 | Can be used to override the implicit B<-ign_eof> after B<-quiet>. | |
237 | ||
ddac1974 NL |
238 | =item B<-psk_identity identity> |
239 | ||
240 | Use the PSK identity B<identity> when using a PSK cipher suite. | |
241 | ||
242 | =item B<-psk key> | |
243 | ||
244 | Use the PSK key B<key> when using a PSK cipher suite. The key is | |
245 | given as a hexadecimal number without leading 0x, for example -psk | |
246 | 1a2b3c4d. | |
247 | ||
c3ed3b6e DSH |
248 | =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> |
249 | ||
250 | these options disable the use of certain SSL or TLS protocols. By default | |
251 | the initial handshake uses a method which should be compatible with all | |
252 | servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. | |
253 | ||
254 | Unfortunately there are a lot of ancient and broken servers in use which | |
255 | cannot handle this technique and will fail to connect. Some servers only | |
256 | work if TLS is turned off with the B<-no_tls> option others will only | |
257 | support SSL v2 and may need the B<-ssl2> option. | |
258 | ||
259 | =item B<-bugs> | |
260 | ||
261 | there are several known bug in SSL and TLS implementations. Adding this | |
262 | option enables various workarounds. | |
263 | ||
765b4137 DSH |
264 | =item B<-brief> |
265 | ||
266 | only provide a brief summary of connection parameters instead of the | |
267 | normal verbose output. | |
268 | ||
c3ed3b6e DSH |
269 | =item B<-cipher cipherlist> |
270 | ||
fabce041 DSH |
271 | this allows the cipher list sent by the client to be modified. Although |
272 | the server determines which cipher suite is used it should take the first | |
273 | supported cipher in the list sent by the client. See the B<ciphers> | |
274 | command for more information. | |
c3ed3b6e | 275 | |
fc1d88f0 RS |
276 | =item B<-serverpref> |
277 | ||
278 | use the server's cipher preferences; only used for SSLV2. | |
279 | ||
e986704d RL |
280 | =item B<-starttls protocol> |
281 | ||
282 | send the protocol-specific message(s) to switch to TLS for communication. | |
283 | B<protocol> is a keyword for the intended protocol. Currently, the only | |
50f307a9 | 284 | supported keywords are "smtp", "pop3", "imap", "ftp" and "xmpp". |
e986704d | 285 | |
b98af49d CALP |
286 | =item B<-xmpphost hostname> |
287 | ||
288 | This option, when used with "-starttls xmpp", specifies the host for the | |
289 | "to" attribute of the stream element. | |
290 | If this option is not specified, then the host specified with "-connect" | |
291 | will be used. | |
292 | ||
d24a9c8f DSH |
293 | =item B<-tlsextdebug> |
294 | ||
295 | print out a hex dump of any TLS extensions received from the server. | |
296 | ||
297 | =item B<-no_ticket> | |
298 | ||
299 | disable RFC4507bis session ticket support. | |
300 | ||
301 | =item B<-sess_out filename> | |
302 | ||
303 | output SSL session to B<filename> | |
304 | ||
305 | =item B<-sess_in sess.pem> | |
306 | ||
307 | load SSL session from B<filename>. The client will attempt to resume a | |
308 | connection from this session. | |
309 | ||
5270e702 RL |
310 | =item B<-engine id> |
311 | ||
e5fa864f | 312 | specifying an engine (by its unique B<id> string) will cause B<s_client> |
5270e702 RL |
313 | to attempt to obtain a functional reference to the specified engine, |
314 | thus initialising it if needed. The engine will then be set as the default | |
315 | for all available algorithms. | |
316 | ||
52b621db LJ |
317 | =item B<-rand file(s)> |
318 | ||
319 | a file or files containing random data used to seed the random number | |
320 | generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). | |
321 | Multiple files can be specified separated by a OS-dependent character. | |
322 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for | |
323 | all others. | |
324 | ||
9cd50f73 T |
325 | =item B<-serverinfo types> |
326 | ||
327 | a list of comma-separated TLS Extension Types (numbers between 0 and | |
328 | 65535). Each type will be sent as an empty ClientHello TLS Extension. | |
329 | The server's response (if any) will be encoded and displayed as a PEM | |
330 | file. | |
331 | ||
cba3f1c7 DSH |
332 | =item B<-status> |
333 | ||
334 | sends a certificate status request to the server (OCSP stapling). The server | |
335 | response (if any) is printed out. | |
336 | ||
7efd0e77 HK |
337 | =item B<-nextprotoneg protocols> |
338 | ||
339 | enable Next Protocol Negotiation TLS extension and provide a list of | |
340 | comma-separated protocol names that the client should advertise | |
341 | support for. The list should contain most wanted protocols first. | |
342 | Protocol names are printable ASCII strings, for example "http/1.1" or | |
343 | "spdy/3". | |
344 | Empty list of protocols is treated specially and will cause the client to | |
345 | advertise support for the TLS extension but disconnect just after | |
346 | reciving ServerHello with a list of server supported protocols. | |
347 | ||
efeca6aa UM |
348 | =back |
349 | ||
c3ed3b6e DSH |
350 | =head1 CONNECTED COMMANDS |
351 | ||
352 | If a connection is established with an SSL server then any data received | |
353 | from the server is displayed and any key presses will be sent to the | |
ce301b6b | 354 | server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> |
3b80e3aa | 355 | have been given), the session will be renegotiated if the line begins with an |
ce301b6b RL |
356 | B<R>, and if the line begins with a B<Q> or if end of file is reached, the |
357 | connection will be closed down. | |
c3ed3b6e DSH |
358 | |
359 | =head1 NOTES | |
360 | ||
361 | B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP | |
362 | server the command: | |
363 | ||
364 | openssl s_client -connect servername:443 | |
365 | ||
366 | would typically be used (https uses port 443). If the connection succeeds | |
367 | then an HTTP command can be given such as "GET /" to retrieve a web page. | |
368 | ||
369 | If the handshake fails then there are several possible causes, if it is | |
370 | nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, | |
a32fc687 | 371 | B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried |
c3ed3b6e DSH |
372 | in case it is a buggy server. In particular you should play with these |
373 | options B<before> submitting a bug report to an OpenSSL mailing list. | |
374 | ||
375 | A frequent problem when attempting to get client certificates working | |
376 | is that a web client complains it has no certificates or gives an empty | |
377 | list to choose from. This is normally because the server is not sending | |
378 | the clients certificate authority in its "acceptable CA list" when it | |
379 | requests a certificate. By using B<s_client> the CA list can be viewed | |
380 | and checked. However some servers only request client authentication | |
381 | after a specific URL is requested. To obtain the list in this case it | |
a32fc687 | 382 | is necessary to use the B<-prexit> option and send an HTTP request |
c3ed3b6e DSH |
383 | for an appropriate page. |
384 | ||
385 | If a certificate is specified on the command line using the B<-cert> | |
386 | option it will not be used unless the server specifically requests | |
387 | a client certificate. Therefor merely including a client certificate | |
388 | on the command line is no guarantee that the certificate works. | |
389 | ||
390 | If there are problems verifying a server certificate then the | |
391 | B<-showcerts> option can be used to show the whole chain. | |
392 | ||
d24a9c8f DSH |
393 | Since the SSLv23 client hello cannot include compression methods or extensions |
394 | these will only be supported if its use is disabled, for example by using the | |
395 | B<-no_sslv2> option. | |
396 | ||
4e6c12f3 DSH |
397 | The B<s_client> utility is a test tool and is designed to continue the |
398 | handshake after any certificate verification errors. As a result it will | |
399 | accept any certificate chain (trusted or not) sent by the peer. None test | |
400 | applications should B<not> do this as it makes them vulnerable to a MITM | |
401 | attack. This behaviour can be changed by with the B<-verify_return_error> | |
402 | option: any verify errors are then returned aborting the handshake. | |
403 | ||
c3ed3b6e DSH |
404 | =head1 BUGS |
405 | ||
406 | Because this program has a lot of options and also because some of | |
a2151c5b | 407 | the techniques used are rather old, the C source of s_client is rather |
c3ed3b6e DSH |
408 | hard to read and not a model of how things should be done. A typical |
409 | SSL client program would be much simpler. | |
410 | ||
c3ed3b6e DSH |
411 | The B<-prexit> option is a bit of a hack. We should really report |
412 | information whenever a session is renegotiated. | |
413 | ||
414 | =head1 SEE ALSO | |
415 | ||
bb075f88 | 416 | L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> |
c3ed3b6e DSH |
417 | |
418 | =cut |