| blob | 59c452e4ee4ff62a2dde006683b42e293006ac37 |
1 .\" $NetBSD: openssl_s_time.1,v 1.14 2015/06/12 17:01:15 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "S_TIME 1"
138 .TH S_TIME 1 "2009-07-19" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 s_time \- SSL/TLS performance timing program
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 \&\fBopenssl\fR \fBs_time\fR
150 [\fB\-connect host:port\fR]
151 [\fB\-www page\fR]
152 [\fB\-cert filename\fR]
153 [\fB\-key filename\fR]
154 [\fB\-CApath directory\fR]
155 [\fB\-CAfile filename\fR]
156 [\fB\-reuse\fR]
157 [\fB\-new\fR]
158 [\fB\-verify depth\fR]
159 [\fB\-nbio\fR]
160 [\fB\-time seconds\fR]
161 [\fB\-ssl2\fR]
162 [\fB\-ssl3\fR]
163 [\fB\-bugs\fR]
164 [\fB\-cipher cipherlist\fR]
165 .SH "DESCRIPTION"
166 .IX Header "DESCRIPTION"
167 The \fBs_client\fR command implements a generic \s-1SSL/TLS\s0 client which connects to a
168 remote host using \s-1SSL/TLS.\s0 It can request a page from the server and includes
169 the time to transfer the payload data in its timing measurements. It measures
170 the number of connections within a given timeframe, the amount of data
171 transferred (if any), and calculates the average time spent for one connection.
172 .SH "OPTIONS"
173 .IX Header "OPTIONS"
174 .IP "\fB\-connect host:port\fR" 4
175 .IX Item "-connect host:port"
176 This specifies the host and optional port to connect to.
177 .IP "\fB\-www page\fR" 4
178 .IX Item "-www page"
179 This specifies the page to \s-1GET\s0 from the server. A value of '/' gets the
180 index.htm[l] page. If this parameter is not specified, then \fBs_time\fR will only
181 perform the handshake to establish \s-1SSL\s0 connections but not transfer any
182 payload data.
183 .IP "\fB\-cert certname\fR" 4
184 .IX Item "-cert certname"
185 The certificate to use, if one is requested by the server. The default is
186 not to use a certificate. The file is in \s-1PEM\s0 format.
187 .IP "\fB\-key keyfile\fR" 4
188 .IX Item "-key keyfile"
189 The private key to use. If not specified then the certificate file will
190 be used. The file is in \s-1PEM\s0 format.
191 .IP "\fB\-verify depth\fR" 4
192 .IX Item "-verify depth"
193 The verify depth to use. This specifies the maximum length of the
194 server certificate chain and turns on server certificate verification.
195 Currently the verify operation continues after errors so all the problems
196 with a certificate chain can be seen. As a side effect the connection
197 will never fail due to a server certificate verify failure.
198 .IP "\fB\-CApath directory\fR" 4
199 .IX Item "-CApath directory"
200 The directory to use for server certificate verification. This directory
201 must be in \*(L"hash format\*(R", see \fBverify\fR for more information. These are
202 also used when building the client certificate chain.
203 .IP "\fB\-CAfile file\fR" 4
204 .IX Item "-CAfile file"
205 A file containing trusted certificates to use during server authentication
206 and to use when attempting to build the client certificate chain.
207 .IP "\fB\-new\fR" 4
208 .IX Item "-new"
209 performs the timing test using a new session \s-1ID\s0 for each connection.
210 If neither \fB\-new\fR nor \fB\-reuse\fR are specified, they are both on by default
211 and executed in sequence.
212 .IP "\fB\-reuse\fR" 4
213 .IX Item "-reuse"
214 performs the timing test using the same session \s-1ID\s0; this can be used as a test
215 that session caching is working. If neither \fB\-new\fR nor \fB\-reuse\fR are
216 specified, they are both on by default and executed in sequence.
217 .IP "\fB\-nbio\fR" 4
218 .IX Item "-nbio"
219 turns on non-blocking I/O.
220 .IP "\fB\-ssl2\fR, \fB\-ssl3\fR" 4
221 .IX Item "-ssl2, -ssl3"
222 these options disable the use of certain \s-1SSL\s0 or \s-1TLS\s0 protocols. By default
223 the initial handshake uses a method which should be compatible with all
224 servers and permit them to use \s-1SSL\s0 v3, \s-1SSL\s0 v2 or \s-1TLS\s0 as appropriate.
225 The timing program is not as rich in options to turn protocols on and off as
226 the \fIopenssl_s_client\fR\|(1) program and may not connect to all servers.
227 .Sp
228 Unfortunately there are a lot of ancient and broken servers in use which
229 cannot handle this technique and will fail to connect. Some servers only
230 work if \s-1TLS\s0 is turned off with the \fB\-ssl3\fR option; others
231 will only support \s-1SSL\s0 v2 and may need the \fB\-ssl2\fR option.
232 .IP "\fB\-bugs\fR" 4
233 .IX Item "-bugs"
234 there are several known bug in \s-1SSL\s0 and \s-1TLS\s0 implementations. Adding this
235 option enables various workarounds.
236 .IP "\fB\-cipher cipherlist\fR" 4
237 .IX Item "-cipher cipherlist"
238 this allows the cipher list sent by the client to be modified. Although
239 the server determines which cipher suite is used it should take the first
240 supported cipher in the list sent by the client.
241 See the \fIopenssl_ciphers\fR\|(1) command for more information.
242 .IP "\fB\-time length\fR" 4
243 .IX Item "-time length"
244 specifies how long (in seconds) \fBs_time\fR should establish connections and
245 optionally transfer payload data from a server. Server and client performance
246 and the link speed determine how many connections \fBs_time\fR can establish.
247 .SH "NOTES"
248 .IX Header "NOTES"
249 \&\fBs_client\fR can be used to measure the performance of an \s-1SSL\s0 connection.
250 To connect to an \s-1SSL HTTP\s0 server and get the default page the command
251 .PP
252 .Vb 1
253 \& openssl s_time \-connect servername:443 \-www / \-CApath yourdir \-CAfile yourfile.pem \-cipher commoncipher [\-ssl3]
254 .Ve
255 .PP
256 would typically be used (https uses port 443). 'commoncipher' is a cipher to
257 which both client and server can agree, see the \fIopenssl_ciphers\fR\|(1) command
258 for details.
259 .PP
260 If the handshake fails then there are several possible causes, if it is
261 nothing obvious like no client certificate then the \fB\-bugs\fR, \fB\-ssl2\fR,
262 \&\fB\-ssl3\fR options can be tried
263 in case it is a buggy server. In particular you should play with these
264 options \fBbefore\fR submitting a bug report to an OpenSSL mailing list.
265 .PP
266 A frequent problem when attempting to get client certificates working
267 is that a web client complains it has no certificates or gives an empty
268 list to choose from. This is normally because the server is not sending
269 the clients certificate authority in its \*(L"acceptable \s-1CA\s0 list\*(R" when it
270 requests a certificate. By using \fIopenssl_s_client\fR\|(1) the \s-1CA\s0 list can be
271 viewed and checked. However some servers only request client authentication
272 after a specific \s-1URL\s0 is requested. To obtain the list in this case it
273 is necessary to use the \fB\-prexit\fR option of \fIopenssl_s_client\fR\|(1) and
274 send an \s-1HTTP\s0 request for an appropriate page.
275 .PP
276 If a certificate is specified on the command line using the \fB\-cert\fR
277 option it will not be used unless the server specifically requests
278 a client certificate. Therefor merely including a client certificate
279 on the command line is no guarantee that the certificate works.
280 .SH "BUGS"
281 .IX Header "BUGS"
282 Because this program does not have all the options of the
283 \&\fIopenssl_s_client\fR\|(1) program to turn protocols on and off, you may not be
284 able to measure the performance of all protocols with all servers.
285 .PP
286 The \fB\-verify\fR option should really exit if the server verification
287 fails.
288 .SH "SEE ALSO"
289 .IX Header "SEE ALSO"
290 \&\fIopenssl_s_client\fR\|(1), \fIopenssl_s_server\fR\|(1), \fIopenssl_ciphers\fR\|(1)