diff --git a/doc/man/s_client.pod b/doc/man/s_client.pod index a316eeffe..c7216e659 100644 --- a/doc/man/s_client.pod +++ b/doc/man/s_client.pod @@ -192,7 +192,7 @@ B<-showcerts> option can be used to show the whole chain. =head1 BUGS Because this program has a lot of options and also because some of -the techniques used are rather old the C source of s_client is rather +the techniques used are rather old, the C source of s_client is rather hard to read and not a model of how things should be done. A typical SSL client program would be much simpler. diff --git a/doc/man/s_server.pod b/doc/man/s_server.pod new file mode 100644 index 000000000..277fd2f25 --- /dev/null +++ b/doc/man/s_server.pod @@ -0,0 +1,226 @@ + +=pod + +=head1 NAME + +s_server - SSL/TLS server program + +=head1 SYNOPSIS + +B B +[B<-accept port>] +[B<-context id>] +[B<-verify depth>] +[B<-Verify depth>] +[B<-cert filename>] +[B<-key keyfile>] +[B<-dcert filename>] +[B<-dkey keyfile>] +[B<-dhparam filename>] +[B<-nbio>] +[B<-nbio_test>] +[B<-crlf>] +[B<-debug>] +[B<-state>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-nocert>] +[B<-cipher cipherlist>] +[B<-quiet>] +[B<-no_tmp_rsa>] +[B<-ssl2>] +[B<-ssl3>] +[B<-tls1>] +[B<-no_ssl2>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_dhe>] +[B<-bugs>] +[B<-www>] +[B<-WWW>] + +=head1 DESCRIPTION + +The B command implements a generic SSL/TLS server which listens +for connections on a given port using SSL/TLS. + +=head1 OPTIONS + +=over 4 + +=item B<-accept port> + +the TCP port to listen on for connections. If not specified 4433 is used. + +=item B<-context id> + +sets the SSL context id. If a client certificate is being requested then +this option must be set. It can be given any string value. + +=item B<-cert certname> + +The certificate to use, most servers cipher suites require the use of a +certificate and some require a certificate with a certain public key type: +for example the DSS cipher suites require a certificate containing a DSS +(DSA) key. If not specified then the filename "server.pem" will be used. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-dcert filename>, B<-dkey keyname> + +specify an additional certificate and private key, these behave in the +same manner as the B<-cert> and B<-key> options except there is no default +if they are not specified (no additional certificate and key is used). As +noted above some cipher suites require a certificate containing a key of +a certain type. Some cipher suites need a certificate carrying an RSA key +and some a DSS (DSA) key. By using RSA and DSS certificates and keys +a server can support clients which only support RSA or DSS cipher suites +by using an appropriate certificate. + +=item B<-nocert> + +if this option is set then no certificate is used. This restricts the +cipher suites available to the anonymous ones (currently just anonymous +DH). + +=item B<-dhparam filename> + +the DH parameter file to use. The ephemeral DH cipher suites generate keys +using a set of DH parameters. If not specified then an attempt is made to +load the parameters from the server certificate file. If this fails then +a static set of parameters hard coded into the s_server program will be used. + +=item B<-nodhe> + +if this option is set then no DH parameters will be loaded effectively +disabling the ephemeral DH cipher suites. + +=item B<-no_tmp_rsa> + +certain export cipher suites sometimes use a temporary RSA key, this option +disables temporary RSA key generation. + +=item B<-verify depth>, B<-Verify depth> + +The verify depth to use. This specifies the maximum length of the +client certificate chain and makes the server request a certificate from +the client. With the B<-verify> option a certificate is requested but the +client does not have to send one, with the B<-Verify> option the client +must supply a certificate or an error occurs. + +=item B<-CApath directory> + +The directory to use for client certificate verification. This directory +must be in "hash format", see B for more information. These are +also used when building the server certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during client authentication +and to use when attempting to build the server certificate chain. The list +is also used in the list of acceptable client CAs passed to the client when +a certificate is requested. + +=item B<-state> + +prints out the SSL session states. + +=item B<-debug> + +print extensive debugging information including a hex dump of all traffic. + +=item B<-nbio_test> + +tests non blocking I/O + +=item B<-nbio> + +turns on non blocking I/O + +=item B<-crlf> + +this option translated a line feed from the terminal into CR+LF. + +=item B<-quiet> + +inhibit printing of session and certificate information. + +=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> + +these options disable the use of certain SSL or TLS protocols. By default +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. See the +B command for more information. + +=item B<-www> + +sends a status message back to the client when it connects. This includes +lots of information about the ciphers used and various session parameters. +The output is in HTML format so this option will normally be used with a +web browser. + +=item B<-WWW> + +emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. + +=back + +=head1 CONNECTED COMMANDS + +If a connection request is established with an SSL client and neither the +B<-www> nor the B<-WWW> option has been used then any data received from +the server is displayed and any key presses will be sent to the server. If +the line begins with an B then the session will be renegotiated. If the +line begins with a B the connection will be closed down. + +=head1 NOTES + +B can be used to debug SSL clients. To accept connections from +a web browser the command: + + openssl s_server -accept 443 -www + +can be used for example. + +Most web browsers (in particular Netscape and MSIE) only support RSA cipher +suites, so they cannot connect to servers which don't use a certificate +carrying an RSA key or a version of OpenSSL with RSA disabled. + +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL clients assume any CA is +acceptable. This is useful for debugging purposes. + +The session parameters can printed out using the B program. + +=head1 BUGS + +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of s_server is rather +hard to read and not a model of how things should be done. A typical +SSL server program would be much simpler. + +The output of common ciphers is wrong: it just gives the list of ciphers that +OpenSSL recognises and the client supports. + +There should be a way for the B program to print out details of any +unknown cipher suites a client says it supports. + +=head1 SEE ALSO + +sess_id(1), s_client(1), ciphers(1) + +=cut