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