123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173 |
- =pod
- =head1 NAME
- s_time - SSL/TLS performance timing program
- =head1 SYNOPSIS
- B<openssl> B<s_time>
- [B<-connect host:port>]
- [B<-www page>]
- [B<-cert filename>]
- [B<-key filename>]
- [B<-CApath directory>]
- [B<-CAfile filename>]
- [B<-reuse>]
- [B<-new>]
- [B<-verify depth>]
- [B<-nbio>]
- [B<-time seconds>]
- [B<-ssl2>]
- [B<-ssl3>]
- [B<-bugs>]
- [B<-cipher cipherlist>]
- =head1 DESCRIPTION
- The B<s_client> command implements a generic SSL/TLS client which connects to a
- remote host using SSL/TLS. It can request a page from the server and includes
- the time to transfer the payload data in its timing measurements. It measures
- the number of connections within a given timeframe, the amount of data
- transferred (if any), and calculates the average time spent for one connection.
- =head1 OPTIONS
- =over 4
- =item B<-connect host:port>
- This specifies the host and optional port to connect to.
- =item B<-www page>
- This specifies the page to GET from the server. A value of '/' gets the
- index.htm[l] page. If this parameter is not specified, then B<s_time> will only
- perform the handshake to establish SSL connections but not transfer any
- payload data.
- =item B<-cert certname>
- The certificate to use, if one is requested by the server. The default is
- not to use a certificate. The file is in PEM format.
- =item B<-key keyfile>
- The private key to use. If not specified then the certificate file will
- be used. The file is in PEM format.
- =item B<-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 verify 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.
- =item B<-CApath directory>
- The directory to use for server certificate verification. This directory
- must be in "hash format", see B<verify> for more information. These are
- also used when building the client certificate chain.
- =item B<-CAfile file>
- A file containing trusted certificates to use during server authentication
- and to use when attempting to build the client certificate chain.
- =item B<-new>
- performs the timing test using a new session ID for each connection.
- If neither B<-new> nor B<-reuse> are specified, they are both on by default
- and executed in sequence.
- =item B<-reuse>
- performs the timing test using the same session ID; this can be used as a test
- that session caching is working. If neither B<-new> nor B<-reuse> are
- specified, they are both on by default and executed in sequence.
- =item B<-nbio>
- turns on non-blocking I/O.
- =item B<-ssl2>, B<-ssl3>
- 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.
- The timing program is not as rich in options to turn protocols on and off as
- the L<s_client(1)|s_client(1)> program and may not connect to all servers.
- 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 B<-ssl3> option; others
- will only support SSL v2 and may need the B<-ssl2> option.
- =item B<-bugs>
- there are several known bug in SSL and TLS implementations. Adding this
- option enables various workarounds.
- =item B<-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
- supported cipher in the list sent by the client.
- See the L<ciphers(1)|ciphers(1)> command for more information.
- =item B<-time length>
- specifies how long (in seconds) B<s_time> should establish connections and
- optionally transfer payload data from a server. Server and client performance
- and the link speed determine how many connections B<s_time> can establish.
- =back
- =head1 NOTES
- B<s_client> can be used to measure the performance of an SSL connection.
- To connect to an SSL HTTP server and get the default page the command
- openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
- would typically be used (https uses port 443). 'commoncipher' is a cipher to
- which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command
- for details.
- 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> 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.
- A frequent problem when attempting to get client certificates 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 L<s_client(1)|s_client(1)> 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> option of L<s_client(1)|s_client(1)> and
- send an HTTP request for an appropriate page.
- If a certificate is specified on the command line using the B<-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.
- =head1 BUGS
- Because this program does not have all the options of the
- L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be
- able to measure the performance of all protocols with all servers.
- The B<-verify> option should really exit if the server verification
- fails.
- =head1 SEE ALSO
- L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
- =cut
|