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