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