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