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