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