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