=head1 SYNOPSIS
B<openssl> B<s_client>
-[B<-connect> host:port>]
+[B<-connect host:port>]
+[B<-servername name>]
[B<-verify depth>]
+[B<-verify_return_error>]
[B<-cert filename>]
+[B<-certform DER|PEM>]
[B<-key filename>]
+[B<-keyform DER|PEM>]
+[B<-pass arg>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-reconnect>]
[B<-pause>]
[B<-showcerts>]
[B<-debug>]
+[B<-msg>]
[B<-nbio_test>]
[B<-state>]
[B<-nbio>]
[B<-crlf>]
+[B<-ign_eof>]
+[B<-no_ign_eof>]
[B<-quiet>]
[B<-ssl2>]
[B<-ssl3>]
[B<-no_tls1>]
[B<-bugs>]
[B<-cipher cipherlist>]
+[B<-serverpref>]
+[B<-starttls protocol>]
+[B<-engine id>]
+[B<-tlsextdebug>]
+[B<-no_ticket>]
+[B<-sess_out filename>]
+[B<-sess_in filename>]
+[B<-rand file(s)>]
+[B<-serverinfo types>]
=head1 DESCRIPTION
This specifies the host and optional port to connect to. If not specified
then an attempt is made to connect to the local host on port 4433.
+=item B<-servername name>
+
+Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
+
=item B<-cert certname>
The certificate to use, if one is requested by the server. The default is
not to use a certificate.
+=item B<-certform format>
+
+The certificate format to use: DER or PEM. PEM is the default.
+
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used.
+=item B<-keyform format>
+
+The private format to use: DER or PEM. PEM is the default.
+
+=item B<-pass arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+
=item B<-verify depth>
The verify depth to use. This specifies the maximum length of the
with a certificate chain can be seen. As a side effect the connection
will never fail due to a server certificate verify failure.
+=item B<-verify_return_error>
+
+Return verification errors instead of continuing. This will typically
+abort the handshake with a fatal error.
+
=item B<-CApath directory>
The directory to use for server certificate verification. This directory
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
+=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig>
+
+Set various certificate chain valiadition option. See the
+L<B<verify>|verify(1)> manual page for details.
+
=item B<-reconnect>
reconnects to the same server 5 times using the same session ID, this can
print extensive debugging information including a hex dump of all traffic.
+=item B<-msg>
+
+show all protocol messages with hex dump.
+
=item B<-nbio_test>
-tests non blocking I/O
+tests non-blocking I/O
=item B<-nbio>
-turns on non blocking I/O
+turns on non-blocking I/O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF as required
by some servers.
+=item B<-ign_eof>
+
+inhibit shutting down the connection when end of file is reached in the
+input.
+
=item B<-quiet>
-inhibit printing of session and certificate information.
+inhibit printing of session and certificate information. This implicitly
+turns on B<-ign_eof> as well.
+
+=item B<-no_ign_eof>
+
+shut down the connection when end of file is reached in the input.
+Can be used to override the implicit B<-ign_eof> after B<-quiet>.
+
+=item B<-psk_identity identity>
+
+Use the PSK identity B<identity> when using a PSK cipher suite.
+
+=item B<-psk key>
+
+Use the PSK key B<key> when using a PSK cipher suite. The key is
+given as a hexadecimal number without leading 0x, for example -psk
+1a2b3c4d.
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
=item B<-cipher cipherlist>
-this allows the cipher list sent by the client to be modified. See the
-B<ciphers> command for more information.
+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
+supported cipher in the list sent by the client. See the B<ciphers>
+command for more information.
+
+=item B<-serverpref>
+
+use the server's cipher preferences; only used for SSLV2.
+
+=item B<-starttls protocol>
+
+send the protocol-specific message(s) to switch to TLS for communication.
+B<protocol> is a keyword for the intended protocol. Currently, the only
+supported keywords are "smtp", "pop3", "imap", and "ftp".
+
+=item B<-tlsextdebug>
+
+print out a hex dump of any TLS extensions received from the server.
+
+=item B<-no_ticket>
+
+disable RFC4507bis session ticket support.
+
+=item B<-sess_out filename>
+
+output SSL session to B<filename>
+
+=item B<-sess_in sess.pem>
+
+load SSL session from B<filename>. The client will attempt to resume a
+connection from this session.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<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.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-serverinfo types>
+
+a list of comma-separated TLS Extension Types (numbers between 0 and
+65535). Each type will be sent as an empty ClientHello TLS Extension.
+The server's response (if any) will be encoded and displayed as a PEM
+file.
=back
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. If the line begins with an B<R> then the session will be
-renegotiated. If the line begins with a B<Q> the connection will be closed
-down.
+server. When used interactively (which means neither B<-quiet> nor B<-ign_eof>
+have been given), the session will be renegotiated if the line begins with an
+B<R>, and if the line begins with a B<Q> or if end of file is reached, the
+connection will be closed down.
=head1 NOTES
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
-B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> can be tried
+B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
requests a certificate. By using B<s_client> the CA list can be viewed
and checked. However some servers only request client authentication
after a specific URL is requested. To obtain the list in this case it
-is necessary to use the B<-prexit> command and send an HTTP request
+is necessary to use the B<-prexit> option and send an HTTP request
for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
If there are problems verifying a server certificate then the
B<-showcerts> option can be used to show the whole chain.
+Since the SSLv23 client hello cannot include compression methods or extensions
+these will only be supported if its use is disabled, for example by using the
+B<-no_sslv2> option.
+
+The B<s_client> utility is a test tool and is designed to continue the
+handshake after any certificate verification errors. As a result it will
+accept any certificate chain (trusted or not) sent by the peer. None test
+applications should B<not> do this as it makes them vulnerable to a MITM
+attack. This behaviour can be changed by with the B<-verify_return_error>
+option: any verify errors are then returned aborting the handshake.
+
=head1 BUGS
Because this program has a lot of options and also because some of
hard to read and not a model of how things should be done. A typical
SSL client program would be much simpler.
-The B<-verify> option should really exit if the server verification
-fails.
-
The B<-prexit> option is a bit of a hack. We should really report
information whenever a session is renegotiated.
=head1 SEE ALSO
-sess_id(1), s_server(1), ciphers(1)
+L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
=cut
projects / oweals / openssl.git / blobdiff