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