Import of old SSLeay release: SSLeay 0.8.1b
[openssl.git] / ssl / readme
1 22 Jun 1996
2 This file belongs in ../apps, but I'll leave it here because it deals
3 with SSL :-)  It is rather dated but it gives you an idea of how
4 things work.
5 ===
6
7 17 Jul 1995
8 I have been changing things quite a bit and have not fully updated
9 this file, so take what you read with a grain of salt
10 eric
11 ===
12 The s_client and s_server programs can be used to test SSL capable
13 IP/port addresses and the verification of the X509 certificates in use
14 by these services.  I strongly advise having a look at the code to get
15 an idea of how to use the authentication under SSLeay.  Any feedback
16 on changes and improvements would be greatly accepted.
17
18 This file will probably be gibberish unless you have read
19 rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM
20 authentication.
21
22 A Brief outline (and examples) how to use them to do so.
23
24 NOTE:
25 The environment variable SSL_CIPER is used to specify the prefered
26 cipher to use, play around with setting it's value to combinations of
27 RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL
28 in a : separated list.
29
30 This directory contains 3 X509 certificates which can be used by these programs.
31 client.pem: a file containing a certificate and private key to be used
32         by s_client.
33 server.pem :a file containing a certificate and private key to be used
34         by s_server.
35 eay1024.pem:the certificate used to sign client.pem and server.pem.
36         This would be your CA's certificate.  There is also a link
37         from the file a8556381.0 to eay1024.PEM.  The value a8556381
38         is returned by 'x509 -hash -noout <eay1024.pem' and is the
39         value used by X509 verification routines to 'find' this
40         certificte when search a directory for it.
41         [the above is not true any more, the CA cert is 
42          ../certs/testca.pem which is signed by ../certs/mincomca.pem]
43
44 When testing the s_server, you may get
45 bind: Address already in use
46 errors.  These indicate the port is still being held by the unix
47 kernel and you are going to have to wait for it to let go of it.  If
48 this is the case, remember to use the port commands on the s_server and
49 s_client to talk on an alternative port.
50
51 =====
52 s_client.
53 This program can be used to connect to any IP/hostname:port that is
54 talking SSL.  Once connected, it will attempt to authenticate the
55 certificate it was passed and if everything works as expected, a 2
56 directional channel will be open.  Any text typed will be sent to the
57 other end.  type Q<cr> to exit.  Flags are as follows.
58 -host arg       : Arg is the host or IP address to connect to.
59 -port arg       : Arg is the port to connect to (https is 443).
60 -verify arg     : Turn on authentication of the server certificate.
61                 : Arg specifies the 'depth', this will covered below.
62 -cert arg       : The optional certificate to use.  This certificate
63                 : will be returned to the server if the server
64                 : requests it for client authentication.
65 -key arg        : The private key that matches the certificate
66                 : specified by the -cert option.  If this is not
67                 : specified (but -cert is), the -cert file will be
68                 : searched for the Private key.  Both files are
69                 : assumed to be in PEM format.
70 -CApath arg     : When to look for certificates when 'verifying' the
71                 : certificate from the server.
72 -CAfile arg     : A file containing certificates to be used for
73                 : 'verifying' the server certificate.
74 -reconnect      : Once a connection has been made, drop it and
75                 : reconnect with same session-id.  This is for testing :-).
76
77 The '-verify n' parameter specifies not only to verify the servers
78 certificate but to also only take notice of 'n' levels.  The best way
79 to explain is to show via examples.
80 Given
81 s_server -cert server.PEM is running.
82
83 s_client
84         CONNECTED
85         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
86         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
87         verify error:num=1:unable to get issuer certificate
88         verify return:1
89         CIPHER is CBC-DES-MD5
90 What has happened is that the 'SSLeay demo server' certificate's
91 issuer ('CA') could not be found but because verify is not on, we
92 don't care and the connection has been made anyway.  It is now 'up'
93 using CBC-DES-MD5 mode.  This is an unauthenticate secure channel.
94 You may not be talking to the right person but the data going to them
95 is encrypted.
96
97 s_client -verify 0
98         CONNECTED
99         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
100         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
101         verify error:num=1:unable to get issuer certificate
102         verify return:1
103         CIPHER is CBC-DES-MD5
104 We are 'verifying' but only to depth 0, so since the 'SSLeay demo server'
105 certificate passed the date and checksum, we are happy to proceed.
106
107 s_client -verify 1
108         CONNECTED
109         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
110         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
111         verify error:num=1:unable to get issuer certificate
112         verify return:0
113         ERROR
114         verify error:unable to get issuer certificate
115 In this case we failed to make the connection because we could not
116 authenticate the certificate because we could not find the
117 'CA' certificate.
118
119 s_client -verify 1 -CAfile eay1024.PEM
120         CONNECTED
121         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
122         verify return:1
123         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
124         verify return:1
125         CIPHER is CBC-DES-MD5
126 We loaded the certificates from the file eay1024.PEM.  Everything
127 checked out and so we made the connection.
128
129 s_client -verify 1 -CApath .
130         CONNECTED
131         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
132         verify return:1
133         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
134         verify return:1
135         CIPHER is CBC-DES-MD5
136 We looked in out local directory for issuer certificates and 'found'
137 a8556381.0 and so everything is ok.
138
139 It is worth noting that 'CA' is a self certified certificate.  If you
140 are passed one of these, it will fail to 'verify' at depth 0 because
141 we need to lookup the certifier of a certificate from some information
142 that we trust and keep locally.
143
144 SSL_CIPHER=CBC3-DES-MD5:RC4-MD5
145 export SSL_CIPHER
146 s_client -verify 10 -CApath . -reconnect
147         CONNECTED
148         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
149         verify return:1
150         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
151         verify return:1
152         drop the connection and reconnect with the same session id
153         CIPHER is CBC3-DES-MD5
154 This has done a full connection and then re-estabished it with the
155 same session id but a new socket.  No RSA stuff occures on the second
156 connection.  Note that we said we would prefer to use CBC3-DES-MD5
157 encryption and so, since the server supports it, we are.
158
159 =====
160 s_server
161 This program accepts SSL connections on a specified port
162 Once connected, it will estabish an SSL connection and optionaly
163 attempt to authenticate the client.  A 2 directional channel will be
164 open.  Any text typed will be sent to the other end.  Type Q<cr> to exit.
165 Flags are as follows.
166 -port arg       : Arg is the port to listen on.
167 -verify arg     : Turn on authentication of the client if they have a
168                 : certificate.  Arg specifies the 'depth'.
169 -Verify arg     : Turn on authentication of the client. If they don't
170                 : have a valid certificate, drop the connection.
171 -cert arg       : The certificate to use.  This certificate
172                 : will be passed to the client.  If it is not
173                 : specified, it will default to server.PEM
174 -key arg        : The private key that matches the certificate
175                 : specified by the -cert option.  If this is not
176                 : specified (but -cert is), the -cert file will be
177                 : searched for the Private key.  Both files are
178                 : assumed to be in PEM format.  Default is server.PEM
179 -CApath arg     : When to look for certificates when 'verifying' the
180                 : certificate from the client.
181 -CAfile arg     : A file containing certificates to be used for
182                 : 'verifying' the client certificate.
183
184 For the following 'demo'  I will specify the s_server command and
185 the s_client command and then list the output from the s_server.
186 s_server
187 s_client
188         CONNECTED
189         CIPHER is CBC-DES-MD5
190 Everything up and running
191
192 s_server -verify 0
193 s_client  
194         CONNECTED
195         CIPHER is CBC-DES-MD5
196 Ok since no certificate was returned and we don't care.
197
198 s_server -verify 0
199 ./s_client -cert client.PEM
200         CONNECTED
201         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
202         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
203         verify error:num=1:unable to get issuer certificate
204         verify return:1
205         CIPHER is CBC-DES-MD5
206 Ok since we were only verifying to level 0
207
208 s_server -verify 4
209 s_client -cert client.PEM
210         CONNECTED
211         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
212         issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
213         verify error:num=1:unable to get issuer certificate
214         verify return:0
215         ERROR
216         verify error:unable to get issuer certificate
217 Bad because we could not authenticate the returned certificate.
218
219 s_server -verify 4 -CApath .
220 s_client -cert client.PEM
221         CONNECTED
222         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
223         verify return:1
224         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
225         verify return:1
226         CIPHER is CBC-DES-MD5
227 Ok because we could authenticate the returned certificate :-).
228
229 s_server -Verify 0 -CApath .
230 s_client
231         CONNECTED
232         ERROR
233         SSL error:function is:REQUEST_CERTIFICATE
234                  :error is   :client end did not return a certificate
235 Error because no certificate returned.
236
237 s_server -Verify 4 -CApath .
238 s_client -cert client.PEM
239         CONNECTED
240         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
241         verify return:1
242         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
243         verify return:1
244         CIPHER is CBC-DES-MD5
245 Full authentication of the client.
246
247 So in summary to do full authentication of both ends
248 s_server -Verify 9 -CApath .
249 s_client -cert client.PEM -CApath . -verify 9
250 From the server side
251         CONNECTED
252         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client
253         verify return:1
254         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
255         verify return:1
256         CIPHER is CBC-DES-MD5
257 From the client side
258         CONNECTED
259         depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server
260         verify return:1
261         depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA
262         verify return:1
263         CIPHER is CBC-DES-MD5
264
265 For general probing of the 'internet https' servers for the
266 distribution area, run
267 s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash
268 Then enter
269 GET /
270 and you should be talking to the https server on that host.
271
272 www.rsa.com was refusing to respond to connections on 443 when I was
273 testing.
274
275 have fun :-).
276
277 eric