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