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