openssl-0.9.8

Bundle of old SSLeay documentation files [OBSOLETE!] *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** OBSOLETE means that nothing in this document should be trusted. This document is provided mostly for historical purposes (it wasn't even up to date at the time SSLeay 0.8.1 was released) and as inspiration. If you copy some snippet of code from this document, please _check_ that it really is correct from all points of view. For example, you can check with the other documents in this directory tree, or by comparing with relevant parts of the include files. People have done the mistake of trusting what's written here. Please don't do that. *** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** ==== readme ======================================================== This is the old 0.6.6 docuementation. Most of the cipher stuff is still relevent but I'm working (very slowly) on new docuemtation. The current version can be found online at http://www.cryptsoft.com/ssleay/doc ==== API.doc ======================================================== SSL - SSLv2/v3/v23 etc. BIO - methods and how they plug together MEM - memory allocation callback CRYPTO - locking for threads EVP - Ciphers/Digests/signatures RSA - methods X509 - certificate retrieval X509 - validation X509 - X509v3 extensions Objects - adding object identifiers ASN.1 - parsing PEM - parsing ==== ssl/readme ===================================================== 22 Jun 1996 This file belongs in ../apps, but I'll leave it here because it deals with SSL :-) It is rather dated but it gives you an idea of how things work. === 17 Jul 1995 I have been changing things quite a bit and have not fully updated this file, so take what you read with a grain of salt eric === The s_client and s_server programs can be used to test SSL capable IP/port addresses and the verification of the X509 certificates in use by these services. I strongly advise having a look at the code to get an idea of how to use the authentication under SSLeay. Any feedback on changes and improvements would be greatly accepted. This file will probably be gibberish unless you have read rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM authentication. A Brief outline (and examples) how to use them to do so. NOTE: The environment variable SSL_CIPER is used to specify the prefered cipher to use, play around with setting it's value to combinations of RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL in a : separated list. This directory contains 3 X509 certificates which can be used by these programs. client.pem: a file containing a certificate and private key to be used by s_client. server.pem :a file containing a certificate and private key to be used by s_server. eay1024.pem:the certificate used to sign client.pem and server.pem. This would be your CA's certificate. There is also a link from the file a8556381.0 to eay1024.PEM. The value a8556381 is returned by 'x509 -hash -noout <eay1024.pem' and is the value used by X509 verification routines to 'find' this certificte when search a directory for it. [the above is not true any more, the CA cert is ../certs/testca.pem which is signed by ../certs/mincomca.pem] When testing the s_server, you may get bind: Address already in use errors. These indicate the port is still being held by the unix kernel and you are going to have to wait for it to let go of it. If this is the case, remember to use the port commands on the s_server and s_client to talk on an alternative port. ===== s_client. This program can be used to connect to any IP/hostname:port that is talking SSL. Once connected, it will attempt to authenticate the certificate it was passed and if everything works as expected, a 2 directional channel will be open. Any text typed will be sent to the other end. type Q<cr> to exit. Flags are as follows. -host arg : Arg is the host or IP address to connect to. -port arg : Arg is the port to connect to (https is 443). -verify arg : Turn on authentication of the server certificate. : Arg specifies the 'depth', this will covered below. -cert arg : The optional certificate to use. This certificate : will be returned to the server if the server : requests it for client authentication. -key arg : The private key that matches the certificate : specified by the -cert option. If this is not : specified (but -cert is), the -cert file will be : searched for the Private key. Both files are : assumed to be in PEM format. -CApath arg : When to look for certificates when 'verifying' the : certificate from the server. -CAfile arg : A file containing certificates to be used for : 'verifying' the server certificate. -reconnect : Once a connection has been made, drop it and : reconnect with same session-id. This is for testing :-). The '-verify n' parameter specifies not only to verify the servers certificate but to also only take notice of 'n' levels. The best way to explain is to show via examples. Given s_server -cert server.PEM is running. s_client CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify error:num=1:unable to get issuer certificate verify return:1 CIPHER is CBC-DES-MD5 What has happened is that the 'SSLeay demo server' certificate's issuer ('CA') could not be found but because verify is not on, we don't care and the connection has been made anyway. It is now 'up' using CBC-DES-MD5 mode. This is an unauthenticate secure channel. You may not be talking to the right person but the data going to them is encrypted. s_client -verify 0 CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify error:num=1:unable to get issuer certificate verify return:1 CIPHER is CBC-DES-MD5 We are 'verifying' but only to depth 0, so since the 'SSLeay demo server' certificate passed the date and checksum, we are happy to proceed. s_client -verify 1 CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify error:num=1:unable to get issuer certificate verify return:0 ERROR verify error:unable to get issuer certificate In this case we failed to make the connection because we could not authenticate the certificate because we could not find the 'CA' certificate. s_client -verify 1 -CAfile eay1024.PEM CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server verify return:1 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify return:1 CIPHER is CBC-DES-MD5 We loaded the certificates from the file eay1024.PEM. Everything checked out and so we made the connection. s_client -verify 1 -CApath . CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server verify return:1 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify return:1 CIPHER is CBC-DES-MD5 We looked in out local directory for issuer certificates and 'found' a8556381.0 and so everything is ok. It is worth noting that 'CA' is a self certified certificate. If you are passed one of these, it will fail to 'verify' at depth 0 because we need to lookup the certifier of a certificate from some information that we trust and keep locally. SSL_CIPHER=CBC3-DES-MD5:RC4-MD5 export SSL_CIPHER s_client -verify 10 -CApath . -reconnect CONNECTED depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server verify return:1 depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA verify return:1 drop the connection and reconnect with the same session id CIPHER is CBC3-DES-MD5 This has done a full connection and then re-estabished it with the same session id but a new socket. No RSA stuff occures on the second connection. Note that we said we would prefer to use CBC3-DES-MD5 encryption and so, since the server s