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