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