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