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