diff options
Diffstat (limited to 'doc/ssleay.doc')
| -rw-r--r-- | doc/ssleay.doc | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/doc/ssleay.doc b/doc/ssleay.doc new file mode 100644 index 0000000000..a0e86aef7c --- /dev/null +++ b/doc/ssleay.doc @@ -0,0 +1,213 @@ +SSLeay: a cryptographic kitchen sink. + +1st December 1995 +Way back at the start of April 1995, I was looking for a mindless +programming project. A friend of mine (Tim Hudson) said "why don't you do SSL, +it has DES encryption in it and I would not mind using it in a SSL telnet". +While it was true I had written a DES library in previous years, litle +did I know what an expansive task SSL would turn into. + +First of all, the SSL protocol contains DES encryption. Well and good. My +DES library was fast and portable. It also contained the RSA's RC4 stream +cipher. Again, not a problem, some-one had just posted to sci.crypt +something that was claimed to be RC4. It also contained IDEA, I had the +specifications, not a problem to implement. MD5, an RFC, trivial, at most +I could spend a week or so trying to see if I could speed up the +implementation. All in all a nice set of ciphers. +Then the first 'expantion of the scope', RSA public key +encryption. Since I did not knowing a thing about public key encryption +or number theory, this appeared quite a daunting task. Just writing a +big number library would be problomatic in itself, let alone making it fast. +At this point the scope of 'implementing SSL' expands eponentialy. +First of all, the RSA private keys were being kept in ASN.1 format. +Thankfully the RSA PKCS series of documents explains this format. So I now +needed to be able to encode and decode arbitary ASN.1 objects. The Public +keys were embeded in X509 certificates. Hmm... these are not only +ASN.1 objects but they make up a heirachy of authentication. To +authenticate a X509 certificate one needs to retrieve it's issuers +certificate etc etc. Hmm..., so I also need to implement some kind +of certificate management software. I would also have to implement +software to authenticate certificates. At this point the support code made +the SSL part of my library look quite small. +Around this time, the first version of SSLeay was released. + +Ah, but here was the problem, I was not happy with the code so far. As may +have become obvious, I had been treating all of this as a learning +exersize, so I have completely written the library myself. As such, due +to the way it had grown like a fungus, much of the library was not +'elagent' or neat. There were global and static variables all over the +place, the SSL part did not even handle non-blocking IO. +The Great rewrite began. + +As of this point in time, the 'Great rewrite' has almost finished. So what +follows is an approximate list of what is actually SSLeay 0.5.0 + +/********* This needs to be updated for 0.6.0+ *************/ + +--- +The library contains the following routines. Please note that most of these +functions are not specfic for SSL or any other particular cipher +implementation. I have tried to make all the routines as general purpose +as possible. So you should not think of this library as an SSL +implemtation, but rather as a library of cryptographic functions +that also contains SSL. I refer to each of these function groupings as +libraries since they are often capable of functioning as independant +libraries + +First up, the general ciphers and message digests supported by the library. + +MD2 rfc???, a standard 'by parts' interface to this algorithm. +MD5 rfc???, the same type of interface as for the MD2 library except a + different algorithm. +SHA THe Secure Hash Algorithm. Again the same type of interface as + MD2/MD5 except the digest is 20 bytes. +SHA1 The 'revised' version of SHA. Just about identical to SHA except + for one tweak of an inner loop. +DES This is my libdes library that has been floating around for the last + few years. It has been enhanced for no other reason than completeness. + It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and + triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are + functional interfaces to the 64 bit modes of cfb and ofb used in + such a way thay they function as single character interfaces. +RC4 The RSA Inc. stream cipher. +RC2 The RSA Inc. block cipher. +IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc, + cfb64 and ofb64 modes of operation. + +Now all the above mentioned ciphers and digests libraries support high +speed, minimal 'crap in the way' type interfaces. For fastest and +lowest level access, these routines should be used directly. + +Now there was also the matter of public key crypto systems. These are +based on large integer arithmatic. + +BN This is my large integer library. It supports all the normal + arithmentic operations. It uses malloc extensivly and as such has + no limits of the size of the numbers being manipulated. If you + wish to use 4000 bit RSA moduli, these routines will handle it. + This library also contains routines to 'generate' prime numbers and + to test for primality. The RSA and DH libraries sit on top of this + library. As of this point in time, I don't support SHA, but + when I do add it, it will just sit on top of the routines contained + in this library. +RSA This implements the RSA public key algorithm. It also contains + routines that will generate a new private/public key pair. + All the RSA functions conform to the PKCS#1 standard. +DH This is an implementation of the + Diffie-Hellman protocol. There are all the require routines for + the protocol, plus extra routines that can be used to generate a + strong prime for use with a specified generator. While this last + routine is not generally required by applications implementing DH, + It is present for completeness and because I thing it is much + better to be able to 'generate' your own 'magic' numbers as oposed + to using numbers suplied by others. I conform to the PKCS#3 + standard where required. + +You may have noticed the preceeding section mentions the 'generation' of +prime numbers. Now this requries the use of 'random numbers'. + +RAND This psuedo-random number library is based on MD5 at it's core + and a large internal state (2k bytes). Once you have entered enough + seed data into this random number algorithm I don't feel + you will ever need to worry about it generating predictable output. + Due to the way I am writing a portable library, I have left the + issue of how to get good initial random seed data upto the + application but I do have support routines for saving and loading a + persistant random number state for use between program runs. + +Now to make all these ciphers easier to use, a higher level +interface was required. In this form, the same function would be used to +encrypt 'by parts', via any one of the above mentioned ciphers. + +EVP The Digital EnVeloPe library is quite large. At it's core are + function to perform encryption and decryption by parts while using + an initial parameter to specify which of the 17 different ciphers + or 4 different message digests to use. On top of these are implmented + the digital signature functions, sign, verify, seal and open. + Base64 encoding of binary data is also done in this library. + +PEM rfc???? describe the format for Privacy Enhanced eMail. + As part of this standard, methods of encoding digital enveloped + data is an ascii format are defined. As such, I use a form of these + to encode enveloped data. While at this point in time full support + for PEM has not been built into the library, a minimal subset of + the secret key and Base64 encoding is present. These reoutines are + mostly used to Ascii encode binary data with a 'type' associated + with it and perhaps details of private key encryption used to + encrypt the data. + +PKCS7 This is another Digital Envelope encoding standard which uses ASN.1 + to encode the data. At this point in time, while there are some + routines to encode and decode this binary format, full support is + not present. + +As Mentioned, above, there are several different ways to encode +data structures. + +ASN1 This library is more a set of primatives used to encode the packing + and unpacking of data structures. It is used by the X509 + certificate standard and by the PKCS standards which are used by + this library. It also contains routines for duplicating and signing + the structures asocisated with X509. + +X509 The X509 library contains routines for packing and unpacking, + verifying and just about every thing else you would want to do with + X509 certificates. + +PKCS7 PKCS-7 is a standard for encoding digital envelope data + structures. At this point in time the routines will load and save + DER forms of these structees. They need to be re-worked to support + the BER form which is the normal way PKCS-7 is encoded. If the + previous 2 sentances don't make much sense, don't worry, this + library is not used by this version of SSLeay anyway. + +OBJ ASN.1 uses 'object identifiers' to identify objects. A set of + functions were requred to translate from ASN.1 to an intenger, to a + character string. This library provieds these translations + +Now I mentioned an X509 library. X509 specified a hieachy of certificates +which needs to be traversed to authenticate particular certificates. + +METH This library is used to push 'methods' of retrieving certificates + into the library. There are some supplied 'methods' with SSLeay + but applications can add new methods if they so desire. + This library has not been finished and is not being used in this + version. + +Now all the above are required for use in the initial point of this project. + +SSL The SSL protocol. This is a full implmentation of SSL v 2. It + support both server and client authentication. SSL v 3 support + will be added when the SSL v 3 specification is released in it's + final form. + +Now quite a few of the above mentioned libraries rely on a few 'complex' +data structures. For each of these I have a library. + +Lhash This is a hash table library which is used extensivly. + +STACK An implemetation of a Stack data structure. + +BUF A simple character array structure that also support a function to + check that the array is greater that a certain size, if it is not, + it is realloced so that is it. + +TXT_DB A simple memory based text file data base. The application can specify + unique indexes that will be enforced at update time. + +CONF Most of the programs written for this library require a configuration + file. Instead of letting programs constantly re-implment this + subsystem, the CONF library provides a consistant and flexable + interface to not only configuration files but also environment + variables. + +But what about when something goes wrong? +The one advantage (and perhaps disadvantage) of all of these +functions being in one library was the ability to implement a +single error reporting system. + +ERR This library is used to report errors. The error system records + library number, function number (in the library) and reason + number. Multiple errors can be reported so that an 'error' trace + is created. The errors can be printed in numeric or textual form. + |