S_CLIENT(1)                 OpenSSL                 S_CLIENT(1)





NAME
       s_client - SSL/TLS client program

SYNOPSIS
       openssl s_client [-connect host:port>] [-verify depth]
       [-cert filename] [-key filename] [-CApath directory]
       [-CAfile filename] [-reconnect] [-pause] [-showcerts]
       [-debug] [-msg] [-nbio_test] [-state] [-nbio] [-crlf]
       [-ign_eof] [-quiet] [-ssl2] [-ssl3] [-tls1] [-no_ssl2]
       [-no_ssl3] [-no_tls1] [-bugs] [-cipher cipherlist]
       [-starttls protocol] [-engine id] [-rand file(s)]

DESCRIPTION
       The s_client command implements a generic SSL/TLS client
       which connects to a remote host using SSL/TLS. It is a
       very useful diagnostic tool for SSL servers.

OPTIONS
       -connect host:port
           This specifies the host and optional port to connect
           to. If not specified then an attempt is made to con-
           nect to the local host on port 4433.

       -cert certname
           The certificate to use, if one is requested by the
           server. The default is not to use a certificate.

       -key keyfile
           The private key to use. If not specified then the
           certificate file will be used.

       -verify depth
           The verify depth to use. This specifies the maximum
           length of the server certificate chain and turns on
           server certificate verification.  Currently the ver-
           ify operation continues after errors so all the
           problems with a certificate chain can be seen. As a
           side effect the connection will never fail due to a
           server certificate verify failure.

       -CApath directory
           The directory to use for server certificate verifi-
           cation. This directory must be in "hash format", see
           verify for more information. These are also used
           when building the client certificate chain.

       -CAfile file
           A file containing trusted certificates to use during
           server authentication and to use when attempting to
           build the client certificate chain.

       -reconnect
           reconnects to the same server 5 times using the same
           session ID, this can be used as a test that session
           caching is working.

       -pause
           pauses 1 second between each read and write call.

       -showcerts
           display the whole server certificate chain: normally
           only the server certificate itself is displayed.

       -prexit
           print session information when the program exits.
           This will always attempt to print out information
           even if the connection fails. Normally information
           will only be printed out once if the connection suc-
           ceeds. This option is useful because the cipher in
           use may be renegotiated or the connection may fail
           because a client certificate is required or is
           requested only after an attempt is made to access a
           certain URL. Note: the output produced by this
           option is not always accurate because a connection
           might never have been established.

       -state
           prints out the SSL session states.

       -debug
           print extensive debugging information including a
           hex dump of all traffic.

       -msg
           show all protocol messages with hex dump.

       -nbio_test
           tests non-blocking I/O

       -nbio
           turns on non-blocking I/O

       -crlf
           this option translated a line feed from the terminal
           into CR+LF as required by some servers.

       -ign_eof
           inhibit shutting down the connection when end of
           file is reached in the input.

       -quiet
           inhibit printing of session and certificate informa-
           tion.  This implicitly turns on -ign_eof as well.

       -ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1
           these options disable the use of certain SSL or TLS
           protocols. By default the initial handshake uses a
           method which should be compatible with all servers
           and permit them to use SSL v3, SSL v2 or TLS as
           appropriate.

           Unfortunately there are a lot of ancient and broken
           servers in use which cannot handle this technique
           and will fail to connect. Some servers only work if
           TLS is turned off with the -no_tls option others
           will only support SSL v2 and may need the -ssl2
           option.

       -bugs
           there are several known bug in SSL and TLS implemen-
           tations. Adding this option enables various work-
           arounds.

       -cipher cipherlist
           this allows the cipher list sent by the client to be
           modified. Although the server determines which
           cipher suite is used it should take the first sup-
           ported cipher in the list sent by the client. See
           the ciphers command for more information.

       -starttls protocol
           send the protocol-specific message(s) to switch to
           TLS for communication.  protocol is a keyword for
           the intended protocol.  Currently, the only
           supported keywords are "smtp" and "pop3".

       -engine id
           specifying an engine (by it's unique id string) will
           cause s_client to attempt to obtain a functional
           reference to the specified engine, thus initialising
           it if needed. The engine will then be set as the
           default for all available algorithms.

       -rand file(s)
           a file or files containing random data used to seed
           the random number generator, or an EGD socket (see
           RAND_egd(3)).  Multiple files can be specified sepa-
           rated by a OS-dependent character.  The separator is
           ; for MS-Windows, , for OpenVMS, and : for all oth-
           ers.

CONNECTED COMMANDS
       If a connection is established with an SSL server then
       any data received from the server is displayed and any
       key presses will be sent to the server. When used inter-
       actively (which means neither -quiet nor -ign_eof have
       been given), the session will be renegotiated if the
       line begins with an R, and if the line begins with a Q
       or if end of file is reached, the connection will be
       closed down.

NOTES
       s_client can be used to debug SSL servers. To connect to
       an SSL HTTP server the command:

        openssl s_client -connect servername:443

       would typically be used (https uses port 443). If the
       connection succeeds then an HTTP command can be given
       such as "GET /" to retrieve a web page.

       If the handshake fails then there are several possible
       causes, if it is nothing obvious like no client certifi-
       cate then the -bugs, -ssl2, -ssl3, -tls1, -no_ssl2,
       -no_ssl3, -no_tls1 can be tried in case it is a buggy
       server. In particular you should play with these options
       before submitting a bug report to an OpenSSL mailing
       list.

       A frequent problem when attempting to get client cer-
       tificates working is that a web client complains it has
       no certificates or gives an empty list to choose from.
       This is normally because the server is not sending the
       clients certificate authority in its "acceptable CA
       list" when it requests a certificate. By using s_client
       the CA list can be viewed and checked. However some
       servers only request client authentication after a spe-
       cific URL is requested. To obtain the list in this case
       it is necessary to use the -prexit command and send an
       HTTP request for an appropriate page.

       If a certificate is specified on the command line using
       the -cert option it will not be used unless the server
       specifically requests a client certificate. Therefor
       merely including a client certificate on the command
       line is no guarantee that the certificate works.

       If there are problems verifying a server certificate
       then the -showcerts option can be used to show the whole
       chain.

BUGS
       Because this program has a lot of options and also
       because some of the techniques used are rather old, the
       C source of s_client is rather hard to read and not a
       model of how things should be done. A typical SSL client
       program would be much simpler.

       The -verify option should really exit if the server ver-
       ification fails.

       The -prexit option is a bit of a hack. We should really
       report information whenever a session is renegotiated.

SEE ALSO
       sess_id(1), s_server(1), ciphers(1)



0.9.7c                     2003-05-28               S_CLIENT(1)
