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