crypto/openssl/doc/apps/s_server.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 openssl-s_server,
   7 s_server - SSL/TLS server program
   8
   9 =head1 SYNOPSIS
  10
  11 B<openssl> B<s_server>
  12 [B<-accept port>]
  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_alt_chains>]
  38 [B<-nocert>]
  39 [B<-client_sigalgs sigalglist>]
  40 [B<-named_curve curve>]
  41 [B<-cipher cipherlist>]
  42 [B<-serverpref>]
  43 [B<-quiet>]
  44 [B<-no_tmp_rsa>]
  45 [B<-ssl2>]
  46 [B<-ssl3>]
  47 [B<-tls1>]
  48 [B<-no_ssl2>]
  49 [B<-no_ssl3>]
  50 [B<-no_tls1>]
  51 [B<-no_dhe>]
  52 [B<-no_ecdhe>]
  53 [B<-bugs>]
  54 [B<-hack>]
  55 [B<-www>]
  56 [B<-WWW>]
  57 [B<-HTTP>]
  58 [B<-engine id>]
  59 [B<-tlsextdebug>]
  60 [B<-no_ticket>]
  61 [B<-id_prefix arg>]
  62 [B<-rand file(s)>]
  63 [B<-serverinfo file>]
  64 [B<-no_resumption_on_reneg>]
  65 [B<-status>]
  66 [B<-status_verbose>]
  67 [B<-status_timeout nsec>]
  68 [B<-status_url url>]
  69 [B<-alpn protocols>]
  70 [B<-nextprotoneg protocols>]
  71
  72 =head1 DESCRIPTION
  73
  74 The B<s_server> command implements a generic SSL/TLS server which listens
  75 for connections on a given port using SSL/TLS.
  76
  77 =head1 OPTIONS
  78
  79 =over 4
  80
  81 =item B<-accept port>
  82
  83 the TCP port to listen on for connections. If not specified 4433 is used.
  84
  85 =item B<-context id>
  86
  87 sets the SSL context id. It can be given any string value. If this option
  88 is not present a default value will be used.
  89
  90 =item B<-cert certname>
  91
  92 The certificate to use, most servers cipher suites require the use of a
  93 certificate and some require a certificate with a certain public key type:
  94 for example the DSS cipher suites require a certificate containing a DSS
  95 (DSA) key. If not specified then the filename "server.pem" will be used.
  96
  97 =item B<-certform format>
  98
  99 The certificate format to use: DER or PEM. PEM is the default.
 100
 101 =item B<-key keyfile>
 102
 103 The private key to use. If not specified then the certificate file will
 104 be used.
 105
 106 =item B<-keyform format>
 107
 108 The private format to use: DER or PEM. PEM is the default.
 109
 110 =item B<-pass arg>
 111
 112 the private key password source. For more information about the format of B<arg>
 113 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
 114
 115 =item B<-dcert filename>, B<-dkey keyname>
 116
 117 specify an additional certificate and private key, these behave in the
 118 same manner as the B<-cert> and B<-key> options except there is no default
 119 if they are not specified (no additional certificate and key is used). As
 120 noted above some cipher suites require a certificate containing a key of
 121 a certain type. Some cipher suites need a certificate carrying an RSA key
 122 and some a DSS (DSA) key. By using RSA and DSS certificates and keys
 123 a server can support clients which only support RSA or DSS cipher suites
 124 by using an appropriate certificate.
 125
 126 =item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
 127
 128 additional certificate and private key format and passphrase respectively.
 129
 130 =item B<-nocert>
 131
 132 if this option is set then no certificate is used. This restricts the
 133 cipher suites available to the anonymous ones (currently just anonymous
 134 DH).
 135
 136 =item B<-dhparam filename>
 137
 138 the DH parameter file to use. The ephemeral DH cipher suites generate keys
 139 using a set of DH parameters. If not specified then an attempt is made to
 140 load the parameters from the server certificate file. If this fails then
 141 a static set of parameters hard coded into the s_server program will be used.
 142
 143 =item B<-no_dhe>
 144
 145 if this option is set then no DH parameters will be loaded effectively
 146 disabling the ephemeral DH cipher suites.
 147
 148 =item B<-no_ecdhe>
 149
 150 if this option is set then no ECDH parameters will be selected, effectively
 151 disabling the ephemeral ECDH cipher suites.
 152
 153 =item B<-no_tmp_rsa>
 154
 155 certain export cipher suites sometimes use a temporary RSA key, this option
 156 disables temporary RSA key generation.
 157
 158 =item B<-verify depth>, B<-Verify depth>
 159
 160 The verify depth to use. This specifies the maximum length of the
 161 client certificate chain and makes the server request a certificate from
 162 the client. With the B<-verify> option a certificate is requested but the
 163 client does not have to send one, with the B<-Verify> option the client
 164 must supply a certificate or an error occurs.
 165
 166 If the ciphersuite cannot request a client certificate (for example an
 167 anonymous ciphersuite or PSK) this option has no effect.
 168
 169 =item B<-crl_check>, B<-crl_check_all>
 170
 171 Check the peer certificate has not been revoked by its CA.
 172 The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
 173 option all CRLs of all CAs in the chain are checked.
 174
 175 =item B<-CApath directory>
 176
 177 The directory to use for client certificate verification. This directory
 178 must be in "hash format", see B<verify> for more information. These are
 179 also used when building the server certificate chain.
 180
 181 =item B<-CAfile file>
 182
 183 A file containing trusted certificates to use during client authentication
 184 and to use when attempting to build the server certificate chain. The list
 185 is also used in the list of acceptable client CAs passed to the client when
 186 a certificate is requested.
 187
 188 =item B<-no_alt_chains>
 189
 190 See the L<B<verify>|verify(1)> manual page for details.
 191
 192 =item B<-state>
 193
 194 prints out the SSL session states.
 195
 196 =item B<-debug>
 197
 198 print extensive debugging information including a hex dump of all traffic.
 199
 200 =item B<-msg>
 201
 202 show all protocol messages with hex dump.
 203
 204 =item B<-nbio_test>
 205
 206 tests non blocking I/O
 207
 208 =item B<-nbio>
 209
 210 turns on non blocking I/O
 211
 212 =item B<-crlf>
 213
 214 this option translated a line feed from the terminal into CR+LF.
 215
 216 =item B<-quiet>
 217
 218 inhibit printing of session and certificate information.
 219
 220 =item B<-psk_hint hint>
 221
 222 Use the PSK identity hint B<hint> when using a PSK cipher suite.
 223
 224 =item B<-psk key>
 225
 226 Use the PSK key B<key> when using a PSK cipher suite. The key is
 227 given as a hexadecimal number without leading 0x, for example -psk
 228 1a2b3c4d.
 229 This option must be provided in order to use a PSK cipher.
 230
 231 =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
 232
 233 These options require or disable the use of the specified SSL or TLS protocols.
 234 By default the initial handshake uses a I<version-flexible> method which will
 235 negotiate the highest mutually supported protocol version.
 236
 237 =item B<-bugs>
 238
 239 there are several known bug in SSL and TLS implementations. Adding this
 240 option enables various workarounds.
 241
 242 =item B<-hack>
 243
 244 this option enables a further workaround for some some early Netscape
 245 SSL code (?).
 246
 247 =item B<-client_sigalgs sigalglist>
 248
 249 Signature algorithms to support for client certificate authentication
 250 (colon-separated list)
 251
 252 =item B<-named_curve curve>
 253
 254 Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
 255 For a list of all possible curves, use:
 256
 257     $ openssl ecparam -list_curves
 258
 259 =item B<-cipher cipherlist>
 260
 261 this allows the cipher list used by the server to be modified.  When
 262 the client sends a list of supported ciphers the first client cipher
 263 also included in the server list is used. Because the client specifies
 264 the preference order, the order of the server cipherlist irrelevant. See
 265 the B<ciphers> command for more information.
 266
 267 =item B<-serverpref>
 268
 269 use the server's cipher preferences, rather than the client's preferences.
 270
 271 =item B<-tlsextdebug>
 272
 273 print out a hex dump of any TLS extensions received from the server.
 274
 275 =item B<-no_ticket>
 276
 277 disable RFC4507bis session ticket support.
 278
 279 =item B<-www>
 280
 281 sends a status message back to the client when it connects. This includes
 282 lots of information about the ciphers used and various session parameters.
 283 The output is in HTML format so this option will normally be used with a
 284 web browser.
 285
 286 =item B<-WWW>
 287
 288 emulates a simple web server. Pages will be resolved relative to the
 289 current directory, for example if the URL https://myhost/page.html is
 290 requested the file ./page.html will be loaded.
 291
 292 =item B<-HTTP>
 293
 294 emulates a simple web server. Pages will be resolved relative to the
 295 current directory, for example if the URL https://myhost/page.html is
 296 requested the file ./page.html will be loaded. The files loaded are
 297 assumed to contain a complete and correct HTTP response (lines that
 298 are part of the HTTP response line and headers must end with CRLF).
 299
 300 =item B<-engine id>
 301
 302 specifying an engine (by its unique B<id> string) will cause B<s_server>
 303 to attempt to obtain a functional reference to the specified engine,
 304 thus initialising it if needed. The engine will then be set as the default
 305 for all available algorithms.
 306
 307 =item B<-id_prefix arg>
 308
 309 generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
 310 for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
 311 servers, when each of which might be generating a unique range of session
 312 IDs (eg. with a certain prefix).
 313
 314 =item B<-rand file(s)>
 315
 316 a file or files containing random data used to seed the random number
 317 generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
 318 Multiple files can be specified separated by a OS-dependent character.
 319 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 320 all others.
 321
 322 =item B<-serverinfo file>
 323
 324 a file containing one or more blocks of PEM data.  Each PEM block
 325 must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
 326 followed by "length" bytes of extension data).  If the client sends
 327 an empty TLS ClientHello extension matching the type, the corresponding
 328 ServerHello extension will be returned.
 329
 330 =item B<-no_resumption_on_reneg>
 331
 332 set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
 333
 334 =item B<-status>
 335
 336 enables certificate status request support (aka OCSP stapling).
 337
 338 =item B<-status_verbose>
 339
 340 enables certificate status request support (aka OCSP stapling) and gives
 341 a verbose printout of the OCSP response.
 342
 343 =item B<-status_timeout nsec>
 344
 345 sets the timeout for OCSP response to B<nsec> seconds.
 346
 347 =item B<-status_url url>
 348
 349 sets a fallback responder URL to use if no responder URL is present in the
 350 server certificate. Without this option an error is returned if the server
 351 certificate does not contain a responder address.
 352
 353 =item B<-alpn protocols>, B<-nextprotoneg protocols>
 354
 355 these flags enable the
 356 Enable the Application-Layer Protocol Negotiation or Next Protocol
 357 Negotiation extension, respectively. ALPN is the IETF standard and
 358 replaces NPN.
 359 The B<protocols> list is a
 360 comma-separated list of supported protocol names.
 361 The list should contain most wanted protocols first.
 362 Protocol names are printable ASCII strings, for example "http/1.1" or
 363 "spdy/3".
 364
 365 =back
 366
 367 =head1 CONNECTED COMMANDS
 368
 369 If a connection request is established with an SSL client and neither the
 370 B<-www> nor the B<-WWW> option has been used then normally any data received
 371 from the client is displayed and any key presses will be sent to the client.
 372
 373 Certain single letter commands are also recognized which perform special
 374 operations: these are listed below.
 375
 376 =over 4
 377
 378 =item B<q>
 379
 380 end the current SSL connection but still accept new connections.
 381
 382 =item B<Q>
 383
 384 end the current SSL connection and exit.
 385
 386 =item B<r>
 387
 388 renegotiate the SSL session.
 389
 390 =item B<R>
 391
 392 renegotiate the SSL session and request a client certificate.
 393
 394 =item B<P>
 395
 396 send some plain text down the underlying TCP connection: this should
 397 cause the client to disconnect due to a protocol violation.
 398
 399 =item B<S>
 400
 401 print out some session cache status information.
 402
 403 =back
 404
 405 =head1 NOTES
 406
 407 B<s_server> can be used to debug SSL clients. To accept connections from
 408 a web browser the command:
 409
 410  openssl s_server -accept 443 -www
 411
 412 can be used for example.
 413
 414 Although specifying an empty list of CAs when requesting a client certificate
 415 is strictly speaking a protocol violation, some SSL clients interpret this to
 416 mean any CA is acceptable. This is useful for debugging purposes.
 417
 418 The session parameters can printed out using the B<sess_id> program.
 419
 420 =head1 BUGS
 421
 422 Because this program has a lot of options and also because some of
 423 the techniques used are rather old, the C source of s_server is rather
 424 hard to read and not a model of how things should be done. A typical
 425 SSL server program would be much simpler.
 426
 427 The output of common ciphers is wrong: it just gives the list of ciphers that
 428 OpenSSL recognizes and the client supports.
 429
 430 There should be a way for the B<s_server> program to print out details of any
 431 unknown cipher suites a client says it supports.
 432
 433 =head1 SEE ALSO
 434
 435 L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
 436
 437 =head1 HISTORY
 438
 439 The -no_alt_chains options was first added to OpenSSL 1.0.2b.
 440
 441 =cut