]>
Commit | Line | Data |
---|---|---|
a2151c5b DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | s_server - SSL/TLS server program | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
a2bbe594 | 10 | B<openssl> B<s_server> |
a2151c5b | 11 | [B<-accept port>] |
642aa226 | 12 | [B<-naccept count>] |
a2151c5b DSH |
13 | [B<-context id>] |
14 | [B<-verify depth>] | |
15 | [B<-Verify depth>] | |
51e00db2 LJ |
16 | [B<-crl_check>] |
17 | [B<-crl_check_all>] | |
a2151c5b | 18 | [B<-cert filename>] |
826a42a0 | 19 | [B<-certform DER|PEM>] |
a2151c5b | 20 | [B<-key keyfile>] |
826a42a0 DSH |
21 | [B<-keyform DER|PEM>] |
22 | [B<-pass arg>] | |
a2151c5b | 23 | [B<-dcert filename>] |
826a42a0 | 24 | [B<-dcertform DER|PEM>] |
a2151c5b | 25 | [B<-dkey keyfile>] |
826a42a0 DSH |
26 | [B<-dkeyform DER|PEM>] |
27 | [B<-dpass arg>] | |
a2151c5b DSH |
28 | [B<-dhparam filename>] |
29 | [B<-nbio>] | |
30 | [B<-nbio_test>] | |
31 | [B<-crlf>] | |
32 | [B<-debug>] | |
1d8634b1 | 33 | [B<-msg>] |
a2151c5b DSH |
34 | [B<-state>] |
35 | [B<-CApath directory>] | |
36 | [B<-CAfile filename>] | |
e42d84be HK |
37 | [B<-attime timestamp>] |
38 | [B<-check_ss_sig>] | |
39 | [B<-explicit_policy>] | |
40 | [B<-extended_crl>] | |
41 | [B<-ignore_critical>] | |
42 | [B<-inhibit_any>] | |
43 | [B<-inhibit_map>] | |
44 | [B<-issuer_checks>] | |
45 | [B<-partial_chain>] | |
46 | [B<-policy arg>] | |
47 | [B<-policy_check>] | |
48 | [B<-policy_print>] | |
49 | [B<-purpose purpose>] | |
50 | [B<-suiteB_128>] | |
51 | [B<-suiteB_128_only>] | |
52 | [B<-suiteB_192>] | |
6d3d5793 | 53 | [B<-trusted_first>] |
e42d84be HK |
54 | [B<-use_deltas>] |
55 | [B<-verify_depth num>] | |
56 | [B<-verify_email email>] | |
57 | [B<-verify_hostname hostname>] | |
58 | [B<-verify_ip ip>] | |
59 | [B<-verify_name name>] | |
60 | [B<-x509_strict>] | |
a2151c5b DSH |
61 | [B<-nocert>] |
62 | [B<-cipher cipherlist>] | |
fc1d88f0 | 63 | [B<-serverpref>] |
a2151c5b DSH |
64 | [B<-quiet>] |
65 | [B<-no_tmp_rsa>] | |
66 | [B<-ssl2>] | |
67 | [B<-ssl3>] | |
68 | [B<-tls1>] | |
69 | [B<-no_ssl2>] | |
70 | [B<-no_ssl3>] | |
71 | [B<-no_tls1>] | |
72 | [B<-no_dhe>] | |
08bef7be | 73 | [B<-no_ecdhe>] |
a2151c5b | 74 | [B<-bugs>] |
765b4137 | 75 | [B<-brief>] |
4b08eaf5 | 76 | [B<-hack>] |
a2151c5b DSH |
77 | [B<-www>] |
78 | [B<-WWW>] | |
7b825005 | 79 | [B<-HTTP>] |
5270e702 | 80 | [B<-engine id>] |
d24a9c8f DSH |
81 | [B<-tlsextdebug>] |
82 | [B<-no_ticket>] | |
e986704d | 83 | [B<-id_prefix arg>] |
52b621db | 84 | [B<-rand file(s)>] |
9cd50f73 | 85 | [B<-serverinfo file>] |
36086186 | 86 | [B<-no_resumption_on_reneg>] |
a2151c5b DSH |
87 | =head1 DESCRIPTION |
88 | ||
89 | The B<s_server> command implements a generic SSL/TLS server which listens | |
90 | for connections on a given port using SSL/TLS. | |
91 | ||
92 | =head1 OPTIONS | |
93 | ||
765b4137 DSH |
94 | In addition to the options below the B<s_server> utility also supports the |
95 | common and server only options documented in the | |
13cfb043 DSH |
96 | L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)/SUPPORTED COMMAND LINE COMMANDS> manual |
97 | page. | |
765b4137 | 98 | |
a2151c5b DSH |
99 | =over 4 |
100 | ||
101 | =item B<-accept port> | |
102 | ||
103 | the TCP port to listen on for connections. If not specified 4433 is used. | |
104 | ||
642aa226 DSH |
105 | =item B<-naccept count> |
106 | ||
107 | The server will exit after receiving B<number> connections, default unlimited. | |
108 | ||
a2151c5b DSH |
109 | =item B<-context id> |
110 | ||
cc8709a0 DSH |
111 | sets the SSL context id. It can be given any string value. If this option |
112 | is not present a default value will be used. | |
a2151c5b DSH |
113 | |
114 | =item B<-cert certname> | |
115 | ||
116 | The certificate to use, most servers cipher suites require the use of a | |
117 | certificate and some require a certificate with a certain public key type: | |
118 | for example the DSS cipher suites require a certificate containing a DSS | |
119 | (DSA) key. If not specified then the filename "server.pem" will be used. | |
120 | ||
826a42a0 DSH |
121 | =item B<-certform format> |
122 | ||
123 | The certificate format to use: DER or PEM. PEM is the default. | |
124 | ||
a2151c5b DSH |
125 | =item B<-key keyfile> |
126 | ||
127 | The private key to use. If not specified then the certificate file will | |
128 | be used. | |
129 | ||
826a42a0 DSH |
130 | =item B<-keyform format> |
131 | ||
132 | The private format to use: DER or PEM. PEM is the default. | |
133 | ||
134 | =item B<-pass arg> | |
135 | ||
136 | the private key password source. For more information about the format of B<arg> | |
137 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. | |
138 | ||
a2151c5b DSH |
139 | =item B<-dcert filename>, B<-dkey keyname> |
140 | ||
141 | specify an additional certificate and private key, these behave in the | |
142 | same manner as the B<-cert> and B<-key> options except there is no default | |
143 | if they are not specified (no additional certificate and key is used). As | |
144 | noted above some cipher suites require a certificate containing a key of | |
145 | a certain type. Some cipher suites need a certificate carrying an RSA key | |
146 | and some a DSS (DSA) key. By using RSA and DSS certificates and keys | |
147 | a server can support clients which only support RSA or DSS cipher suites | |
148 | by using an appropriate certificate. | |
149 | ||
826a42a0 DSH |
150 | =item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg> |
151 | ||
2b4ffc65 | 152 | additional certificate and private key format and passphrase respectively. |
826a42a0 | 153 | |
a2151c5b DSH |
154 | =item B<-nocert> |
155 | ||
156 | if this option is set then no certificate is used. This restricts the | |
157 | cipher suites available to the anonymous ones (currently just anonymous | |
158 | DH). | |
159 | ||
160 | =item B<-dhparam filename> | |
161 | ||
162 | the DH parameter file to use. The ephemeral DH cipher suites generate keys | |
163 | using a set of DH parameters. If not specified then an attempt is made to | |
164 | load the parameters from the server certificate file. If this fails then | |
165 | a static set of parameters hard coded into the s_server program will be used. | |
166 | ||
45ecfb19 | 167 | =item B<-no_dhe> |
a2151c5b DSH |
168 | |
169 | if this option is set then no DH parameters will be loaded effectively | |
170 | disabling the ephemeral DH cipher suites. | |
171 | ||
08bef7be HK |
172 | =item B<-no_ecdhe> |
173 | ||
174 | if this option is set then no ECDH parameters will be loaded effectively | |
175 | disabling the ephemeral ECDH cipher suites. | |
176 | ||
a2151c5b DSH |
177 | =item B<-no_tmp_rsa> |
178 | ||
179 | certain export cipher suites sometimes use a temporary RSA key, this option | |
180 | disables temporary RSA key generation. | |
181 | ||
182 | =item B<-verify depth>, B<-Verify depth> | |
183 | ||
184 | The verify depth to use. This specifies the maximum length of the | |
185 | client certificate chain and makes the server request a certificate from | |
186 | the client. With the B<-verify> option a certificate is requested but the | |
187 | client does not have to send one, with the B<-Verify> option the client | |
188 | must supply a certificate or an error occurs. | |
189 | ||
51e00db2 LJ |
190 | =item B<-crl_check>, B<-crl_check_all> |
191 | ||
192 | Check the peer certificate has not been revoked by its CA. | |
193 | The CRL(s) are appended to the certificate file. With the B<-crl_check_all> | |
194 | option all CRLs of all CAs in the chain are checked. | |
195 | ||
a2151c5b DSH |
196 | =item B<-CApath directory> |
197 | ||
198 | The directory to use for client certificate verification. This directory | |
199 | must be in "hash format", see B<verify> for more information. These are | |
200 | also used when building the server certificate chain. | |
201 | ||
202 | =item B<-CAfile file> | |
203 | ||
204 | A file containing trusted certificates to use during client authentication | |
205 | and to use when attempting to build the server certificate chain. The list | |
206 | is also used in the list of acceptable client CAs passed to the client when | |
207 | a certificate is requested. | |
208 | ||
e42d84be HK |
209 | =item B<-attime>, B<-check_ss_sig>, B<explicit_policy>, B<-extended_crl>, |
210 | B<-ignore_critical>, B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, | |
211 | B<-partial_chain>, B<-policy>, B<-policy_check>, B<-policy_print>, B<-purpose>, | |
212 | B<-suiteB_128>, B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, | |
213 | B<-use_deltas>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, | |
214 | B<-verify_ip>, B<-verify_name>, B<-x509_strict> | |
6d3d5793 | 215 | |
e42d84be | 216 | Set different peer certificate verification options. |
6d3d5793 HK |
217 | See the L<B<verify>|verify(1)> manual page for details. |
218 | ||
a2151c5b DSH |
219 | =item B<-state> |
220 | ||
221 | prints out the SSL session states. | |
222 | ||
223 | =item B<-debug> | |
224 | ||
225 | print extensive debugging information including a hex dump of all traffic. | |
226 | ||
1d8634b1 BM |
227 | =item B<-msg> |
228 | ||
229 | show all protocol messages with hex dump. | |
230 | ||
8dbeb110 DSH |
231 | =item B<-trace> |
232 | ||
233 | show verbose trace output of protocol messages. OpenSSL needs to be compiled | |
234 | with B<enable-ssl-trace> for this option to work. | |
235 | ||
236 | =item B<-msgfile> | |
237 | ||
238 | file to send output of B<-msg> or B<-trace> to, default standard output. | |
239 | ||
a2151c5b DSH |
240 | =item B<-nbio_test> |
241 | ||
242 | tests non blocking I/O | |
243 | ||
244 | =item B<-nbio> | |
245 | ||
246 | turns on non blocking I/O | |
247 | ||
248 | =item B<-crlf> | |
249 | ||
250 | this option translated a line feed from the terminal into CR+LF. | |
251 | ||
252 | =item B<-quiet> | |
253 | ||
254 | inhibit printing of session and certificate information. | |
255 | ||
ddac1974 NL |
256 | =item B<-psk_hint hint> |
257 | ||
258 | Use the PSK identity hint B<hint> when using a PSK cipher suite. | |
259 | ||
260 | =item B<-psk key> | |
261 | ||
262 | Use the PSK key B<key> when using a PSK cipher suite. The key is | |
263 | given as a hexadecimal number without leading 0x, for example -psk | |
264 | 1a2b3c4d. | |
265 | ||
a2151c5b DSH |
266 | =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> |
267 | ||
268 | these options disable the use of certain SSL or TLS protocols. By default | |
269 | the initial handshake uses a method which should be compatible with all | |
270 | servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. | |
271 | ||
272 | =item B<-bugs> | |
273 | ||
274 | there are several known bug in SSL and TLS implementations. Adding this | |
275 | option enables various workarounds. | |
276 | ||
765b4137 DSH |
277 | =item B<-brief> |
278 | ||
279 | only provide a brief summary of connection parameters instead of the | |
280 | normal verbose output. | |
281 | ||
4b08eaf5 DSH |
282 | =item B<-hack> |
283 | ||
284 | this option enables a further workaround for some some early Netscape | |
285 | SSL code (?). | |
286 | ||
a2151c5b DSH |
287 | =item B<-cipher cipherlist> |
288 | ||
fabce041 DSH |
289 | this allows the cipher list used by the server to be modified. When |
290 | the client sends a list of supported ciphers the first client cipher | |
291 | also included in the server list is used. Because the client specifies | |
292 | the preference order, the order of the server cipherlist irrelevant. See | |
293 | the B<ciphers> command for more information. | |
a2151c5b | 294 | |
fc1d88f0 RS |
295 | =item B<-serverpref> |
296 | ||
297 | use the server's cipher preferences, rather than the client's preferences. | |
298 | ||
d24a9c8f DSH |
299 | =item B<-tlsextdebug> |
300 | ||
301 | print out a hex dump of any TLS extensions received from the server. | |
302 | ||
303 | =item B<-no_ticket> | |
304 | ||
305 | disable RFC4507bis session ticket support. | |
306 | ||
a2151c5b DSH |
307 | =item B<-www> |
308 | ||
309 | sends a status message back to the client when it connects. This includes | |
310 | lots of information about the ciphers used and various session parameters. | |
311 | The output is in HTML format so this option will normally be used with a | |
312 | web browser. | |
313 | ||
314 | =item B<-WWW> | |
315 | ||
316 | emulates a simple web server. Pages will be resolved relative to the | |
317 | current directory, for example if the URL https://myhost/page.html is | |
318 | requested the file ./page.html will be loaded. | |
319 | ||
7b825005 RL |
320 | =item B<-HTTP> |
321 | ||
322 | emulates a simple web server. Pages will be resolved relative to the | |
323 | current directory, for example if the URL https://myhost/page.html is | |
324 | requested the file ./page.html will be loaded. The files loaded are | |
325 | assumed to contain a complete and correct HTTP response (lines that | |
3b80e3aa | 326 | are part of the HTTP response line and headers must end with CRLF). |
7b825005 | 327 | |
765b4137 DSH |
328 | =item B<-rev> |
329 | ||
330 | simple test server which just reverses the text received from the client | |
331 | and sends it back to the server. Also sets B<-brief>. | |
332 | ||
5270e702 RL |
333 | =item B<-engine id> |
334 | ||
e5fa864f | 335 | specifying an engine (by its unique B<id> string) will cause B<s_server> |
5270e702 RL |
336 | to attempt to obtain a functional reference to the specified engine, |
337 | thus initialising it if needed. The engine will then be set as the default | |
338 | for all available algorithms. | |
339 | ||
e986704d RL |
340 | =item B<-id_prefix arg> |
341 | ||
342 | generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful | |
343 | for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple | |
344 | servers, when each of which might be generating a unique range of session | |
345 | IDs (eg. with a certain prefix). | |
346 | ||
52b621db LJ |
347 | =item B<-rand file(s)> |
348 | ||
349 | a file or files containing random data used to seed the random number | |
350 | generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). | |
351 | Multiple files can be specified separated by a OS-dependent character. | |
352 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for | |
353 | all others. | |
354 | ||
9cd50f73 T |
355 | =item B<-serverinfo file> |
356 | ||
357 | a file containing one or more blocks of PEM data. Each PEM block | |
358 | must encode a TLS ServerHello extension (2 bytes type, 2 bytes length, | |
359 | followed by "length" bytes of extension data). If the client sends | |
360 | an empty TLS ClientHello extension matching the type, the corresponding | |
361 | ServerHello extension will be returned. | |
362 | ||
36086186 SD |
363 | =item B<-no_resumption_on_reneg> |
364 | ||
b948ee27 | 365 | set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. |
36086186 | 366 | |
a2151c5b DSH |
367 | =back |
368 | ||
369 | =head1 CONNECTED COMMANDS | |
370 | ||
371 | If a connection request is established with an SSL client and neither the | |
4b08eaf5 DSH |
372 | B<-www> nor the B<-WWW> option has been used then normally any data received |
373 | from the client is displayed and any key presses will be sent to the client. | |
374 | ||
657e60fa | 375 | Certain single letter commands are also recognized which perform special |
4b08eaf5 DSH |
376 | operations: these are listed below. |
377 | ||
378 | =over 4 | |
379 | ||
380 | =item B<q> | |
381 | ||
382 | end the current SSL connection but still accept new connections. | |
383 | ||
384 | =item B<Q> | |
385 | ||
386 | end the current SSL connection and exit. | |
387 | ||
388 | =item B<r> | |
389 | ||
390 | renegotiate the SSL session. | |
391 | ||
392 | =item B<R> | |
393 | ||
394 | renegotiate the SSL session and request a client certificate. | |
395 | ||
396 | =item B<P> | |
397 | ||
398 | send some plain text down the underlying TCP connection: this should | |
399 | cause the client to disconnect due to a protocol violation. | |
400 | ||
401 | =item B<S> | |
402 | ||
403 | print out some session cache status information. | |
404 | ||
405 | =back | |
a2151c5b DSH |
406 | |
407 | =head1 NOTES | |
408 | ||
409 | B<s_server> can be used to debug SSL clients. To accept connections from | |
410 | a web browser the command: | |
411 | ||
412 | openssl s_server -accept 443 -www | |
413 | ||
414 | can be used for example. | |
415 | ||
416 | Most web browsers (in particular Netscape and MSIE) only support RSA cipher | |
417 | suites, so they cannot connect to servers which don't use a certificate | |
418 | carrying an RSA key or a version of OpenSSL with RSA disabled. | |
419 | ||
420 | Although specifying an empty list of CAs when requesting a client certificate | |
4b08eaf5 DSH |
421 | is strictly speaking a protocol violation, some SSL clients interpret this to |
422 | mean any CA is acceptable. This is useful for debugging purposes. | |
a2151c5b DSH |
423 | |
424 | The session parameters can printed out using the B<sess_id> program. | |
425 | ||
426 | =head1 BUGS | |
427 | ||
428 | Because this program has a lot of options and also because some of | |
429 | the techniques used are rather old, the C source of s_server is rather | |
430 | hard to read and not a model of how things should be done. A typical | |
431 | SSL server program would be much simpler. | |
432 | ||
433 | The output of common ciphers is wrong: it just gives the list of ciphers that | |
4b08eaf5 | 434 | OpenSSL recognizes and the client supports. |
a2151c5b DSH |
435 | |
436 | There should be a way for the B<s_server> program to print out details of any | |
437 | unknown cipher suites a client says it supports. | |
438 | ||
439 | =head1 SEE ALSO | |
440 | ||
bb075f88 | 441 | L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)> |
a2151c5b DSH |
442 | |
443 | =cut |