Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / usr.bin / openssl / man / s_server.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
984263bc
MD
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)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
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'
984263bc 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' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 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"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 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
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
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 #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
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'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
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
984263bc
MD
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)
984263bc
MD
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
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "S_SERVER 1"
e257b235
PA
135.TH S_SERVER 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
984263bc 140.SH "NAME"
e3cdf75b 141s_server \- SSL/TLS server program
984263bc 142.SH "SYNOPSIS"
8b0cefbb
JR
143.IX Header "SYNOPSIS"
144\&\fBopenssl\fR \fBs_server\fR
984263bc
MD
145[\fB\-accept port\fR]
146[\fB\-context id\fR]
147[\fB\-verify depth\fR]
148[\fB\-Verify depth\fR]
aac4ff6f
PA
149[\fB\-crl_check\fR]
150[\fB\-crl_check_all\fR]
984263bc 151[\fB\-cert filename\fR]
a561f9ff 152[\fB\-certform DER|PEM\fR]
984263bc 153[\fB\-key keyfile\fR]
a561f9ff
SS
154[\fB\-keyform DER|PEM\fR]
155[\fB\-pass arg\fR]
984263bc 156[\fB\-dcert filename\fR]
a561f9ff 157[\fB\-dcertform DER|PEM\fR]
984263bc 158[\fB\-dkey keyfile\fR]
a561f9ff
SS
159[\fB\-dkeyform DER|PEM\fR]
160[\fB\-dpass arg\fR]
984263bc
MD
161[\fB\-dhparam filename\fR]
162[\fB\-nbio\fR]
163[\fB\-nbio_test\fR]
164[\fB\-crlf\fR]
165[\fB\-debug\fR]
166[\fB\-msg\fR]
167[\fB\-state\fR]
168[\fB\-CApath directory\fR]
169[\fB\-CAfile filename\fR]
170[\fB\-nocert\fR]
171[\fB\-cipher cipherlist\fR]
172[\fB\-quiet\fR]
173[\fB\-no_tmp_rsa\fR]
174[\fB\-ssl2\fR]
175[\fB\-ssl3\fR]
176[\fB\-tls1\fR]
177[\fB\-no_ssl2\fR]
178[\fB\-no_ssl3\fR]
179[\fB\-no_tls1\fR]
180[\fB\-no_dhe\fR]
181[\fB\-bugs\fR]
182[\fB\-hack\fR]
183[\fB\-www\fR]
184[\fB\-WWW\fR]
185[\fB\-HTTP\fR]
186[\fB\-engine id\fR]
2c0715f4
PA
187[\fB\-tlsextdebug\fR]
188[\fB\-no_ticket\fR]
e3cdf75b
JR
189[\fB\-id_prefix arg\fR]
190[\fB\-rand file(s)\fR]
984263bc 191.SH "DESCRIPTION"
8b0cefbb
JR
192.IX Header "DESCRIPTION"
193The \fBs_server\fR command implements a generic \s-1SSL/TLS\s0 server which listens
194for connections on a given port using \s-1SSL/TLS\s0.
984263bc 195.SH "OPTIONS"
8b0cefbb
JR
196.IX Header "OPTIONS"
197.IP "\fB\-accept port\fR" 4
198.IX Item "-accept port"
984263bc 199the \s-1TCP\s0 port to listen on for connections. If not specified 4433 is used.
8b0cefbb
JR
200.IP "\fB\-context id\fR" 4
201.IX Item "-context id"
984263bc
MD
202sets the \s-1SSL\s0 context id. It can be given any string value. If this option
203is not present a default value will be used.
8b0cefbb
JR
204.IP "\fB\-cert certname\fR" 4
205.IX Item "-cert certname"
984263bc
MD
206The certificate to use, most servers cipher suites require the use of a
207certificate and some require a certificate with a certain public key type:
208for example the \s-1DSS\s0 cipher suites require a certificate containing a \s-1DSS\s0
209(\s-1DSA\s0) key. If not specified then the filename \*(L"server.pem\*(R" will be used.
a561f9ff
SS
210.IP "\fB\-certform format\fR" 4
211.IX Item "-certform format"
212The certificate format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
8b0cefbb
JR
213.IP "\fB\-key keyfile\fR" 4
214.IX Item "-key keyfile"
984263bc
MD
215The private key to use. If not specified then the certificate file will
216be used.
a561f9ff
SS
217.IP "\fB\-keyform format\fR" 4
218.IX Item "-keyform format"
219The private format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
220.IP "\fB\-pass arg\fR" 4
221.IX Item "-pass arg"
222the private key password source. For more information about the format of \fBarg\fR
223see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
8b0cefbb
JR
224.IP "\fB\-dcert filename\fR, \fB\-dkey keyname\fR" 4
225.IX Item "-dcert filename, -dkey keyname"
984263bc
MD
226specify an additional certificate and private key, these behave in the
227same manner as the \fB\-cert\fR and \fB\-key\fR options except there is no default
228if they are not specified (no additional certificate and key is used). As
229noted above some cipher suites require a certificate containing a key of
230a certain type. Some cipher suites need a certificate carrying an \s-1RSA\s0 key
231and some a \s-1DSS\s0 (\s-1DSA\s0) key. By using \s-1RSA\s0 and \s-1DSS\s0 certificates and keys
232a server can support clients which only support \s-1RSA\s0 or \s-1DSS\s0 cipher suites
233by using an appropriate certificate.
a561f9ff
SS
234.IP "\fB\-dcertform format\fR, \fB\-dkeyform format\fR, \fB\-dpass arg\fR" 4
235.IX Item "-dcertform format, -dkeyform format, -dpass arg"
236addtional certificate and private key format and passphrase respectively.
8b0cefbb
JR
237.IP "\fB\-nocert\fR" 4
238.IX Item "-nocert"
984263bc
MD
239if this option is set then no certificate is used. This restricts the
240cipher suites available to the anonymous ones (currently just anonymous
8b0cefbb
JR
241\&\s-1DH\s0).
242.IP "\fB\-dhparam filename\fR" 4
243.IX Item "-dhparam filename"
984263bc
MD
244the \s-1DH\s0 parameter file to use. The ephemeral \s-1DH\s0 cipher suites generate keys
245using a set of \s-1DH\s0 parameters. If not specified then an attempt is made to
246load the parameters from the server certificate file. If this fails then
247a static set of parameters hard coded into the s_server program will be used.
8b0cefbb
JR
248.IP "\fB\-no_dhe\fR" 4
249.IX Item "-no_dhe"
984263bc
MD
250if this option is set then no \s-1DH\s0 parameters will be loaded effectively
251disabling the ephemeral \s-1DH\s0 cipher suites.
8b0cefbb
JR
252.IP "\fB\-no_tmp_rsa\fR" 4
253.IX Item "-no_tmp_rsa"
984263bc
MD
254certain export cipher suites sometimes use a temporary \s-1RSA\s0 key, this option
255disables temporary \s-1RSA\s0 key generation.
8b0cefbb
JR
256.IP "\fB\-verify depth\fR, \fB\-Verify depth\fR" 4
257.IX Item "-verify depth, -Verify depth"
984263bc
MD
258The verify depth to use. This specifies the maximum length of the
259client certificate chain and makes the server request a certificate from
260the client. With the \fB\-verify\fR option a certificate is requested but the
261client does not have to send one, with the \fB\-Verify\fR option the client
262must supply a certificate or an error occurs.
aac4ff6f
PA
263.IP "\fB\-crl_check\fR, \fB\-crl_check_all\fR" 4
264.IX Item "-crl_check, -crl_check_all"
265Check the peer certificate has not been revoked by its \s-1CA\s0.
266The \s-1CRL\s0(s) are appended to the certificate file. With the \fB\-crl_check_all\fR
267option all CRLs of all CAs in the chain are checked.
8b0cefbb
JR
268.IP "\fB\-CApath directory\fR" 4
269.IX Item "-CApath directory"
984263bc
MD
270The directory to use for client certificate verification. This directory
271must be in \*(L"hash format\*(R", see \fBverify\fR for more information. These are
272also used when building the server certificate chain.
8b0cefbb
JR
273.IP "\fB\-CAfile file\fR" 4
274.IX Item "-CAfile file"
984263bc
MD
275A file containing trusted certificates to use during client authentication
276and to use when attempting to build the server certificate chain. The list
277is also used in the list of acceptable client CAs passed to the client when
278a certificate is requested.
8b0cefbb
JR
279.IP "\fB\-state\fR" 4
280.IX Item "-state"
984263bc 281prints out the \s-1SSL\s0 session states.
8b0cefbb
JR
282.IP "\fB\-debug\fR" 4
283.IX Item "-debug"
984263bc 284print extensive debugging information including a hex dump of all traffic.
8b0cefbb
JR
285.IP "\fB\-msg\fR" 4
286.IX Item "-msg"
984263bc 287show all protocol messages with hex dump.
8b0cefbb
JR
288.IP "\fB\-nbio_test\fR" 4
289.IX Item "-nbio_test"
984263bc 290tests non blocking I/O
8b0cefbb
JR
291.IP "\fB\-nbio\fR" 4
292.IX Item "-nbio"
984263bc 293turns on non blocking I/O
8b0cefbb
JR
294.IP "\fB\-crlf\fR" 4
295.IX Item "-crlf"
984263bc 296this option translated a line feed from the terminal into \s-1CR+LF\s0.
8b0cefbb
JR
297.IP "\fB\-quiet\fR" 4
298.IX Item "-quiet"
984263bc 299inhibit printing of session and certificate information.
8b0cefbb
JR
300.IP "\fB\-ssl2\fR, \fB\-ssl3\fR, \fB\-tls1\fR, \fB\-no_ssl2\fR, \fB\-no_ssl3\fR, \fB\-no_tls1\fR" 4
301.IX Item "-ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1"
984263bc
MD
302these options disable the use of certain \s-1SSL\s0 or \s-1TLS\s0 protocols. By default
303the initial handshake uses a method which should be compatible with all
304servers and permit them to use \s-1SSL\s0 v3, \s-1SSL\s0 v2 or \s-1TLS\s0 as appropriate.
8b0cefbb
JR
305.IP "\fB\-bugs\fR" 4
306.IX Item "-bugs"
984263bc
MD
307there are several known bug in \s-1SSL\s0 and \s-1TLS\s0 implementations. Adding this
308option enables various workarounds.
8b0cefbb
JR
309.IP "\fB\-hack\fR" 4
310.IX Item "-hack"
984263bc 311this option enables a further workaround for some some early Netscape
8b0cefbb
JR
312\&\s-1SSL\s0 code (?).
313.IP "\fB\-cipher cipherlist\fR" 4
314.IX Item "-cipher cipherlist"
984263bc
MD
315this allows the cipher list used by the server to be modified. When
316the client sends a list of supported ciphers the first client cipher
317also included in the server list is used. Because the client specifies
318the preference order, the order of the server cipherlist irrelevant. See
319the \fBciphers\fR command for more information.
2c0715f4
PA
320.IP "\fB\-tlsextdebug\fR" 4
321.IX Item "-tlsextdebug"
322print out a hex dump of any \s-1TLS\s0 extensions received from the server.
323.IP "\fB\-no_ticket\fR" 4
324.IX Item "-no_ticket"
e257b235 325disable RFC4507bis session ticket support.
8b0cefbb
JR
326.IP "\fB\-www\fR" 4
327.IX Item "-www"
984263bc
MD
328sends a status message back to the client when it connects. This includes
329lots of information about the ciphers used and various session parameters.
330The output is in \s-1HTML\s0 format so this option will normally be used with a
331web browser.
8b0cefbb
JR
332.IP "\fB\-WWW\fR" 4
333.IX Item "-WWW"
984263bc
MD
334emulates a simple web server. Pages will be resolved relative to the
335current directory, for example if the \s-1URL\s0 https://myhost/page.html is
336requested the file ./page.html will be loaded.
8b0cefbb
JR
337.IP "\fB\-HTTP\fR" 4
338.IX Item "-HTTP"
984263bc
MD
339emulates a simple web server. Pages will be resolved relative to the
340current directory, for example if the \s-1URL\s0 https://myhost/page.html is
341requested the file ./page.html will be loaded. The files loaded are
342assumed to contain a complete and correct \s-1HTTP\s0 response (lines that
343are part of the \s-1HTTP\s0 response line and headers must end with \s-1CRLF\s0).
8b0cefbb
JR
344.IP "\fB\-engine id\fR" 4
345.IX Item "-engine id"
984263bc
MD
346specifying an engine (by it's unique \fBid\fR string) will cause \fBs_server\fR
347to attempt to obtain a functional reference to the specified engine,
348thus initialising it if needed. The engine will then be set as the default
349for all available algorithms.
8b0cefbb
JR
350.IP "\fB\-id_prefix arg\fR" 4
351.IX Item "-id_prefix arg"
e3cdf75b
JR
352generate \s-1SSL/TLS\s0 session IDs prefixed by \fBarg\fR. This is mostly useful
353for testing any \s-1SSL/TLS\s0 code (eg. proxies) that wish to deal with multiple
354servers, when each of which might be generating a unique range of session
355IDs (eg. with a certain prefix).
8b0cefbb
JR
356.IP "\fB\-rand file(s)\fR" 4
357.IX Item "-rand file(s)"
984263bc 358a file or files containing random data used to seed the random number
8b0cefbb
JR
359generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
360Multiple files can be specified separated by a OS-dependent character.
e257b235 361The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
984263bc
MD
362all others.
363.SH "CONNECTED COMMANDS"
8b0cefbb
JR
364.IX Header "CONNECTED COMMANDS"
365If a connection request is established with an \s-1SSL\s0 client and neither the
366\&\fB\-www\fR nor the \fB\-WWW\fR option has been used then normally any data received
e257b235 367from the client is displayed and any key presses will be sent to the client.
984263bc
MD
368.PP
369Certain single letter commands are also recognized which perform special
370operations: these are listed below.
8b0cefbb
JR
371.IP "\fBq\fR" 4
372.IX Item "q"
984263bc 373end the current \s-1SSL\s0 connection but still accept new connections.
8b0cefbb
JR
374.IP "\fBQ\fR" 4
375.IX Item "Q"
984263bc 376end the current \s-1SSL\s0 connection and exit.
8b0cefbb
JR
377.IP "\fBr\fR" 4
378.IX Item "r"
984263bc 379renegotiate the \s-1SSL\s0 session.
8b0cefbb
JR
380.IP "\fBR\fR" 4
381.IX Item "R"
984263bc 382renegotiate the \s-1SSL\s0 session and request a client certificate.
8b0cefbb
JR
383.IP "\fBP\fR" 4
384.IX Item "P"
984263bc
MD
385send some plain text down the underlying \s-1TCP\s0 connection: this should
386cause the client to disconnect due to a protocol violation.
8b0cefbb
JR
387.IP "\fBS\fR" 4
388.IX Item "S"
984263bc
MD
389print out some session cache status information.
390.SH "NOTES"
8b0cefbb
JR
391.IX Header "NOTES"
392\&\fBs_server\fR can be used to debug \s-1SSL\s0 clients. To accept connections from
984263bc
MD
393a web browser the command:
394.PP
395.Vb 1
e257b235 396\& openssl s_server \-accept 443 \-www
984263bc 397.Ve
8b0cefbb 398.PP
984263bc
MD
399can be used for example.
400.PP
8b0cefbb 401Most web browsers (in particular Netscape and \s-1MSIE\s0) only support \s-1RSA\s0 cipher
984263bc 402suites, so they cannot connect to servers which don't use a certificate
8b0cefbb 403carrying an \s-1RSA\s0 key or a version of OpenSSL with \s-1RSA\s0 disabled.
984263bc
MD
404.PP
405Although specifying an empty list of CAs when requesting a client certificate
8b0cefbb
JR
406is strictly speaking a protocol violation, some \s-1SSL\s0 clients interpret this to
407mean any \s-1CA\s0 is acceptable. This is useful for debugging purposes.
984263bc
MD
408.PP
409The session parameters can printed out using the \fBsess_id\fR program.
2c0715f4
PA
410.PP
411\&\s-1TLS\s0 extensions are only supported in OpenSSL 0.9.8 if they are explictly
412enabled at compile time using for example the \fBenable-tlsext\fR switch.
984263bc 413.SH "BUGS"
8b0cefbb 414.IX Header "BUGS"
984263bc
MD
415Because this program has a lot of options and also because some of
416the techniques used are rather old, the C source of s_server is rather
417hard to read and not a model of how things should be done. A typical
8b0cefbb 418\&\s-1SSL\s0 server program would be much simpler.
984263bc
MD
419.PP
420The output of common ciphers is wrong: it just gives the list of ciphers that
421OpenSSL recognizes and the client supports.
422.PP
423There should be a way for the \fBs_server\fR program to print out details of any
424unknown cipher suites a client says it supports.
425.SH "SEE ALSO"
e3cdf75b 426.IX Header "SEE ALSO"
8b0cefbb 427\&\fIsess_id\fR\|(1), \fIs_client\fR\|(1), \fIciphers\fR\|(1)