doc/apps/s_server.pod

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