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