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