s_client.pod revision 279264
1 2=pod 3 4=head1 NAME 5 6s_client - SSL/TLS client program 7 8=head1 SYNOPSIS 9 10B<openssl> B<s_client> 11[B<-connect host:port>] 12[B<-servername name>] 13[B<-verify depth>] 14[B<-verify_return_error>] 15[B<-cert filename>] 16[B<-certform DER|PEM>] 17[B<-key filename>] 18[B<-keyform DER|PEM>] 19[B<-pass arg>] 20[B<-CApath directory>] 21[B<-CAfile filename>] 22[B<-reconnect>] 23[B<-pause>] 24[B<-showcerts>] 25[B<-debug>] 26[B<-msg>] 27[B<-nbio_test>] 28[B<-state>] 29[B<-nbio>] 30[B<-crlf>] 31[B<-ign_eof>] 32[B<-no_ign_eof>] 33[B<-quiet>] 34[B<-ssl2>] 35[B<-ssl3>] 36[B<-tls1>] 37[B<-no_ssl2>] 38[B<-no_ssl3>] 39[B<-no_tls1>] 40[B<-bugs>] 41[B<-cipher cipherlist>] 42[B<-serverpref>] 43[B<-starttls protocol>] 44[B<-engine id>] 45[B<-tlsextdebug>] 46[B<-no_ticket>] 47[B<-sess_out filename>] 48[B<-sess_in filename>] 49[B<-rand file(s)>] 50[B<-status>] 51[B<-nextprotoneg protocols>] 52 53=head1 DESCRIPTION 54 55The B<s_client> command implements a generic SSL/TLS client which connects 56to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for 57SSL servers. 58 59=head1 OPTIONS 60 61=over 4 62 63=item B<-connect host:port> 64 65This specifies the host and optional port to connect to. If not specified 66then an attempt is made to connect to the local host on port 4433. 67 68=item B<-servername name> 69 70Set the TLS SNI (Server Name Indication) extension in the ClientHello message. 71 72=item B<-cert certname> 73 74The certificate to use, if one is requested by the server. The default is 75not to use a certificate. 76 77=item B<-certform format> 78 79The certificate format to use: DER or PEM. PEM is the default. 80 81=item B<-key keyfile> 82 83The private key to use. If not specified then the certificate file will 84be used. 85 86=item B<-keyform format> 87 88The private format to use: DER or PEM. PEM is the default. 89 90=item B<-pass arg> 91 92the private key password source. For more information about the format of B<arg> 93see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 94 95=item B<-verify depth> 96 97The verify depth to use. This specifies the maximum length of the 98server certificate chain and turns on server certificate verification. 99Currently the verify operation continues after errors so all the problems 100with a certificate chain can be seen. As a side effect the connection 101will never fail due to a server certificate verify failure. 102 103=item B<-verify_return_error> 104 105Return verification errors instead of continuing. This will typically 106abort the handshake with a fatal error. 107 108=item B<-CApath directory> 109 110The directory to use for server certificate verification. This directory 111must be in "hash format", see B<verify> for more information. These are 112also used when building the client certificate chain. 113 114=item B<-CAfile file> 115 116A file containing trusted certificates to use during server authentication 117and to use when attempting to build the client certificate chain. 118 119=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig> 120 121Set various certificate chain valiadition option. See the 122L<B<verify>|verify(1)> manual page for details. 123 124=item B<-reconnect> 125 126reconnects to the same server 5 times using the same session ID, this can 127be used as a test that session caching is working. 128 129=item B<-pause> 130 131pauses 1 second between each read and write call. 132 133=item B<-showcerts> 134 135display the whole server certificate chain: normally only the server 136certificate itself is displayed. 137 138=item B<-prexit> 139 140print session information when the program exits. This will always attempt 141to print out information even if the connection fails. Normally information 142will only be printed out once if the connection succeeds. This option is useful 143because the cipher in use may be renegotiated or the connection may fail 144because a client certificate is required or is requested only after an 145attempt is made to access a certain URL. Note: the output produced by this 146option is not always accurate because a connection might never have been 147established. 148 149=item B<-state> 150 151prints out the SSL session states. 152 153=item B<-debug> 154 155print extensive debugging information including a hex dump of all traffic. 156 157=item B<-msg> 158 159show all protocol messages with hex dump. 160 161=item B<-nbio_test> 162 163tests non-blocking I/O 164 165=item B<-nbio> 166 167turns on non-blocking I/O 168 169=item B<-crlf> 170 171this option translated a line feed from the terminal into CR+LF as required 172by some servers. 173 174=item B<-ign_eof> 175 176inhibit shutting down the connection when end of file is reached in the 177input. 178 179=item B<-quiet> 180 181inhibit printing of session and certificate information. This implicitly 182turns on B<-ign_eof> as well. 183 184=item B<-no_ign_eof> 185 186shut down the connection when end of file is reached in the input. 187Can be used to override the implicit B<-ign_eof> after B<-quiet>. 188 189=item B<-psk_identity identity> 190 191Use the PSK identity B<identity> when using a PSK cipher suite. 192 193=item B<-psk key> 194 195Use the PSK key B<key> when using a PSK cipher suite. The key is 196given as a hexadecimal number without leading 0x, for example -psk 1971a2b3c4d. 198 199=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> 200 201these options disable the use of certain SSL or TLS protocols. By default 202the initial handshake uses a method which should be compatible with all 203servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. 204 205Unfortunately there are a lot of ancient and broken servers in use which 206cannot handle this technique and will fail to connect. Some servers only 207work if TLS is turned off with the B<-no_tls> option others will only 208support SSL v2 and may need the B<-ssl2> option. 209 210=item B<-bugs> 211 212there are several known bug in SSL and TLS implementations. Adding this 213option enables various workarounds. 214 215=item B<-cipher cipherlist> 216 217this allows the cipher list sent by the client to be modified. Although 218the server determines which cipher suite is used it should take the first 219supported cipher in the list sent by the client. See the B<ciphers> 220command for more information. 221 222=item B<-serverpref> 223 224use the server's cipher preferences; only used for SSLV2. 225 226=item B<-starttls protocol> 227 228send the protocol-specific message(s) to switch to TLS for communication. 229B<protocol> is a keyword for the intended protocol. Currently, the only 230supported keywords are "smtp", "pop3", "imap", and "ftp". 231 232=item B<-tlsextdebug> 233 234print out a hex dump of any TLS extensions received from the server. 235 236=item B<-no_ticket> 237 238disable RFC4507bis session ticket support. 239 240=item B<-sess_out filename> 241 242output SSL session to B<filename> 243 244=item B<-sess_in sess.pem> 245 246load SSL session from B<filename>. The client will attempt to resume a 247connection from this session. 248 249=item B<-engine id> 250 251specifying an engine (by its unique B<id> string) will cause B<s_client> 252to attempt to obtain a functional reference to the specified engine, 253thus initialising it if needed. The engine will then be set as the default 254for all available algorithms. 255 256=item B<-rand file(s)> 257 258a file or files containing random data used to seed the random number 259generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 260Multiple files can be specified separated by a OS-dependent character. 261The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 262all others. 263 264=item B<-status> 265 266sends a certificate status request to the server (OCSP stapling). The server 267response (if any) is printed out. 268 269=item B<-nextprotoneg protocols> 270 271enable Next Protocol Negotiation TLS extension and provide a list of 272comma-separated protocol names that the client should advertise 273support for. The list should contain most wanted protocols first. 274Protocol names are printable ASCII strings, for example "http/1.1" or 275"spdy/3". 276Empty list of protocols is treated specially and will cause the client to 277advertise support for the TLS extension but disconnect just after 278reciving ServerHello with a list of server supported protocols. 279 280=back 281 282=head1 CONNECTED COMMANDS 283 284If a connection is established with an SSL server then any data received 285from the server is displayed and any key presses will be sent to the 286server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> 287have been given), the session will be renegotiated if the line begins with an 288B<R>, and if the line begins with a B<Q> or if end of file is reached, the 289connection will be closed down. 290 291=head1 NOTES 292 293B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP 294server the command: 295 296 openssl s_client -connect servername:443 297 298would typically be used (https uses port 443). If the connection succeeds 299then an HTTP command can be given such as "GET /" to retrieve a web page. 300 301If the handshake fails then there are several possible causes, if it is 302nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, 303B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried 304in case it is a buggy server. In particular you should play with these 305options B<before> submitting a bug report to an OpenSSL mailing list. 306 307A frequent problem when attempting to get client certificates working 308is that a web client complains it has no certificates or gives an empty 309list to choose from. This is normally because the server is not sending 310the clients certificate authority in its "acceptable CA list" when it 311requests a certificate. By using B<s_client> the CA list can be viewed 312and checked. However some servers only request client authentication 313after a specific URL is requested. To obtain the list in this case it 314is necessary to use the B<-prexit> option and send an HTTP request 315for an appropriate page. 316 317If a certificate is specified on the command line using the B<-cert> 318option it will not be used unless the server specifically requests 319a client certificate. Therefor merely including a client certificate 320on the command line is no guarantee that the certificate works. 321 322If there are problems verifying a server certificate then the 323B<-showcerts> option can be used to show the whole chain. 324 325Since the SSLv23 client hello cannot include compression methods or extensions 326these will only be supported if its use is disabled, for example by using the 327B<-no_sslv2> option. 328 329The B<s_client> utility is a test tool and is designed to continue the 330handshake after any certificate verification errors. As a result it will 331accept any certificate chain (trusted or not) sent by the peer. None test 332applications should B<not> do this as it makes them vulnerable to a MITM 333attack. This behaviour can be changed by with the B<-verify_return_error> 334option: any verify errors are then returned aborting the handshake. 335 336=head1 BUGS 337 338Because this program has a lot of options and also because some of 339the techniques used are rather old, the C source of s_client is rather 340hard to read and not a model of how things should be done. A typical 341SSL client program would be much simpler. 342 343The B<-prexit> option is a bit of a hack. We should really report 344information whenever a session is renegotiated. 345 346=head1 SEE ALSO 347 348L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> 349 350=cut 351