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