s_time.pod revision 325337
1 2=pod 3 4=head1 NAME 5 6openssl-s_time, 7s_time - SSL/TLS performance timing program 8 9=head1 SYNOPSIS 10 11B<openssl> B<s_time> 12[B<-connect host:port>] 13[B<-www page>] 14[B<-cert filename>] 15[B<-key filename>] 16[B<-CApath directory>] 17[B<-CAfile filename>] 18[B<-reuse>] 19[B<-new>] 20[B<-verify depth>] 21[B<-nbio>] 22[B<-time seconds>] 23[B<-ssl2>] 24[B<-ssl3>] 25[B<-bugs>] 26[B<-cipher cipherlist>] 27 28=head1 DESCRIPTION 29 30The B<s_time> command implements a generic SSL/TLS client which connects to a 31remote host using SSL/TLS. It can request a page from the server and includes 32the time to transfer the payload data in its timing measurements. It measures 33the number of connections within a given timeframe, the amount of data 34transferred (if any), and calculates the average time spent for one connection. 35 36=head1 OPTIONS 37 38=over 4 39 40=item B<-connect host:port> 41 42This specifies the host and optional port to connect to. 43 44=item B<-www page> 45 46This specifies the page to GET from the server. A value of '/' gets the 47index.htm[l] page. If this parameter is not specified, then B<s_time> will only 48perform the handshake to establish SSL connections but not transfer any 49payload data. 50 51=item B<-cert certname> 52 53The certificate to use, if one is requested by the server. The default is 54not to use a certificate. The file is in PEM format. 55 56=item B<-key keyfile> 57 58The private key to use. If not specified then the certificate file will 59be used. The file is in PEM format. 60 61=item B<-verify depth> 62 63The verify depth to use. This specifies the maximum length of the 64server certificate chain and turns on server certificate verification. 65Currently the verify operation continues after errors so all the problems 66with a certificate chain can be seen. As a side effect the connection 67will never fail due to a server certificate verify failure. 68 69=item B<-CApath directory> 70 71The directory to use for server certificate verification. This directory 72must be in "hash format", see B<verify> for more information. These are 73also used when building the client certificate chain. 74 75=item B<-CAfile file> 76 77A file containing trusted certificates to use during server authentication 78and to use when attempting to build the client certificate chain. 79 80=item B<-new> 81 82performs the timing test using a new session ID for each connection. 83If neither B<-new> nor B<-reuse> are specified, they are both on by default 84and executed in sequence. 85 86=item B<-reuse> 87 88performs the timing test using the same session ID; this can be used as a test 89that session caching is working. If neither B<-new> nor B<-reuse> are 90specified, they are both on by default and executed in sequence. 91 92=item B<-nbio> 93 94turns on non-blocking I/O. 95 96=item B<-ssl2>, B<-ssl3> 97 98these options disable the use of certain SSL or TLS protocols. By default 99the initial handshake uses a method which should be compatible with all 100servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. 101The timing program is not as rich in options to turn protocols on and off as 102the L<s_client(1)|s_client(1)> program and may not connect to all servers. 103 104Unfortunately there are a lot of ancient and broken servers in use which 105cannot handle this technique and will fail to connect. Some servers only 106work if TLS is turned off with the B<-ssl3> option; others 107will only support SSL v2 and may need the B<-ssl2> option. 108 109=item B<-bugs> 110 111there are several known bug in SSL and TLS implementations. Adding this 112option enables various workarounds. 113 114=item B<-cipher cipherlist> 115 116this allows the cipher list sent by the client to be modified. Although 117the server determines which cipher suite is used it should take the first 118supported cipher in the list sent by the client. 119See the L<ciphers(1)|ciphers(1)> command for more information. 120 121=item B<-time length> 122 123specifies how long (in seconds) B<s_time> should establish connections and 124optionally transfer payload data from a server. Server and client performance 125and the link speed determine how many connections B<s_time> can establish. 126 127=back 128 129=head1 NOTES 130 131B<s_time> can be used to measure the performance of an SSL connection. 132To connect to an SSL HTTP server and get the default page the command 133 134 openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3] 135 136would typically be used (https uses port 443). 'commoncipher' is a cipher to 137which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command 138for details. 139 140If the handshake fails then there are several possible causes, if it is 141nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, 142B<-ssl3> options can be tried 143in case it is a buggy server. In particular you should play with these 144options B<before> submitting a bug report to an OpenSSL mailing list. 145 146A frequent problem when attempting to get client certificates working 147is that a web client complains it has no certificates or gives an empty 148list to choose from. This is normally because the server is not sending 149the clients certificate authority in its "acceptable CA list" when it 150requests a certificate. By using L<s_client(1)|s_client(1)> the CA list can be 151viewed and checked. However some servers only request client authentication 152after a specific URL is requested. To obtain the list in this case it 153is necessary to use the B<-prexit> option of L<s_client(1)|s_client(1)> and 154send an HTTP request for an appropriate page. 155 156If a certificate is specified on the command line using the B<-cert> 157option it will not be used unless the server specifically requests 158a client certificate. Therefor merely including a client certificate 159on the command line is no guarantee that the certificate works. 160 161=head1 BUGS 162 163Because this program does not have all the options of the 164L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be 165able to measure the performance of all protocols with all servers. 166 167The B<-verify> option should really exit if the server verification 168fails. 169 170=head1 SEE ALSO 171 172L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> 173 174=cut 175