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