Provided support for the -nameopt flag in s_client, s_server and s_time
[openssl.git] / doc / man1 / s_server.pod
1 =pod
2
3 =head1 NAME
4
5 s_server - SSL/TLS server program
6
7 =head1 SYNOPSIS
8
9 B<openssl> B<s_server>
10 [B<-help>]
11 [B<-port port>]
12 [B<-accept val>]
13 [B<-naccept count>]
14 [B<-unix val>]
15 [B<-unlink>]
16 [B<-4>]
17 [B<-6>]
18 [B<-context id>]
19 [B<-verify depth>]
20 [B<-Verify depth>]
21 [B<-crl_check>]
22 [B<-crl_check_all>]
23 [B<-cert filename>]
24 [B<-certform DER|PEM>]
25 [B<-key keyfile>]
26 [B<-keyform DER|PEM>]
27 [B<-pass arg>]
28 [B<-dcert filename>]
29 [B<-dcertform DER|PEM>]
30 [B<-dkey keyfile>]
31 [B<-dkeyform DER|PEM>]
32 [B<-dpass arg>]
33 [B<-dhparam filename>]
34 [B<-nbio>]
35 [B<-nbio_test>]
36 [B<-crlf>]
37 [B<-debug>]
38 [B<-msg>]
39 [B<-state>]
40 [B<-CApath directory>]
41 [B<-CAfile filename>]
42 [B<-no-CAfile>]
43 [B<-no-CApath>]
44 [B<-attime timestamp>]
45 [B<-check_ss_sig>]
46 [B<-explicit_policy>]
47 [B<-extended_crl>]
48 [B<-ignore_critical>]
49 [B<-inhibit_any>]
50 [B<-inhibit_map>]
51 [B<-no_check_time>]
52 [B<-partial_chain>]
53 [B<-policy arg>]
54 [B<-policy_check>]
55 [B<-policy_print>]
56 [B<-purpose purpose>]
57 [B<-suiteB_128>]
58 [B<-suiteB_128_only>]
59 [B<-suiteB_192>]
60 [B<-trusted_first>]
61 [B<-no_alt_chains>]
62 [B<-use_deltas>]
63 [B<-auth_level num>]
64 [B<-nameopt option>]
65 [B<-verify_depth num>]
66 [B<-verify_return_error>]
67 [B<-verify_email email>]
68 [B<-verify_hostname hostname>]
69 [B<-verify_ip ip>]
70 [B<-verify_name name>]
71 [B<-x509_strict>]
72 [B<-nocert>]
73 [B<-cipher cipherlist>]
74 [B<-serverpref>]
75 [B<-quiet>]
76 [B<-ssl3>]
77 [B<-tls1>]
78 [B<-tls1_1>]
79 [B<-tls1_2>]
80 [B<-tls1_3>]
81 [B<-dtls>]
82 [B<-dtls1>]
83 [B<-dtls1_2>]
84 [B<-listen>]
85 [B<-async>]
86 [B<-split_send_frag>]
87 [B<-max_pipelines>]
88 [B<-read_buf>]
89 [B<-no_ssl3>]
90 [B<-no_tls1>]
91 [B<-no_tls1_1>]
92 [B<-no_tls1_2>]
93 [B<-no_tls1_3>]
94 [B<-no_dhe>]
95 [B<-bugs>]
96 [B<-comp>]
97 [B<-no_comp>]
98 [B<-brief>]
99 [B<-www>]
100 [B<-WWW>]
101 [B<-HTTP>]
102 [B<-engine id>]
103 [B<-tlsextdebug>]
104 [B<-no_ticket>]
105 [B<-id_prefix arg>]
106 [B<-rand file(s)>]
107 [B<-serverinfo file>]
108 [B<-no_resumption_on_reneg>]
109 [B<-status>]
110 [B<-status_verbose>]
111 [B<-status_timeout nsec>]
112 [B<-status_url url>]
113 [B<-status_file file>]
114 [B<-alpn protocols>]
115 [B<-nextprotoneg protocols>]
116
117 =head1 DESCRIPTION
118
119 The B<s_server> command implements a generic SSL/TLS server which listens
120 for connections on a given port using SSL/TLS.
121
122 =head1 OPTIONS
123
124 In addition to the options below the B<s_server> utility also supports the
125 common and server only options documented in the
126 in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
127 manual page.
128
129 =over 4
130
131 =item B<-help>
132
133 Print out a usage message.
134
135 =item B<-port port>
136
137 The TCP port to listen on for connections. If not specified 4433 is used.
138
139 =item B<-accept val>
140
141 The optional TCP host and port to listen on for connections. If not specified, *:4433 is used.
142
143 =item B<-naccept count>
144
145 The server will exit after receiving B<number> connections, default unlimited.
146
147 =item B<-unix val>
148
149 Unix domain socket to accept on.
150
151 =item B<-unlink>
152
153 For -unix, unlink existing socket first.
154
155 =item B<-4>
156
157 Use IPv4 only.
158
159 =item B<-6>
160
161 Use IPv6 only.
162
163 =item B<-context id>
164
165 Sets the SSL context id. It can be given any string value. If this option
166 is not present a default value will be used.
167
168 =item B<-cert certname>
169
170 The certificate to use, most servers cipher suites require the use of a
171 certificate and some require a certificate with a certain public key type:
172 for example the DSS cipher suites require a certificate containing a DSS
173 (DSA) key. If not specified then the filename "server.pem" will be used.
174
175 =item B<-certform format>
176
177 The certificate format to use: DER or PEM. PEM is the default.
178
179 =item B<-key keyfile>
180
181 The private key to use. If not specified then the certificate file will
182 be used.
183
184 =item B<-keyform format>
185
186 The private format to use: DER or PEM. PEM is the default.
187
188 =item B<-pass arg>
189
190 The private key password source. For more information about the format of B<arg>
191 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
192
193 =item B<-dcert filename>, B<-dkey keyname>
194
195 Specify an additional certificate and private key, these behave in the
196 same manner as the B<-cert> and B<-key> options except there is no default
197 if they are not specified (no additional certificate and key is used). As
198 noted above some cipher suites require a certificate containing a key of
199 a certain type. Some cipher suites need a certificate carrying an RSA key
200 and some a DSS (DSA) key. By using RSA and DSS certificates and keys
201 a server can support clients which only support RSA or DSS cipher suites
202 by using an appropriate certificate.
203
204 =item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
205
206 Additional certificate and private key format and passphrase respectively.
207
208 =item B<-nocert>
209
210 If this option is set then no certificate is used. This restricts the
211 cipher suites available to the anonymous ones (currently just anonymous
212 DH).
213
214 =item B<-dhparam filename>
215
216 The DH parameter file to use. The ephemeral DH cipher suites generate keys
217 using a set of DH parameters. If not specified then an attempt is made to
218 load the parameters from the server certificate file.
219 If this fails then a static set of parameters hard coded into the B<s_server>
220 program will be used.
221
222 =item B<-no_dhe>
223
224 If this option is set then no DH parameters will be loaded effectively
225 disabling the ephemeral DH cipher suites.
226
227 =item B<-crl_check>, B<-crl_check_all>
228
229 Check the peer certificate has not been revoked by its CA.
230 The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
231 option all CRLs of all CAs in the chain are checked.
232
233 =item B<-CApath directory>
234
235 The directory to use for client certificate verification. This directory
236 must be in "hash format", see B<verify> for more information. These are
237 also used when building the server certificate chain.
238
239 =item B<-CAfile file>
240
241 A file containing trusted certificates to use during client authentication
242 and to use when attempting to build the server certificate chain. The list
243 is also used in the list of acceptable client CAs passed to the client when
244 a certificate is requested.
245
246 =item B<-no-CAfile>
247
248 Do not load the trusted CA certificates from the default file location
249
250 =item B<-no-CApath>
251
252 Do not load the trusted CA certificates from the default directory location
253
254 =item B<-verify depth>, B<-Verify depth>
255
256 The verify depth to use. This specifies the maximum length of the
257 client certificate chain and makes the server request a certificate from
258 the client. With the B<-verify> option a certificate is requested but the
259 client does not have to send one, with the B<-Verify> option the client
260 must supply a certificate or an error occurs.
261
262 If the ciphersuite cannot request a client certificate (for example an
263 anonymous ciphersuite or PSK) this option has no effect.
264
265 =item B<-nameopt option>
266
267 option which determines how the subject or issuer names are displayed. The
268 B<option> argument can be a single option or multiple options separated by
269 commas.  Alternatively the B<-nameopt> switch may be used more than once to
270 set multiple options. See the L<x509(1)> manual page for details.
271
272 =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
273 B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
274 B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
275 B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
276 B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
277 B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
278 B<-verify_ip>, B<-verify_name>, B<-x509_strict>
279
280 Set different peer certificate verification options.
281 See the L<verify(1)> manual page for details.
282
283 =item B<-verify_return_error>
284
285 Verification errors normally just print a message but allow the
286 connection to continue, for debugging purposes.
287 If this option is used, then verification errors close the connection.
288
289 =item B<-state>
290
291 Prints the SSL session states.
292
293 =item B<-debug>
294
295 Print extensive debugging information including a hex dump of all traffic.
296
297 =item B<-msg>
298
299 Show all protocol messages with hex dump.
300
301 =item B<-trace>
302
303 Show verbose trace output of protocol messages. OpenSSL needs to be compiled
304 with B<enable-ssl-trace> for this option to work.
305
306 =item B<-msgfile>
307
308 File to send output of B<-msg> or B<-trace> to, default standard output.
309
310 =item B<-nbio_test>
311
312 Tests non blocking I/O
313
314 =item B<-nbio>
315
316 Turns on non blocking I/O
317
318 =item B<-crlf>
319
320 This option translated a line feed from the terminal into CR+LF.
321
322 =item B<-quiet>
323
324 Inhibit printing of session and certificate information.
325
326 =item B<-psk_hint hint>
327
328 Use the PSK identity hint B<hint> when using a PSK cipher suite.
329
330 =item B<-psk key>
331
332 Use the PSK key B<key> when using a PSK cipher suite. The key is
333 given as a hexadecimal number without leading 0x, for example -psk
334 1a2b3c4d.
335
336 =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
337
338 These options require or disable the use of the specified SSL or TLS protocols.
339 By default B<s_server> will negotiate the highest mutually supported protocol
340 version.
341 When a specific TLS version is required, only that version will be accepted
342 from the client.
343
344 =item B<-dtls>, B<-dtls1>, B<-dtls1_2>
345
346 These options make B<s_server> use DTLS protocols instead of TLS.
347 With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
348 whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
349 respectively.
350
351 =item B<-listen>
352
353 This option can only be used in conjunction with one of the DTLS options above.
354 With this option B<s_server> will listen on a UDP port for incoming connections.
355 Any ClientHellos that arrive will be checked to see if they have a cookie in
356 them or not.
357 Any without a cookie will be responded to with a HelloVerifyRequest.
358 If a ClientHello with a cookie is received then B<s_server> will connect to
359 that peer and complete the handshake.
360
361 =item B<-async>
362
363 Switch on asynchronous mode. Cryptographic operations will be performed
364 asynchronously. This will only have an effect if an asynchronous capable engine
365 is also used via the B<-engine> option. For test purposes the dummy async engine
366 (dasync) can be used (if available).
367
368 =item B<-split_send_frag int>
369
370 The size used to split data for encrypt pipelines. If more data is written in
371 one go than this value then it will be split into multiple pipelines, up to the
372 maximum number of pipelines defined by max_pipelines. This only has an effect if
373 a suitable ciphersuite has been negotiated, an engine that supports pipelining
374 has been loaded, and max_pipelines is greater than 1. See
375 L<SSL_CTX_set_split_send_fragment(3)> for further information.
376
377 =item B<-max_pipelines int>
378
379 The maximum number of encrypt/decrypt pipelines to be used. This will only have
380 an effect if an engine has been loaded that supports pipelining (e.g. the dasync
381 engine) and a suitable ciphersuite has been negotiated. The default value is 1.
382 See L<SSL_CTX_set_max_pipelines(3)> for further information.
383
384 =item B<-read_buf int>
385
386 The default read buffer size to be used for connections. This will only have an
387 effect if the buffer size is larger than the size that would otherwise be used
388 and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
389 further information).
390
391 =item B<-bugs>
392
393 There are several known bug in SSL and TLS implementations. Adding this
394 option enables various workarounds.
395
396 =item B<-comp>
397
398 Enable negotiation of TLS compression.
399 This option was introduced in OpenSSL 1.1.0.
400 TLS compression is not recommended and is off by default as of
401 OpenSSL 1.1.0.
402
403 =item B<-no_comp>
404
405 Disable negotiation of TLS compression.
406 TLS compression is not recommended and is off by default as of
407 OpenSSL 1.1.0.
408
409 =item B<-brief>
410
411 Provide a brief summary of connection parameters instead of the normal verbose
412 output.
413
414 =item B<-cipher cipherlist>
415
416 This allows the cipher list used by the server to be modified.  When
417 the client sends a list of supported ciphers the first client cipher
418 also included in the server list is used. Because the client specifies
419 the preference order, the order of the server cipherlist irrelevant. See
420 the B<ciphers> command for more information.
421
422 =item B<-serverpref>
423
424 Use the server's cipher preferences, rather than the client's preferences.
425
426 =item B<-tlsextdebug>
427
428 Print a hex dump of any TLS extensions received from the server.
429
430 =item B<-no_ticket>
431
432 Disable RFC4507bis session ticket support.
433
434 =item B<-www>
435
436 Sends a status message back to the client when it connects. This includes
437 information about the ciphers used and various session parameters.
438 The output is in HTML format so this option will normally be used with a
439 web browser.
440
441 =item B<-WWW>
442
443 Emulates a simple web server. Pages will be resolved relative to the
444 current directory, for example if the URL https://myhost/page.html is
445 requested the file ./page.html will be loaded.
446
447 =item B<-HTTP>
448
449 Emulates a simple web server. Pages will be resolved relative to the
450 current directory, for example if the URL https://myhost/page.html is
451 requested the file ./page.html will be loaded. The files loaded are
452 assumed to contain a complete and correct HTTP response (lines that
453 are part of the HTTP response line and headers must end with CRLF).
454
455 =item B<-rev>
456
457 Simple test server which just reverses the text received from the client
458 and sends it back to the server. Also sets B<-brief>.
459
460 =item B<-engine id>
461
462 Specifying an engine (by its unique B<id> string) will cause B<s_server>
463 to attempt to obtain a functional reference to the specified engine,
464 thus initialising it if needed. The engine will then be set as the default
465 for all available algorithms.
466
467 =item B<-id_prefix arg>
468
469 Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
470 for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
471 servers, when each of which might be generating a unique range of session
472 IDs (eg. with a certain prefix).
473
474 =item B<-rand file(s)>
475
476 A file or files containing random data used to seed the random number
477 generator, or an EGD socket (see L<RAND_egd(3)>).
478 Multiple files can be specified separated by an OS-dependent character.
479 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
480 all others.
481
482 =item B<-serverinfo file>
483
484 A file containing one or more blocks of PEM data.  Each PEM block
485 must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
486 followed by "length" bytes of extension data).  If the client sends
487 an empty TLS ClientHello extension matching the type, the corresponding
488 ServerHello extension will be returned.
489
490 =item B<-no_resumption_on_reneg>
491
492 Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
493
494 =item B<-status>
495
496 Enables certificate status request support (aka OCSP stapling).
497
498 =item B<-status_verbose>
499
500 Enables certificate status request support (aka OCSP stapling) and gives
501 a verbose printout of the OCSP response.
502
503 =item B<-status_timeout nsec>
504
505 Sets the timeout for OCSP response to B<nsec> seconds.
506
507 =item B<-status_url url>
508
509 Sets a fallback responder URL to use if no responder URL is present in the
510 server certificate. Without this option an error is returned if the server
511 certificate does not contain a responder address.
512
513 =item B<-status_file file>
514
515 Overrides any OCSP responder URLs from the certificate and always provides the
516 OCSP Response stored in the file. The file must be in DER format.
517
518 =item B<-alpn protocols>, B<-nextprotoneg protocols>
519
520 these flags enable the 
521 Enable the Application-Layer Protocol Negotiation or Next Protocol
522 Negotiation extension, respectively. ALPN is the IETF standard and
523 replaces NPN.
524 The B<protocols> list is a
525 comma-separated list of supported protocol names.
526 The list should contain most wanted protocols first.
527 Protocol names are printable ASCII strings, for example "http/1.1" or
528 "spdy/3".
529
530 =back
531
532 =head1 CONNECTED COMMANDS
533
534 If a connection request is established with an SSL client and neither the
535 B<-www> nor the B<-WWW> option has been used then normally any data received
536 from the client is displayed and any key presses will be sent to the client.
537
538 Certain single letter commands are also recognized which perform special
539 operations: these are listed below.
540
541 =over 4
542
543 =item B<q>
544
545 end the current SSL connection but still accept new connections.
546
547 =item B<Q>
548
549 end the current SSL connection and exit.
550
551 =item B<r>
552
553 renegotiate the SSL session.
554
555 =item B<R>
556
557 renegotiate the SSL session and request a client certificate.
558
559 =item B<P>
560
561 send some plain text down the underlying TCP connection: this should
562 cause the client to disconnect due to a protocol violation.
563
564 =item B<S>
565
566 print out some session cache status information.
567
568 =item B<-keylogfile path>
569
570 Appends TLS secrets to the specified keylog file such that external programs
571 (like Wireshark) can decrypt TLS connections.
572
573 =back
574
575 =head1 NOTES
576
577 B<s_server> can be used to debug SSL clients. To accept connections from
578 a web browser the command:
579
580  openssl s_server -accept 443 -www
581
582 can be used for example.
583
584 Most web browsers (in particular Netscape and MSIE) only support RSA cipher
585 suites, so they cannot connect to servers which don't use a certificate
586 carrying an RSA key or a version of OpenSSL with RSA disabled.
587
588 Although specifying an empty list of CAs when requesting a client certificate
589 is strictly speaking a protocol violation, some SSL clients interpret this to
590 mean any CA is acceptable. This is useful for debugging purposes.
591
592 The session parameters can printed out using the B<sess_id> program.
593
594 =head1 BUGS
595
596 Because this program has a lot of options and also because some of the
597 techniques used are rather old, the C source of B<s_server> is rather hard to
598 read and not a model of how things should be done.
599 A typical SSL server program would be much simpler.
600
601 The output of common ciphers is wrong: it just gives the list of ciphers that
602 OpenSSL recognizes and the client supports.
603
604 There should be a way for the B<s_server> program to print out details of any
605 unknown cipher suites a client says it supports.
606
607 =head1 SEE ALSO
608
609 L<SSL_CONF_cmd(3)>,
610 L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
611
612 =head1 HISTORY
613
614 The -no_alt_chains options was first added to OpenSSL 1.1.0.
615
616 =head1 COPYRIGHT
617
618 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
619
620 Licensed under the OpenSSL license (the "License").  You may not use
621 this file except in compliance with the License.  You can obtain a copy
622 in the file LICENSE in the source distribution or at
623 L<https://www.openssl.org/source/license.html>.
624
625 =cut