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