crypto/openssl/doc/apps/s_client.pod

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