Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / usr.bin / openssl / man / s_server.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)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
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'
984263bc 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' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 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"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 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
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
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 #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
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'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
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
984263bc
MD
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)
984263bc
MD
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
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "S_SERVER 1"
e3261593 127.TH S_SERVER 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
984263bc 132.SH "NAME"
e3cdf75b 133s_server \- SSL/TLS server program
984263bc 134.SH "SYNOPSIS"
8b0cefbb
JR
135.IX Header "SYNOPSIS"
136\&\fBopenssl\fR \fBs_server\fR
984263bc
MD
137[\fB\-accept port\fR]
138[\fB\-context id\fR]
139[\fB\-verify depth\fR]
140[\fB\-Verify depth\fR]
aac4ff6f
PA
141[\fB\-crl_check\fR]
142[\fB\-crl_check_all\fR]
984263bc 143[\fB\-cert filename\fR]
a561f9ff 144[\fB\-certform DER|PEM\fR]
984263bc 145[\fB\-key keyfile\fR]
a561f9ff
SS
146[\fB\-keyform DER|PEM\fR]
147[\fB\-pass arg\fR]
984263bc 148[\fB\-dcert filename\fR]
a561f9ff 149[\fB\-dcertform DER|PEM\fR]
984263bc 150[\fB\-dkey keyfile\fR]
a561f9ff
SS
151[\fB\-dkeyform DER|PEM\fR]
152[\fB\-dpass arg\fR]
984263bc
MD
153[\fB\-dhparam filename\fR]
154[\fB\-nbio\fR]
155[\fB\-nbio_test\fR]
156[\fB\-crlf\fR]
157[\fB\-debug\fR]
158[\fB\-msg\fR]
159[\fB\-state\fR]
160[\fB\-CApath directory\fR]
161[\fB\-CAfile filename\fR]
162[\fB\-nocert\fR]
163[\fB\-cipher cipherlist\fR]
164[\fB\-quiet\fR]
165[\fB\-no_tmp_rsa\fR]
166[\fB\-ssl2\fR]
167[\fB\-ssl3\fR]
168[\fB\-tls1\fR]
169[\fB\-no_ssl2\fR]
170[\fB\-no_ssl3\fR]
171[\fB\-no_tls1\fR]
172[\fB\-no_dhe\fR]
173[\fB\-bugs\fR]
174[\fB\-hack\fR]
175[\fB\-www\fR]
176[\fB\-WWW\fR]
177[\fB\-HTTP\fR]
178[\fB\-engine id\fR]
2c0715f4
PA
179[\fB\-tlsextdebug\fR]
180[\fB\-no_ticket\fR]
e3cdf75b
JR
181[\fB\-id_prefix arg\fR]
182[\fB\-rand file(s)\fR]
984263bc 183.SH "DESCRIPTION"
8b0cefbb
JR
184.IX Header "DESCRIPTION"
185The \fBs_server\fR command implements a generic \s-1SSL/TLS\s0 server which listens
186for connections on a given port using \s-1SSL/TLS\s0.
984263bc 187.SH "OPTIONS"
8b0cefbb
JR
188.IX Header "OPTIONS"
189.IP "\fB\-accept port\fR" 4
190.IX Item "-accept port"
984263bc 191the \s-1TCP\s0 port to listen on for connections. If not specified 4433 is used.
8b0cefbb
JR
192.IP "\fB\-context id\fR" 4
193.IX Item "-context id"
984263bc
MD
194sets the \s-1SSL\s0 context id. It can be given any string value. If this option
195is not present a default value will be used.
8b0cefbb
JR
196.IP "\fB\-cert certname\fR" 4
197.IX Item "-cert certname"
984263bc
MD
198The certificate to use, most servers cipher suites require the use of a
199certificate and some require a certificate with a certain public key type:
200for example the \s-1DSS\s0 cipher suites require a certificate containing a \s-1DSS\s0
201(\s-1DSA\s0) key. If not specified then the filename \*(L"server.pem\*(R" will be used.
a561f9ff
SS
202.IP "\fB\-certform format\fR" 4
203.IX Item "-certform format"
204The certificate format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
8b0cefbb
JR
205.IP "\fB\-key keyfile\fR" 4
206.IX Item "-key keyfile"
984263bc
MD
207The private key to use. If not specified then the certificate file will
208be used.
a561f9ff
SS
209.IP "\fB\-keyform format\fR" 4
210.IX Item "-keyform format"
211The private format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
212.IP "\fB\-pass arg\fR" 4
213.IX Item "-pass arg"
214the private key password source. For more information about the format of \fBarg\fR
215see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
8b0cefbb
JR
216.IP "\fB\-dcert filename\fR, \fB\-dkey keyname\fR" 4
217.IX Item "-dcert filename, -dkey keyname"
984263bc
MD
218specify an additional certificate and private key, these behave in the
219same manner as the \fB\-cert\fR and \fB\-key\fR options except there is no default
220if they are not specified (no additional certificate and key is used). As
221noted above some cipher suites require a certificate containing a key of
222a certain type. Some cipher suites need a certificate carrying an \s-1RSA\s0 key
223and some a \s-1DSS\s0 (\s-1DSA\s0) key. By using \s-1RSA\s0 and \s-1DSS\s0 certificates and keys
224a server can support clients which only support \s-1RSA\s0 or \s-1DSS\s0 cipher suites
225by using an appropriate certificate.
a561f9ff
SS
226.IP "\fB\-dcertform format\fR, \fB\-dkeyform format\fR, \fB\-dpass arg\fR" 4
227.IX Item "-dcertform format, -dkeyform format, -dpass arg"
228addtional certificate and private key format and passphrase respectively.
8b0cefbb
JR
229.IP "\fB\-nocert\fR" 4
230.IX Item "-nocert"
984263bc
MD
231if this option is set then no certificate is used. This restricts the
232cipher suites available to the anonymous ones (currently just anonymous
8b0cefbb
JR
233\&\s-1DH\s0).
234.IP "\fB\-dhparam filename\fR" 4
235.IX Item "-dhparam filename"
984263bc
MD
236the \s-1DH\s0 parameter file to use. The ephemeral \s-1DH\s0 cipher suites generate keys
237using a set of \s-1DH\s0 parameters. If not specified then an attempt is made to
238load the parameters from the server certificate file. If this fails then
239a static set of parameters hard coded into the s_server program will be used.
8b0cefbb
JR
240.IP "\fB\-no_dhe\fR" 4
241.IX Item "-no_dhe"
984263bc
MD
242if this option is set then no \s-1DH\s0 parameters will be loaded effectively
243disabling the ephemeral \s-1DH\s0 cipher suites.
8b0cefbb
JR
244.IP "\fB\-no_tmp_rsa\fR" 4
245.IX Item "-no_tmp_rsa"
984263bc
MD
246certain export cipher suites sometimes use a temporary \s-1RSA\s0 key, this option
247disables temporary \s-1RSA\s0 key generation.
8b0cefbb
JR
248.IP "\fB\-verify depth\fR, \fB\-Verify depth\fR" 4
249.IX Item "-verify depth, -Verify depth"
984263bc
MD
250The verify depth to use. This specifies the maximum length of the
251client certificate chain and makes the server request a certificate from
252the client. With the \fB\-verify\fR option a certificate is requested but the
253client does not have to send one, with the \fB\-Verify\fR option the client
254must supply a certificate or an error occurs.
aac4ff6f
PA
255.IP "\fB\-crl_check\fR, \fB\-crl_check_all\fR" 4
256.IX Item "-crl_check, -crl_check_all"
257Check the peer certificate has not been revoked by its \s-1CA\s0.
258The \s-1CRL\s0(s) are appended to the certificate file. With the \fB\-crl_check_all\fR
259option all CRLs of all CAs in the chain are checked.
8b0cefbb
JR
260.IP "\fB\-CApath directory\fR" 4
261.IX Item "-CApath directory"
984263bc
MD
262The directory to use for client certificate verification. This directory
263must be in \*(L"hash format\*(R", see \fBverify\fR for more information. These are
264also used when building the server certificate chain.
8b0cefbb
JR
265.IP "\fB\-CAfile file\fR" 4
266.IX Item "-CAfile file"
984263bc
MD
267A file containing trusted certificates to use during client authentication
268and to use when attempting to build the server certificate chain. The list
269is also used in the list of acceptable client CAs passed to the client when
270a certificate is requested.
8b0cefbb
JR
271.IP "\fB\-state\fR" 4
272.IX Item "-state"
984263bc 273prints out the \s-1SSL\s0 session states.
8b0cefbb
JR
274.IP "\fB\-debug\fR" 4
275.IX Item "-debug"
984263bc 276print extensive debugging information including a hex dump of all traffic.
8b0cefbb
JR
277.IP "\fB\-msg\fR" 4
278.IX Item "-msg"
984263bc 279show all protocol messages with hex dump.
8b0cefbb
JR
280.IP "\fB\-nbio_test\fR" 4
281.IX Item "-nbio_test"
984263bc 282tests non blocking I/O
8b0cefbb
JR
283.IP "\fB\-nbio\fR" 4
284.IX Item "-nbio"
984263bc 285turns on non blocking I/O
8b0cefbb
JR
286.IP "\fB\-crlf\fR" 4
287.IX Item "-crlf"
984263bc 288this option translated a line feed from the terminal into \s-1CR+LF\s0.
8b0cefbb
JR
289.IP "\fB\-quiet\fR" 4
290.IX Item "-quiet"
984263bc 291inhibit printing of session and certificate information.
01185282
PA
292.IP "\fB\-psk_hint hint\fR" 4
293.IX Item "-psk_hint hint"
294Use the \s-1PSK\s0 identity hint \fBhint\fR when using a \s-1PSK\s0 cipher suite.
295.IP "\fB\-psk key\fR" 4
296.IX Item "-psk key"
297Use the \s-1PSK\s0 key \fBkey\fR when using a \s-1PSK\s0 cipher suite. The key is
298given as a hexadecimal number without leading 0x, for example \-psk
2991a2b3c4d.
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"
01185282 346specifying an engine (by its unique \fBid\fR string) will cause \fBs_server\fR
984263bc
MD
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.
410.SH "BUGS"
8b0cefbb 411.IX Header "BUGS"
984263bc
MD
412Because this program has a lot of options and also because some of
413the techniques used are rather old, the C source of s_server is rather
414hard to read and not a model of how things should be done. A typical
8b0cefbb 415\&\s-1SSL\s0 server program would be much simpler.
984263bc
MD
416.PP
417The output of common ciphers is wrong: it just gives the list of ciphers that
418OpenSSL recognizes and the client supports.
419.PP
420There should be a way for the \fBs_server\fR program to print out details of any
421unknown cipher suites a client says it supports.
422.SH "SEE ALSO"
e3cdf75b 423.IX Header "SEE ALSO"
8b0cefbb 424\&\fIsess_id\fR\|(1), \fIs_client\fR\|(1), \fIciphers\fR\|(1)