1 | =pod
|
---|
2 |
|
---|
3 | =head1 NAME
|
---|
4 |
|
---|
5 | openssl-s_client,
|
---|
6 | s_client - SSL/TLS client program
|
---|
7 |
|
---|
8 | =head1 SYNOPSIS
|
---|
9 |
|
---|
10 | B<openssl> B<s_client>
|
---|
11 | [B<-help>]
|
---|
12 | [B<-connect host:port>]
|
---|
13 | [B<-bind host:port>]
|
---|
14 | [B<-proxy host:port>]
|
---|
15 | [B<-unix path>]
|
---|
16 | [B<-4>]
|
---|
17 | [B<-6>]
|
---|
18 | [B<-servername name>]
|
---|
19 | [B<-noservername>]
|
---|
20 | [B<-verify depth>]
|
---|
21 | [B<-verify_return_error>]
|
---|
22 | [B<-cert filename>]
|
---|
23 | [B<-certform DER|PEM>]
|
---|
24 | [B<-key filename>]
|
---|
25 | [B<-keyform DER|PEM>]
|
---|
26 | [B<-cert_chain filename>]
|
---|
27 | [B<-build_chain>]
|
---|
28 | [B<-xkey>]
|
---|
29 | [B<-xcert>]
|
---|
30 | [B<-xchain>]
|
---|
31 | [B<-xchain_build>]
|
---|
32 | [B<-xcertform PEM|DER>]
|
---|
33 | [B<-xkeyform PEM|DER>]
|
---|
34 | [B<-pass arg>]
|
---|
35 | [B<-CApath directory>]
|
---|
36 | [B<-CAfile filename>]
|
---|
37 | [B<-chainCApath directory>]
|
---|
38 | [B<-chainCAfile filename>]
|
---|
39 | [B<-no-CAfile>]
|
---|
40 | [B<-no-CApath>]
|
---|
41 | [B<-requestCAfile filename>]
|
---|
42 | [B<-dane_tlsa_domain domain>]
|
---|
43 | [B<-dane_tlsa_rrdata rrdata>]
|
---|
44 | [B<-dane_ee_no_namechecks>]
|
---|
45 | [B<-attime timestamp>]
|
---|
46 | [B<-check_ss_sig>]
|
---|
47 | [B<-crl_check>]
|
---|
48 | [B<-crl_check_all>]
|
---|
49 | [B<-explicit_policy>]
|
---|
50 | [B<-extended_crl>]
|
---|
51 | [B<-ignore_critical>]
|
---|
52 | [B<-inhibit_any>]
|
---|
53 | [B<-inhibit_map>]
|
---|
54 | [B<-no_check_time>]
|
---|
55 | [B<-partial_chain>]
|
---|
56 | [B<-policy arg>]
|
---|
57 | [B<-policy_check>]
|
---|
58 | [B<-policy_print>]
|
---|
59 | [B<-purpose purpose>]
|
---|
60 | [B<-suiteB_128>]
|
---|
61 | [B<-suiteB_128_only>]
|
---|
62 | [B<-suiteB_192>]
|
---|
63 | [B<-trusted_first>]
|
---|
64 | [B<-no_alt_chains>]
|
---|
65 | [B<-use_deltas>]
|
---|
66 | [B<-auth_level num>]
|
---|
67 | [B<-nameopt option>]
|
---|
68 | [B<-verify_depth num>]
|
---|
69 | [B<-verify_email email>]
|
---|
70 | [B<-verify_hostname hostname>]
|
---|
71 | [B<-verify_ip ip>]
|
---|
72 | [B<-verify_name name>]
|
---|
73 | [B<-build_chain>]
|
---|
74 | [B<-x509_strict>]
|
---|
75 | [B<-reconnect>]
|
---|
76 | [B<-showcerts>]
|
---|
77 | [B<-debug>]
|
---|
78 | [B<-msg>]
|
---|
79 | [B<-nbio_test>]
|
---|
80 | [B<-state>]
|
---|
81 | [B<-nbio>]
|
---|
82 | [B<-crlf>]
|
---|
83 | [B<-ign_eof>]
|
---|
84 | [B<-no_ign_eof>]
|
---|
85 | [B<-psk_identity identity>]
|
---|
86 | [B<-psk key>]
|
---|
87 | [B<-psk_session file>]
|
---|
88 | [B<-quiet>]
|
---|
89 | [B<-ssl3>]
|
---|
90 | [B<-tls1>]
|
---|
91 | [B<-tls1_1>]
|
---|
92 | [B<-tls1_2>]
|
---|
93 | [B<-tls1_3>]
|
---|
94 | [B<-no_ssl3>]
|
---|
95 | [B<-no_tls1>]
|
---|
96 | [B<-no_tls1_1>]
|
---|
97 | [B<-no_tls1_2>]
|
---|
98 | [B<-no_tls1_3>]
|
---|
99 | [B<-dtls>]
|
---|
100 | [B<-dtls1>]
|
---|
101 | [B<-dtls1_2>]
|
---|
102 | [B<-sctp>]
|
---|
103 | [B<-sctp_label_bug>]
|
---|
104 | [B<-fallback_scsv>]
|
---|
105 | [B<-async>]
|
---|
106 | [B<-max_send_frag>]
|
---|
107 | [B<-split_send_frag>]
|
---|
108 | [B<-max_pipelines>]
|
---|
109 | [B<-read_buf>]
|
---|
110 | [B<-bugs>]
|
---|
111 | [B<-comp>]
|
---|
112 | [B<-no_comp>]
|
---|
113 | [B<-allow_no_dhe_kex>]
|
---|
114 | [B<-sigalgs sigalglist>]
|
---|
115 | [B<-curves curvelist>]
|
---|
116 | [B<-cipher cipherlist>]
|
---|
117 | [B<-ciphersuites val>]
|
---|
118 | [B<-serverpref>]
|
---|
119 | [B<-starttls protocol>]
|
---|
120 | [B<-xmpphost hostname>]
|
---|
121 | [B<-name hostname>]
|
---|
122 | [B<-engine id>]
|
---|
123 | [B<-tlsextdebug>]
|
---|
124 | [B<-no_ticket>]
|
---|
125 | [B<-sess_out filename>]
|
---|
126 | [B<-sess_in filename>]
|
---|
127 | [B<-rand file...>]
|
---|
128 | [B<-writerand file>]
|
---|
129 | [B<-serverinfo types>]
|
---|
130 | [B<-status>]
|
---|
131 | [B<-alpn protocols>]
|
---|
132 | [B<-nextprotoneg protocols>]
|
---|
133 | [B<-ct>]
|
---|
134 | [B<-noct>]
|
---|
135 | [B<-ctlogfile>]
|
---|
136 | [B<-keylogfile file>]
|
---|
137 | [B<-early_data file>]
|
---|
138 | [B<-enable_pha>]
|
---|
139 | [B<target>]
|
---|
140 |
|
---|
141 | =head1 DESCRIPTION
|
---|
142 |
|
---|
143 | The B<s_client> command implements a generic SSL/TLS client which connects
|
---|
144 | to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
|
---|
145 | SSL servers.
|
---|
146 |
|
---|
147 | =head1 OPTIONS
|
---|
148 |
|
---|
149 | In addition to the options below the B<s_client> utility also supports the
|
---|
150 | common and client only options documented
|
---|
151 | in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
|
---|
152 | manual page.
|
---|
153 |
|
---|
154 | =over 4
|
---|
155 |
|
---|
156 | =item B<-help>
|
---|
157 |
|
---|
158 | Print out a usage message.
|
---|
159 |
|
---|
160 | =item B<-connect host:port>
|
---|
161 |
|
---|
162 | This specifies the host and optional port to connect to. It is possible to
|
---|
163 | select the host and port using the optional target positional argument instead.
|
---|
164 | If neither this nor the target positional argument are specified then an attempt
|
---|
165 | is made to connect to the local host on port 4433.
|
---|
166 |
|
---|
167 | =item B<-bind host:port>]
|
---|
168 |
|
---|
169 | This specifies the host address and or port to bind as the source for the
|
---|
170 | connection. For Unix-domain sockets the port is ignored and the host is
|
---|
171 | used as the source socket address.
|
---|
172 |
|
---|
173 | =item B<-proxy host:port>
|
---|
174 |
|
---|
175 | When used with the B<-connect> flag, the program uses the host and port
|
---|
176 | specified with this flag and issues an HTTP CONNECT command to connect
|
---|
177 | to the desired server.
|
---|
178 |
|
---|
179 | =item B<-unix path>
|
---|
180 |
|
---|
181 | Connect over the specified Unix-domain socket.
|
---|
182 |
|
---|
183 | =item B<-4>
|
---|
184 |
|
---|
185 | Use IPv4 only.
|
---|
186 |
|
---|
187 | =item B<-6>
|
---|
188 |
|
---|
189 | Use IPv6 only.
|
---|
190 |
|
---|
191 | =item B<-servername name>
|
---|
192 |
|
---|
193 | Set the TLS SNI (Server Name Indication) extension in the ClientHello message to
|
---|
194 | the given value.
|
---|
195 | If B<-servername> is not provided, the TLS SNI extension will be populated with
|
---|
196 | the name given to B<-connect> if it follows a DNS name format. If B<-connect> is
|
---|
197 | not provided either, the SNI is set to "localhost".
|
---|
198 | This is the default since OpenSSL 1.1.1.
|
---|
199 |
|
---|
200 | Even though SNI should normally be a DNS name and not an IP address, if
|
---|
201 | B<-servername> is provided then that name will be sent, regardless of whether
|
---|
202 | it is a DNS name or not.
|
---|
203 |
|
---|
204 | This option cannot be used in conjunction with B<-noservername>.
|
---|
205 |
|
---|
206 | =item B<-noservername>
|
---|
207 |
|
---|
208 | Suppresses sending of the SNI (Server Name Indication) extension in the
|
---|
209 | ClientHello message. Cannot be used in conjunction with the B<-servername> or
|
---|
210 | <-dane_tlsa_domain> options.
|
---|
211 |
|
---|
212 | =item B<-cert certname>
|
---|
213 |
|
---|
214 | The certificate to use, if one is requested by the server. The default is
|
---|
215 | not to use a certificate.
|
---|
216 |
|
---|
217 | =item B<-certform format>
|
---|
218 |
|
---|
219 | The certificate format to use: DER or PEM. PEM is the default.
|
---|
220 |
|
---|
221 | =item B<-key keyfile>
|
---|
222 |
|
---|
223 | The private key to use. If not specified then the certificate file will
|
---|
224 | be used.
|
---|
225 |
|
---|
226 | =item B<-keyform format>
|
---|
227 |
|
---|
228 | The private format to use: DER or PEM. PEM is the default.
|
---|
229 |
|
---|
230 | =item B<-cert_chain>
|
---|
231 |
|
---|
232 | A file containing trusted certificates to use when attempting to build the
|
---|
233 | client/server certificate chain related to the certificate specified via the
|
---|
234 | B<-cert> option.
|
---|
235 |
|
---|
236 | =item B<-build_chain>
|
---|
237 |
|
---|
238 | Specify whether the application should build the certificate chain to be
|
---|
239 | provided to the server.
|
---|
240 |
|
---|
241 | =item B<-xkey infile>, B<-xcert infile>, B<-xchain>
|
---|
242 |
|
---|
243 | Specify an extra certificate, private key and certificate chain. These behave
|
---|
244 | in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When
|
---|
245 | specified, the callback returning the first valid chain will be in use by the
|
---|
246 | client.
|
---|
247 |
|
---|
248 | =item B<-xchain_build>
|
---|
249 |
|
---|
250 | Specify whether the application should build the certificate chain to be
|
---|
251 | provided to the server for the extra certificates provided via B<-xkey infile>,
|
---|
252 | B<-xcert infile>, B<-xchain> options.
|
---|
253 |
|
---|
254 | =item B<-xcertform PEM|DER>, B<-xkeyform PEM|DER>
|
---|
255 |
|
---|
256 | Extra certificate and private key format respectively.
|
---|
257 |
|
---|
258 | =item B<-pass arg>
|
---|
259 |
|
---|
260 | the private key password source. For more information about the format of B<arg>
|
---|
261 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
|
---|
262 |
|
---|
263 | =item B<-verify depth>
|
---|
264 |
|
---|
265 | The verify depth to use. This specifies the maximum length of the
|
---|
266 | server certificate chain and turns on server certificate verification.
|
---|
267 | Currently the verify operation continues after errors so all the problems
|
---|
268 | with a certificate chain can be seen. As a side effect the connection
|
---|
269 | will never fail due to a server certificate verify failure.
|
---|
270 |
|
---|
271 | =item B<-verify_return_error>
|
---|
272 |
|
---|
273 | Return verification errors instead of continuing. This will typically
|
---|
274 | abort the handshake with a fatal error.
|
---|
275 |
|
---|
276 | =item B<-nameopt option>
|
---|
277 |
|
---|
278 | Option which determines how the subject or issuer names are displayed. The
|
---|
279 | B<option> argument can be a single option or multiple options separated by
|
---|
280 | commas. Alternatively the B<-nameopt> switch may be used more than once to
|
---|
281 | set multiple options. See the L<x509(1)> manual page for details.
|
---|
282 |
|
---|
283 | =item B<-CApath directory>
|
---|
284 |
|
---|
285 | The directory to use for server certificate verification. This directory
|
---|
286 | must be in "hash format", see L<verify(1)> for more information. These are
|
---|
287 | also used when building the client certificate chain.
|
---|
288 |
|
---|
289 | =item B<-CAfile file>
|
---|
290 |
|
---|
291 | A file containing trusted certificates to use during server authentication
|
---|
292 | and to use when attempting to build the client certificate chain.
|
---|
293 |
|
---|
294 | =item B<-chainCApath directory>
|
---|
295 |
|
---|
296 | The directory to use for building the chain provided to the server. This
|
---|
297 | directory must be in "hash format", see L<verify(1)> for more information.
|
---|
298 |
|
---|
299 | =item B<-chainCAfile file>
|
---|
300 |
|
---|
301 | A file containing trusted certificates to use when attempting to build the
|
---|
302 | client certificate chain.
|
---|
303 |
|
---|
304 | =item B<-no-CAfile>
|
---|
305 |
|
---|
306 | Do not load the trusted CA certificates from the default file location
|
---|
307 |
|
---|
308 | =item B<-no-CApath>
|
---|
309 |
|
---|
310 | Do not load the trusted CA certificates from the default directory location
|
---|
311 |
|
---|
312 | =item B<-requestCAfile file>
|
---|
313 |
|
---|
314 | A file containing a list of certificates whose subject names will be sent
|
---|
315 | to the server in the B<certificate_authorities> extension. Only supported
|
---|
316 | for TLS 1.3
|
---|
317 |
|
---|
318 | =item B<-dane_tlsa_domain domain>
|
---|
319 |
|
---|
320 | Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
|
---|
321 | TLSA base domain which becomes the default SNI hint and the primary
|
---|
322 | reference identifier for hostname checks. This must be used in
|
---|
323 | combination with at least one instance of the B<-dane_tlsa_rrdata>
|
---|
324 | option below.
|
---|
325 |
|
---|
326 | When DANE authentication succeeds, the diagnostic output will include
|
---|
327 | the lowest (closest to 0) depth at which a TLSA record authenticated
|
---|
328 | a chain certificate. When that TLSA record is a "2 1 0" trust
|
---|
329 | anchor public key that signed (rather than matched) the top-most
|
---|
330 | certificate of the chain, the result is reported as "TA public key
|
---|
331 | verified". Otherwise, either the TLSA record "matched TA certificate"
|
---|
332 | at a positive depth or else "matched EE certificate" at depth 0.
|
---|
333 |
|
---|
334 | =item B<-dane_tlsa_rrdata rrdata>
|
---|
335 |
|
---|
336 | Use one or more times to specify the RRDATA fields of the DANE TLSA
|
---|
337 | RRset associated with the target service. The B<rrdata> value is
|
---|
338 | specified in "presentation form", that is four whitespace separated
|
---|
339 | fields that specify the usage, selector, matching type and associated
|
---|
340 | data, with the last of these encoded in hexadecimal. Optional
|
---|
341 | whitespace is ignored in the associated data field. For example:
|
---|
342 |
|
---|
343 | $ openssl s_client -brief -starttls smtp \
|
---|
344 | -connect smtp.example.com:25 \
|
---|
345 | -dane_tlsa_domain smtp.example.com \
|
---|
346 | -dane_tlsa_rrdata "2 1 1
|
---|
347 | B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
|
---|
348 | -dane_tlsa_rrdata "2 1 1
|
---|
349 | 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
|
---|
350 | ...
|
---|
351 | Verification: OK
|
---|
352 | Verified peername: smtp.example.com
|
---|
353 | DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
|
---|
354 | ...
|
---|
355 |
|
---|
356 | =item B<-dane_ee_no_namechecks>
|
---|
357 |
|
---|
358 | This disables server name checks when authenticating via DANE-EE(3) TLSA
|
---|
359 | records.
|
---|
360 | For some applications, primarily web browsers, it is not safe to disable name
|
---|
361 | checks due to "unknown key share" attacks, in which a malicious server can
|
---|
362 | convince a client that a connection to a victim server is instead a secure
|
---|
363 | connection to the malicious server.
|
---|
364 | The malicious server may then be able to violate cross-origin scripting
|
---|
365 | restrictions.
|
---|
366 | Thus, despite the text of RFC7671, name checks are by default enabled for
|
---|
367 | DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
|
---|
368 | to do so.
|
---|
369 | In particular, SMTP and XMPP clients should set this option as SRV and MX
|
---|
370 | records already make it possible for a remote domain to redirect client
|
---|
371 | connections to any server of its choice, and in any case SMTP and XMPP clients
|
---|
372 | do not execute scripts downloaded from remote servers.
|
---|
373 |
|
---|
374 | =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
|
---|
375 | B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
|
---|
376 | B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
|
---|
377 | B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
|
---|
378 | B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
|
---|
379 | B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
|
---|
380 | B<-verify_ip>, B<-verify_name>, B<-x509_strict>
|
---|
381 |
|
---|
382 | Set various certificate chain validation options. See the
|
---|
383 | L<verify(1)> manual page for details.
|
---|
384 |
|
---|
385 | =item B<-reconnect>
|
---|
386 |
|
---|
387 | Reconnects to the same server 5 times using the same session ID, this can
|
---|
388 | be used as a test that session caching is working.
|
---|
389 |
|
---|
390 | =item B<-showcerts>
|
---|
391 |
|
---|
392 | Displays the server certificate list as sent by the server: it only consists of
|
---|
393 | certificates the server has sent (in the order the server has sent them). It is
|
---|
394 | B<not> a verified chain.
|
---|
395 |
|
---|
396 | =item B<-prexit>
|
---|
397 |
|
---|
398 | Print session information when the program exits. This will always attempt
|
---|
399 | to print out information even if the connection fails. Normally information
|
---|
400 | will only be printed out once if the connection succeeds. This option is useful
|
---|
401 | because the cipher in use may be renegotiated or the connection may fail
|
---|
402 | because a client certificate is required or is requested only after an
|
---|
403 | attempt is made to access a certain URL. Note: the output produced by this
|
---|
404 | option is not always accurate because a connection might never have been
|
---|
405 | established.
|
---|
406 |
|
---|
407 | =item B<-state>
|
---|
408 |
|
---|
409 | Prints out the SSL session states.
|
---|
410 |
|
---|
411 | =item B<-debug>
|
---|
412 |
|
---|
413 | Print extensive debugging information including a hex dump of all traffic.
|
---|
414 |
|
---|
415 | =item B<-msg>
|
---|
416 |
|
---|
417 | Show all protocol messages with hex dump.
|
---|
418 |
|
---|
419 | =item B<-trace>
|
---|
420 |
|
---|
421 | Show verbose trace output of protocol messages. OpenSSL needs to be compiled
|
---|
422 | with B<enable-ssl-trace> for this option to work.
|
---|
423 |
|
---|
424 | =item B<-msgfile>
|
---|
425 |
|
---|
426 | File to send output of B<-msg> or B<-trace> to, default standard output.
|
---|
427 |
|
---|
428 | =item B<-nbio_test>
|
---|
429 |
|
---|
430 | Tests non-blocking I/O
|
---|
431 |
|
---|
432 | =item B<-nbio>
|
---|
433 |
|
---|
434 | Turns on non-blocking I/O
|
---|
435 |
|
---|
436 | =item B<-crlf>
|
---|
437 |
|
---|
438 | This option translated a line feed from the terminal into CR+LF as required
|
---|
439 | by some servers.
|
---|
440 |
|
---|
441 | =item B<-ign_eof>
|
---|
442 |
|
---|
443 | Inhibit shutting down the connection when end of file is reached in the
|
---|
444 | input.
|
---|
445 |
|
---|
446 | =item B<-quiet>
|
---|
447 |
|
---|
448 | Inhibit printing of session and certificate information. This implicitly
|
---|
449 | turns on B<-ign_eof> as well.
|
---|
450 |
|
---|
451 | =item B<-no_ign_eof>
|
---|
452 |
|
---|
453 | Shut down the connection when end of file is reached in the input.
|
---|
454 | Can be used to override the implicit B<-ign_eof> after B<-quiet>.
|
---|
455 |
|
---|
456 | =item B<-psk_identity identity>
|
---|
457 |
|
---|
458 | Use the PSK identity B<identity> when using a PSK cipher suite.
|
---|
459 | The default value is "Client_identity" (without the quotes).
|
---|
460 |
|
---|
461 | =item B<-psk key>
|
---|
462 |
|
---|
463 | Use the PSK key B<key> when using a PSK cipher suite. The key is
|
---|
464 | given as a hexadecimal number without leading 0x, for example -psk
|
---|
465 | 1a2b3c4d.
|
---|
466 | This option must be provided in order to use a PSK cipher.
|
---|
467 |
|
---|
468 | =item B<-psk_session file>
|
---|
469 |
|
---|
470 | Use the pem encoded SSL_SESSION data stored in B<file> as the basis of a PSK.
|
---|
471 | Note that this will only work if TLSv1.3 is negotiated.
|
---|
472 |
|
---|
473 | =item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
|
---|
474 |
|
---|
475 | These options require or disable the use of the specified SSL or TLS protocols.
|
---|
476 | By default B<s_client> will negotiate the highest mutually supported protocol
|
---|
477 | version.
|
---|
478 | When a specific TLS version is required, only that version will be offered to
|
---|
479 | and accepted from the server.
|
---|
480 | Note that not all protocols and flags may be available, depending on how
|
---|
481 | OpenSSL was built.
|
---|
482 |
|
---|
483 | =item B<-dtls>, B<-dtls1>, B<-dtls1_2>
|
---|
484 |
|
---|
485 | These options make B<s_client> use DTLS protocols instead of TLS.
|
---|
486 | With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
|
---|
487 | whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
|
---|
488 | respectively.
|
---|
489 |
|
---|
490 | =item B<-sctp>
|
---|
491 |
|
---|
492 | Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in
|
---|
493 | conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only
|
---|
494 | available where OpenSSL has support for SCTP enabled.
|
---|
495 |
|
---|
496 | =item B<-sctp_label_bug>
|
---|
497 |
|
---|
498 | Use the incorrect behaviour of older OpenSSL implementations when computing
|
---|
499 | endpoint-pair shared secrets for DTLS/SCTP. This allows communication with
|
---|
500 | older broken implementations but breaks interoperability with correct
|
---|
501 | implementations. Must be used in conjunction with B<-sctp>. This option is only
|
---|
502 | available where OpenSSL has support for SCTP enabled.
|
---|
503 |
|
---|
504 | =item B<-fallback_scsv>
|
---|
505 |
|
---|
506 | Send TLS_FALLBACK_SCSV in the ClientHello.
|
---|
507 |
|
---|
508 | =item B<-async>
|
---|
509 |
|
---|
510 | Switch on asynchronous mode. Cryptographic operations will be performed
|
---|
511 | asynchronously. This will only have an effect if an asynchronous capable engine
|
---|
512 | is also used via the B<-engine> option. For test purposes the dummy async engine
|
---|
513 | (dasync) can be used (if available).
|
---|
514 |
|
---|
515 | =item B<-max_send_frag int>
|
---|
516 |
|
---|
517 | The maximum size of data fragment to send.
|
---|
518 | See L<SSL_CTX_set_max_send_fragment(3)> for further information.
|
---|
519 |
|
---|
520 | =item B<-split_send_frag int>
|
---|
521 |
|
---|
522 | The size used to split data for encrypt pipelines. If more data is written in
|
---|
523 | one go than this value then it will be split into multiple pipelines, up to the
|
---|
524 | maximum number of pipelines defined by max_pipelines. This only has an effect if
|
---|
525 | a suitable cipher suite has been negotiated, an engine that supports pipelining
|
---|
526 | has been loaded, and max_pipelines is greater than 1. See
|
---|
527 | L<SSL_CTX_set_split_send_fragment(3)> for further information.
|
---|
528 |
|
---|
529 | =item B<-max_pipelines int>
|
---|
530 |
|
---|
531 | The maximum number of encrypt/decrypt pipelines to be used. This will only have
|
---|
532 | an effect if an engine has been loaded that supports pipelining (e.g. the dasync
|
---|
533 | engine) and a suitable cipher suite has been negotiated. The default value is 1.
|
---|
534 | See L<SSL_CTX_set_max_pipelines(3)> for further information.
|
---|
535 |
|
---|
536 | =item B<-read_buf int>
|
---|
537 |
|
---|
538 | The default read buffer size to be used for connections. This will only have an
|
---|
539 | effect if the buffer size is larger than the size that would otherwise be used
|
---|
540 | and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
|
---|
541 | further information).
|
---|
542 |
|
---|
543 | =item B<-bugs>
|
---|
544 |
|
---|
545 | There are several known bugs in SSL and TLS implementations. Adding this
|
---|
546 | option enables various workarounds.
|
---|
547 |
|
---|
548 | =item B<-comp>
|
---|
549 |
|
---|
550 | Enables support for SSL/TLS compression.
|
---|
551 | This option was introduced in OpenSSL 1.1.0.
|
---|
552 | TLS compression is not recommended and is off by default as of
|
---|
553 | OpenSSL 1.1.0.
|
---|
554 |
|
---|
555 | =item B<-no_comp>
|
---|
556 |
|
---|
557 | Disables support for SSL/TLS compression.
|
---|
558 | TLS compression is not recommended and is off by default as of
|
---|
559 | OpenSSL 1.1.0.
|
---|
560 |
|
---|
561 | =item B<-brief>
|
---|
562 |
|
---|
563 | Only provide a brief summary of connection parameters instead of the
|
---|
564 | normal verbose output.
|
---|
565 |
|
---|
566 | =item B<-sigalgs sigalglist>
|
---|
567 |
|
---|
568 | Specifies the list of signature algorithms that are sent by the client.
|
---|
569 | The server selects one entry in the list based on its preferences.
|
---|
570 | For example strings, see L<SSL_CTX_set1_sigalgs(3)>
|
---|
571 |
|
---|
572 | =item B<-curves curvelist>
|
---|
573 |
|
---|
574 | Specifies the list of supported curves to be sent by the client. The curve is
|
---|
575 | ultimately selected by the server. For a list of all curves, use:
|
---|
576 |
|
---|
577 | $ openssl ecparam -list_curves
|
---|
578 |
|
---|
579 | =item B<-cipher cipherlist>
|
---|
580 |
|
---|
581 | This allows the TLSv1.2 and below cipher list sent by the client to be modified.
|
---|
582 | This list will be combined with any TLSv1.3 ciphersuites that have been
|
---|
583 | configured. Although the server determines which ciphersuite is used it should
|
---|
584 | take the first supported cipher in the list sent by the client. See the
|
---|
585 | B<ciphers> command for more information.
|
---|
586 |
|
---|
587 | =item B<-ciphersuites val>
|
---|
588 |
|
---|
589 | This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
|
---|
590 | list will be combined with any TLSv1.2 and below ciphersuites that have been
|
---|
591 | configured. Although the server determines which cipher suite is used it should
|
---|
592 | take the first supported cipher in the list sent by the client. See the
|
---|
593 | B<ciphers> command for more information. The format for this list is a simple
|
---|
594 | colon (":") separated list of TLSv1.3 ciphersuite names.
|
---|
595 |
|
---|
596 | =item B<-starttls protocol>
|
---|
597 |
|
---|
598 | Send the protocol-specific message(s) to switch to TLS for communication.
|
---|
599 | B<protocol> is a keyword for the intended protocol. Currently, the only
|
---|
600 | supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
|
---|
601 | "irc", "postgres", "mysql", "lmtp", "nntp", "sieve" and "ldap".
|
---|
602 |
|
---|
603 | =item B<-xmpphost hostname>
|
---|
604 |
|
---|
605 | This option, when used with "-starttls xmpp" or "-starttls xmpp-server",
|
---|
606 | specifies the host for the "to" attribute of the stream element.
|
---|
607 | If this option is not specified, then the host specified with "-connect"
|
---|
608 | will be used.
|
---|
609 |
|
---|
610 | This option is an alias of the B<-name> option for "xmpp" and "xmpp-server".
|
---|
611 |
|
---|
612 | =item B<-name hostname>
|
---|
613 |
|
---|
614 | This option is used to specify hostname information for various protocols
|
---|
615 | used with B<-starttls> option. Currently only "xmpp", "xmpp-server",
|
---|
616 | "smtp" and "lmtp" can utilize this B<-name> option.
|
---|
617 |
|
---|
618 | If this option is used with "-starttls xmpp" or "-starttls xmpp-server",
|
---|
619 | if specifies the host for the "to" attribute of the stream element. If this
|
---|
620 | option is not specified, then the host specified with "-connect" will be used.
|
---|
621 |
|
---|
622 | If this option is used with "-starttls lmtp" or "-starttls smtp", it specifies
|
---|
623 | the name to use in the "LMTP LHLO" or "SMTP EHLO" message, respectively. If
|
---|
624 | this option is not specified, then "mail.example.com" will be used.
|
---|
625 |
|
---|
626 | =item B<-tlsextdebug>
|
---|
627 |
|
---|
628 | Print out a hex dump of any TLS extensions received from the server.
|
---|
629 |
|
---|
630 | =item B<-no_ticket>
|
---|
631 |
|
---|
632 | Disable RFC4507bis session ticket support.
|
---|
633 |
|
---|
634 | =item B<-sess_out filename>
|
---|
635 |
|
---|
636 | Output SSL session to B<filename>.
|
---|
637 |
|
---|
638 | =item B<-sess_in sess.pem>
|
---|
639 |
|
---|
640 | Load SSL session from B<filename>. The client will attempt to resume a
|
---|
641 | connection from this session.
|
---|
642 |
|
---|
643 | =item B<-engine id>
|
---|
644 |
|
---|
645 | Specifying an engine (by its unique B<id> string) will cause B<s_client>
|
---|
646 | to attempt to obtain a functional reference to the specified engine,
|
---|
647 | thus initialising it if needed. The engine will then be set as the default
|
---|
648 | for all available algorithms.
|
---|
649 |
|
---|
650 | =item B<-rand file...>
|
---|
651 |
|
---|
652 | A file or files containing random data used to seed the random number
|
---|
653 | generator.
|
---|
654 | Multiple files can be specified separated by an OS-dependent character.
|
---|
655 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
|
---|
656 | all others.
|
---|
657 |
|
---|
658 | =item [B<-writerand file>]
|
---|
659 |
|
---|
660 | Writes random data to the specified I<file> upon exit.
|
---|
661 | This can be used with a subsequent B<-rand> flag.
|
---|
662 |
|
---|
663 | =item B<-serverinfo types>
|
---|
664 |
|
---|
665 | A list of comma-separated TLS Extension Types (numbers between 0 and
|
---|
666 | 65535). Each type will be sent as an empty ClientHello TLS Extension.
|
---|
667 | The server's response (if any) will be encoded and displayed as a PEM
|
---|
668 | file.
|
---|
669 |
|
---|
670 | =item B<-status>
|
---|
671 |
|
---|
672 | Sends a certificate status request to the server (OCSP stapling). The server
|
---|
673 | response (if any) is printed out.
|
---|
674 |
|
---|
675 | =item B<-alpn protocols>, B<-nextprotoneg protocols>
|
---|
676 |
|
---|
677 | These flags enable the Enable the Application-Layer Protocol Negotiation
|
---|
678 | or Next Protocol Negotiation (NPN) extension, respectively. ALPN is the
|
---|
679 | IETF standard and replaces NPN.
|
---|
680 | The B<protocols> list is a comma-separated list of protocol names that
|
---|
681 | the client should advertise support for. The list should contain the most
|
---|
682 | desirable protocols first. Protocol names are printable ASCII strings,
|
---|
683 | for example "http/1.1" or "spdy/3".
|
---|
684 | An empty list of protocols is treated specially and will cause the
|
---|
685 | client to advertise support for the TLS extension but disconnect just
|
---|
686 | after receiving ServerHello with a list of server supported protocols.
|
---|
687 | The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used.
|
---|
688 |
|
---|
689 | =item B<-ct>, B<-noct>
|
---|
690 |
|
---|
691 | Use one of these two options to control whether Certificate Transparency (CT)
|
---|
692 | is enabled (B<-ct>) or disabled (B<-noct>).
|
---|
693 | If CT is enabled, signed certificate timestamps (SCTs) will be requested from
|
---|
694 | the server and reported at handshake completion.
|
---|
695 |
|
---|
696 | Enabling CT also enables OCSP stapling, as this is one possible delivery method
|
---|
697 | for SCTs.
|
---|
698 |
|
---|
699 | =item B<-ctlogfile>
|
---|
700 |
|
---|
701 | A file containing a list of known Certificate Transparency logs. See
|
---|
702 | L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
|
---|
703 |
|
---|
704 | =item B<-keylogfile file>
|
---|
705 |
|
---|
706 | Appends TLS secrets to the specified keylog file such that external programs
|
---|
707 | (like Wireshark) can decrypt TLS connections.
|
---|
708 |
|
---|
709 | =item B<-early_data file>
|
---|
710 |
|
---|
711 | Reads the contents of the specified file and attempts to send it as early data
|
---|
712 | to the server. This will only work with resumed sessions that support early
|
---|
713 | data and when the server accepts the early data.
|
---|
714 |
|
---|
715 | =item B<-enable_pha>
|
---|
716 |
|
---|
717 | For TLSv1.3 only, send the Post-Handshake Authentication extension. This will
|
---|
718 | happen whether or not a certificate has been provided via B<-cert>.
|
---|
719 |
|
---|
720 | =item B<[target]>
|
---|
721 |
|
---|
722 | Rather than providing B<-connect>, the target hostname and optional port may
|
---|
723 | be provided as a single positional argument after all options. If neither this
|
---|
724 | nor B<-connect> are provided, falls back to attempting to connect to localhost
|
---|
725 | on port 4433.
|
---|
726 |
|
---|
727 | =back
|
---|
728 |
|
---|
729 | =head1 CONNECTED COMMANDS
|
---|
730 |
|
---|
731 | If a connection is established with an SSL server then any data received
|
---|
732 | from the server is displayed and any key presses will be sent to the
|
---|
733 | server. If end of file is reached then the connection will be closed down. When
|
---|
734 | used interactively (which means neither B<-quiet> nor B<-ign_eof> have been
|
---|
735 | given), then certain commands are also recognized which perform special
|
---|
736 | operations. These commands are a letter which must appear at the start of a
|
---|
737 | line. They are listed below.
|
---|
738 |
|
---|
739 | =over 4
|
---|
740 |
|
---|
741 | =item B<Q>
|
---|
742 |
|
---|
743 | End the current SSL connection and exit.
|
---|
744 |
|
---|
745 | =item B<R>
|
---|
746 |
|
---|
747 | Renegotiate the SSL session (TLSv1.2 and below only).
|
---|
748 |
|
---|
749 | =item B<B>
|
---|
750 |
|
---|
751 | Send a heartbeat message to the server (DTLS only)
|
---|
752 |
|
---|
753 | =item B<k>
|
---|
754 |
|
---|
755 | Send a key update message to the server (TLSv1.3 only)
|
---|
756 |
|
---|
757 | =item B<K>
|
---|
758 |
|
---|
759 | Send a key update message to the server and request one back (TLSv1.3 only)
|
---|
760 |
|
---|
761 | =back
|
---|
762 |
|
---|
763 | =head1 NOTES
|
---|
764 |
|
---|
765 | B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
|
---|
766 | server the command:
|
---|
767 |
|
---|
768 | openssl s_client -connect servername:443
|
---|
769 |
|
---|
770 | would typically be used (https uses port 443). If the connection succeeds
|
---|
771 | then an HTTP command can be given such as "GET /" to retrieve a web page.
|
---|
772 |
|
---|
773 | If the handshake fails then there are several possible causes, if it is
|
---|
774 | nothing obvious like no client certificate then the B<-bugs>,
|
---|
775 | B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried
|
---|
776 | in case it is a buggy server. In particular you should play with these
|
---|
777 | options B<before> submitting a bug report to an OpenSSL mailing list.
|
---|
778 |
|
---|
779 | A frequent problem when attempting to get client certificates working
|
---|
780 | is that a web client complains it has no certificates or gives an empty
|
---|
781 | list to choose from. This is normally because the server is not sending
|
---|
782 | the clients certificate authority in its "acceptable CA list" when it
|
---|
783 | requests a certificate. By using B<s_client> the CA list can be viewed
|
---|
784 | and checked. However some servers only request client authentication
|
---|
785 | after a specific URL is requested. To obtain the list in this case it
|
---|
786 | is necessary to use the B<-prexit> option and send an HTTP request
|
---|
787 | for an appropriate page.
|
---|
788 |
|
---|
789 | If a certificate is specified on the command line using the B<-cert>
|
---|
790 | option it will not be used unless the server specifically requests
|
---|
791 | a client certificate. Therefor merely including a client certificate
|
---|
792 | on the command line is no guarantee that the certificate works.
|
---|
793 |
|
---|
794 | If there are problems verifying a server certificate then the
|
---|
795 | B<-showcerts> option can be used to show all the certificates sent by the
|
---|
796 | server.
|
---|
797 |
|
---|
798 | The B<s_client> utility is a test tool and is designed to continue the
|
---|
799 | handshake after any certificate verification errors. As a result it will
|
---|
800 | accept any certificate chain (trusted or not) sent by the peer. None test
|
---|
801 | applications should B<not> do this as it makes them vulnerable to a MITM
|
---|
802 | attack. This behaviour can be changed by with the B<-verify_return_error>
|
---|
803 | option: any verify errors are then returned aborting the handshake.
|
---|
804 |
|
---|
805 | The B<-bind> option may be useful if the server or a firewall requires
|
---|
806 | connections to come from some particular address and or port.
|
---|
807 |
|
---|
808 | =head1 BUGS
|
---|
809 |
|
---|
810 | Because this program has a lot of options and also because some of the
|
---|
811 | techniques used are rather old, the C source of B<s_client> is rather hard to
|
---|
812 | read and not a model of how things should be done.
|
---|
813 | A typical SSL client program would be much simpler.
|
---|
814 |
|
---|
815 | The B<-prexit> option is a bit of a hack. We should really report
|
---|
816 | information whenever a session is renegotiated.
|
---|
817 |
|
---|
818 | =head1 SEE ALSO
|
---|
819 |
|
---|
820 | L<SSL_CONF_cmd(3)>, L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>,
|
---|
821 | L<SSL_CTX_set_max_send_fragment(3)>, L<SSL_CTX_set_split_send_fragment(3)>,
|
---|
822 | L<SSL_CTX_set_max_pipelines(3)>
|
---|
823 |
|
---|
824 | =head1 HISTORY
|
---|
825 |
|
---|
826 | The B<-no_alt_chains> option was added in OpenSSL 1.1.0.
|
---|
827 | The B<-name> option was added in OpenSSL 1.1.1.
|
---|
828 |
|
---|
829 | =head1 COPYRIGHT
|
---|
830 |
|
---|
831 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
|
---|
832 |
|
---|
833 | Licensed under the OpenSSL license (the "License"). You may not use
|
---|
834 | this file except in compliance with the License. You can obtain a copy
|
---|
835 | in the file LICENSE in the source distribution or at
|
---|
836 | L<https://www.openssl.org/source/license.html>.
|
---|
837 |
|
---|
838 | =cut
|
---|