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