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