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