doc/man/s_server.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 s_server - SSL/TLS server program
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<s_client>
  11 [B<-accept port>]
  12 [B<-context id>]
  13 [B<-verify depth>]
  14 [B<-Verify depth>]
  15 [B<-cert filename>]
  16 [B<-key keyfile>]
  17 [B<-dcert filename>]
  18 [B<-dkey keyfile>]
  19 [B<-dhparam filename>]
  20 [B<-nbio>]
  21 [B<-nbio_test>]
  22 [B<-crlf>]
  23 [B<-debug>]
  24 [B<-state>]
  25 [B<-CApath directory>]
  26 [B<-CAfile filename>]
  27 [B<-nocert>]
  28 [B<-cipher cipherlist>]
  29 [B<-quiet>]
  30 [B<-no_tmp_rsa>]
  31 [B<-ssl2>]
  32 [B<-ssl3>]
  33 [B<-tls1>]
  34 [B<-no_ssl2>]
  35 [B<-no_ssl3>]
  36 [B<-no_tls1>]
  37 [B<-no_dhe>]
  38 [B<-bugs>]
  39 [B<-www>]
  40 [B<-WWW>]
  41
  42 =head1 DESCRIPTION
  43
  44 The B<s_server> command implements a generic SSL/TLS server which listens
  45 for connections on a given port using SSL/TLS.
  46
  47 =head1 OPTIONS
  48
  49 =over 4
  50
  51 =item B<-accept port>
  52
  53 the TCP port to listen on for connections. If not specified 4433 is used.
  54
  55 =item B<-context id>
  56
  57 sets the SSL context id. If a client certificate is being requested then
  58 this option must be set. It can be given any string value.
  59
  60 =item B<-cert certname>
  61
  62 The certificate to use, most servers cipher suites require the use of a
  63 certificate and some require a certificate with a certain public key type:
  64 for example the DSS cipher suites require a certificate containing a DSS
  65 (DSA) key. If not specified then the filename "server.pem" will be used.
  66
  67 =item B<-key keyfile>
  68
  69 The private key to use. If not specified then the certificate file will
  70 be used.
  71
  72 =item B<-dcert filename>, B<-dkey keyname>
  73
  74 specify an additional certificate and private key, these behave in the
  75 same manner as the B<-cert> and B<-key> options except there is no default
  76 if they are not specified (no additional certificate and key is used). As
  77 noted above some cipher suites require a certificate containing a key of
  78 a certain type. Some cipher suites need a certificate carrying an RSA key
  79 and some a DSS (DSA) key. By using RSA and DSS certificates and keys
  80 a server can support clients which only support RSA or DSS cipher suites
  81 by using an appropriate certificate.
  82
  83 =item B<-nocert>
  84
  85 if this option is set then no certificate is used. This restricts the
  86 cipher suites available to the anonymous ones (currently just anonymous
  87 DH).
  88
  89 =item B<-dhparam filename>
  90
  91 the DH parameter file to use. The ephemeral DH cipher suites generate keys
  92 using a set of DH parameters. If not specified then an attempt is made to
  93 load the parameters from the server certificate file. If this fails then
  94 a static set of parameters hard coded into the s_server program will be used.
  95
  96 =item B<-nodhe>
  97
  98 if this option is set then no DH parameters will be loaded effectively
  99 disabling the ephemeral DH cipher suites.
 100
 101 =item B<-no_tmp_rsa>
 102
 103 certain export cipher suites sometimes use a temporary RSA key, this option
 104 disables temporary RSA key generation.
 105
 106 =item B<-verify depth>, B<-Verify depth>
 107
 108 The verify depth to use. This specifies the maximum length of the
 109 client certificate chain and makes the server request a certificate from
 110 the client. With the B<-verify> option a certificate is requested but the
 111 client does not have to send one, with the B<-Verify> option the client
 112 must supply a certificate or an error occurs.
 113
 114 =item B<-CApath directory>
 115
 116 The directory to use for client certificate verification. This directory
 117 must be in "hash format", see B<verify> for more information. These are
 118 also used when building the server certificate chain.
 119
 120 =item B<-CAfile file>
 121
 122 A file containing trusted certificates to use during client authentication
 123 and to use when attempting to build the server certificate chain. The list
 124 is also used in the list of acceptable client CAs passed to the client when
 125 a certificate is requested.
 126
 127 =item B<-state>
 128
 129 prints out the SSL session states.
 130
 131 =item B<-debug>
 132
 133 print extensive debugging information including a hex dump of all traffic.
 134
 135 =item B<-nbio_test>
 136
 137 tests non blocking I/O
 138
 139 =item B<-nbio>
 140
 141 turns on non blocking I/O
 142
 143 =item B<-crlf>
 144
 145 this option translated a line feed from the terminal into CR+LF.
 146
 147 =item B<-quiet>
 148
 149 inhibit printing of session and certificate information.
 150
 151 =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
 152
 153 these options disable the use of certain SSL or TLS protocols. By default
 154 the initial handshake uses a method which should be compatible with all
 155 servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
 156
 157 =item B<-bugs>
 158
 159 there are several known bug in SSL and TLS implementations. Adding this
 160 option enables various workarounds.
 161
 162 =item B<-cipher cipherlist>
 163
 164 this allows the cipher list sent by the client to be modified. See the
 165 B<ciphers> command for more information.
 166
 167 =item B<-www>
 168
 169 sends a status message back to the client when it connects. This includes
 170 lots of information about the ciphers used and various session parameters.
 171 The output is in HTML format so this option will normally be used with a
 172 web browser.
 173
 174 =item B<-WWW>
 175
 176 emulates a simple web server. Pages will be resolved relative to the
 177 current directory, for example if the URL https://myhost/page.html is
 178 requested the file ./page.html will be loaded.
 179
 180 =back
 181
 182 =head1 CONNECTED COMMANDS
 183
 184 If a connection request is established with an SSL client and neither the
 185 B<-www> nor the B<-WWW> option has been used then any data received from
 186 the server is displayed and any key presses will be sent to the server. If
 187 the line begins with an B<R> then the session will be renegotiated. If the
 188 line begins with a B<Q> the connection will be closed down.
 189
 190 =head1 NOTES
 191
 192 B<s_server> can be used to debug SSL clients. To accept connections from
 193 a web browser the command:
 194
 195  openssl s_server -accept 443 -www
 196
 197 can be used for example.
 198
 199 Most web browsers (in particular Netscape and MSIE) only support RSA cipher
 200 suites, so they cannot connect to servers which don't use a certificate
 201 carrying an RSA key or a version of OpenSSL with RSA disabled.
 202
 203 Although specifying an empty list of CAs when requesting a client certificate
 204 is strictly speaking a protocol violation, some SSL clients assume any CA is
 205 acceptable. This is useful for debugging purposes.
 206
 207 The session parameters can printed out using the B<sess_id> program.
 208
 209 =head1 BUGS
 210
 211 Because this program has a lot of options and also because some of
 212 the techniques used are rather old, the C source of s_server is rather
 213 hard to read and not a model of how things should be done. A typical
 214 SSL server program would be much simpler.
 215
 216 The output of common ciphers is wrong: it just gives the list of ciphers that
 217 OpenSSL recognises and the client supports.
 218
 219 There should be a way for the B<s_server> program to print out details of any
 220 unknown cipher suites a client says it supports.
 221
 222 =head1 SEE ALSO
 223
 224 sess_id(1), s_client(1), ciphers(1)
 225
 226 =cut