doc/ssleay.doc

   1 SSLeay: a cryptographic kitchen sink.
   2
   3 1st December 1995
   4 Way back at the start of April 1995, I was looking for a mindless
   5 programming project.  A friend of mine (Tim Hudson) said "why don't you do SSL,
   6 it has DES encryption in it and I would not mind using it in a SSL telnet".
   7 While it was true I had written a DES library in previous years, litle
   8 did I know what an expansive task SSL would turn into.
   9
  10 First of all, the SSL protocol contains DES encryption.  Well and good.  My
  11 DES library was fast and portable.  It also contained the RSA's RC4 stream
  12 cipher.  Again, not a problem, some-one had just posted to sci.crypt
  13 something that was claimed to be RC4.  It also contained IDEA, I had the
  14 specifications, not a problem to implement.  MD5, an RFC, trivial, at most
  15 I could spend a week or so trying to see if I could speed up the
  16 implementation.  All in all a nice set of ciphers.
  17 Then the first 'expantion of the scope', RSA public key
  18 encryption.  Since I did not knowing a thing about public key encryption
  19 or number theory, this appeared quite a daunting task.  Just writing a
  20 big number library would be problomatic in itself, let alone making it fast.
  21 At this point the scope of 'implementing SSL' expands eponentialy.
  22 First of all, the RSA private keys  were being kept in ASN.1 format.
  23 Thankfully the RSA PKCS series of documents explains this format.  So I now
  24 needed to be able to encode and decode arbitary ASN.1 objects.  The Public
  25 keys were embeded in X509 certificates.  Hmm... these are not only
  26 ASN.1 objects but they make up a heirachy of authentication.  To
  27 authenticate a X509 certificate one needs to retrieve it's issuers
  28 certificate etc etc.  Hmm..., so I also need to implement some kind
  29 of certificate management software.  I would also have to implement
  30 software to authenticate certificates.  At this point the support code made
  31 the SSL part of my library look quite small.
  32 Around this time, the first version of SSLeay was released.
  33
  34 Ah, but here was the problem, I was not happy with the code so far.  As may
  35 have become obvious, I had been treating all of this as a learning
  36 exersize, so I have completely written the library myself.  As such, due
  37 to the way it had grown like a fungus, much of the library was not
  38 'elagent' or neat.  There were global and static variables all over the
  39 place, the SSL part did not even handle non-blocking IO.
  40 The Great rewrite began.
  41
  42 As of this point in time, the 'Great rewrite' has almost finished.  So what
  43 follows is an approximate list of what is actually SSLeay 0.5.0
  44
  45 /********* This needs to be updated for 0.6.0+ *************/
  46
  47 ---
  48 The library contains the following routines.  Please note that most of these
  49 functions are not specfic for SSL or any other particular cipher
  50 implementation.  I have tried to make all the routines as general purpose
  51 as possible.  So you should not think of this library as an SSL
  52 implemtation, but rather as a library of cryptographic functions
  53 that also contains SSL.  I refer to each of these function groupings as
  54 libraries since they are often capable of functioning as independant
  55 libraries
  56
  57 First up, the general ciphers and message digests supported by the library.
  58
  59 MD2     rfc???, a standard 'by parts' interface to this algorithm.
  60 MD5     rfc???, the same type of interface as for the MD2 library except a
  61         different algorithm.
  62 SHA     THe Secure Hash Algorithm.  Again the same type of interface as
  63         MD2/MD5 except the digest is 20 bytes.
  64 SHA1    The 'revised' version of SHA.  Just about identical to SHA except
  65         for one tweak of an inner loop.
  66 DES     This is my libdes library that has been floating around for the last
  67         few years.  It has been enhanced for no other reason than completeness.
  68         It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and
  69         triple DES modes of ecb, cbc, cfb64 and ofb64.  cfb64 and ofb64 are
  70         functional interfaces to the 64 bit modes of cfb and ofb used in
  71         such a way thay they function as single character interfaces.
  72 RC4     The RSA Inc. stream cipher.
  73 RC2     The RSA Inc. block cipher.
  74 IDEA    An implmentation of the IDEA cipher, the library supports ecb, cbc,
  75         cfb64 and ofb64 modes of operation.
  76
  77 Now all the above mentioned ciphers and digests libraries support high
  78 speed, minimal 'crap in the way' type interfaces.  For fastest and
  79 lowest level access, these routines should be used directly.
  80
  81 Now there was also the matter of public key crypto systems.  These are
  82 based on large integer arithmatic.
  83
  84 BN      This is my large integer library.  It supports all the normal
  85         arithmentic operations.  It uses malloc extensivly and as such has
  86         no limits of the size of the numbers being manipulated.  If you
  87         wish to use 4000 bit RSA moduli, these routines will handle it.
  88         This library also contains routines to 'generate' prime numbers and
  89         to test for primality.  The RSA and DH libraries sit on top of this
  90         library.  As of this point in time, I don't support SHA, but
  91         when I do add it, it will just sit on top of the routines contained
  92         in this library.
  93 RSA     This implements the RSA public key algorithm.  It also contains
  94         routines that will generate a new private/public key pair.
  95         All the RSA functions conform to the PKCS#1 standard.
  96 DH      This is an implementation of the
  97         Diffie-Hellman protocol.  There are all the require routines for
  98         the protocol, plus extra routines that can be used to generate a
  99         strong prime for use with a specified generator.  While this last
 100         routine is not generally required by applications implementing DH,
 101         It is present for completeness and because I thing it is much
 102         better to be able to 'generate' your own 'magic' numbers as oposed
 103         to using numbers suplied by others.  I conform to the PKCS#3
 104         standard where required.
 105
 106 You may have noticed the preceeding section mentions the 'generation' of
 107 prime numbers.  Now this requries the use of 'random numbers'.
 108
 109 RAND    This psuedo-random number library is based on MD5 at it's core
 110         and a large internal state (2k bytes).  Once you have entered enough
 111         seed data into this random number algorithm I don't feel
 112         you will ever need to worry about it generating predictable output.
 113         Due to the way I am writing a portable library, I have left the
 114         issue of how to get good initial random seed data upto the
 115         application but I do have support routines for saving and loading a
 116         persistant random number state for use between program runs.
 117
 118 Now to make all these ciphers easier to use, a higher level
 119 interface was required.  In this form, the same function would be used to
 120 encrypt 'by parts', via any one of the above mentioned ciphers.
 121
 122 EVP     The Digital EnVeloPe library is quite large.  At it's core are
 123         function to perform encryption and decryption by parts while using
 124         an initial parameter to specify which of the 17 different ciphers
 125         or 4 different message digests to use.  On top of these are implmented
 126         the digital signature functions, sign, verify, seal and open.
 127         Base64 encoding of binary data is also done in this library.
 128
 129 PEM     rfc???? describe the format for Privacy Enhanced eMail.
 130         As part of this standard, methods of encoding digital enveloped
 131         data is an ascii format are defined.  As such, I use a form of these
 132         to encode enveloped data.  While at this point in time full support
 133         for PEM has not been built into the library, a minimal subset of
 134         the secret key and Base64 encoding is present.  These reoutines are
 135         mostly used to Ascii encode binary data with a 'type' associated
 136         with it and perhaps details of private key encryption used to
 137         encrypt the data.
 138
 139 PKCS7   This is another Digital Envelope encoding standard which uses ASN.1
 140         to encode the data.  At this point in time, while there are some
 141         routines to encode and decode this binary format, full support is
 142         not present.
 143
 144 As Mentioned, above, there are several different ways to encode
 145 data structures.
 146
 147 ASN1    This library is more a set of primatives used to encode the packing
 148         and unpacking of data structures.  It is used by the X509
 149         certificate standard and by the PKCS standards which are used by
 150         this library.  It also contains routines for duplicating and signing
 151         the structures asocisated with X509.
 152
 153 X509    The X509 library contains routines for packing and unpacking,
 154         verifying and just about every thing else you would want to do with
 155         X509 certificates.
 156
 157 PKCS7   PKCS-7 is a standard for encoding digital envelope data
 158         structures.  At this point in time the routines will load and save
 159         DER forms of these structees.  They need to be re-worked to support
 160         the BER form which is the normal way PKCS-7 is encoded.  If the
 161         previous 2 sentances don't make much sense, don't worry, this
 162         library is not used by this version of SSLeay anyway.
 163
 164 OBJ     ASN.1 uses 'object identifiers' to identify objects.  A set of
 165         functions were requred to translate from ASN.1 to an intenger, to a
 166         character string.  This library provieds these translations
 167
 168 Now I mentioned an X509 library.  X509 specified a hieachy of certificates
 169 which needs to be traversed to authenticate particular certificates.
 170
 171 METH    This library is used to push 'methods' of retrieving certificates
 172         into the library.  There are some supplied 'methods' with SSLeay
 173         but applications can add new methods if they so desire.
 174         This library has not been finished and is not being used in this
 175         version.
 176
 177 Now all the above are required for use in the initial point of this project.
 178
 179 SSL     The SSL protocol.  This is a full implmentation of SSL v 2.  It
 180         support both server and client authentication.  SSL v 3 support
 181         will be added when the SSL v 3 specification is released in it's
 182         final form.
 183
 184 Now quite a few of the above mentioned libraries rely on a few 'complex'
 185 data structures.  For each of these I have a library.
 186
 187 Lhash   This is a hash table library which is used extensivly.
 188
 189 STACK   An implemetation of a Stack data structure.
 190
 191 BUF     A simple character array structure that also support a function to
 192         check that the array is greater that a certain size, if it is not,
 193         it is realloced so that is it.
 194
 195 TXT_DB  A simple memory based text file data base.  The application can specify
 196         unique indexes that will be enforced at update time.
 197
 198 CONF    Most of the programs written for this library require a configuration
 199         file.  Instead of letting programs constantly re-implment this
 200         subsystem, the CONF library provides a consistant and flexable
 201         interface to not only configuration files but also environment
 202         variables.
 203
 204 But what about when something goes wrong?
 205 The one advantage (and perhaps disadvantage) of all of these
 206 functions being in one library was the ability to implement a
 207 single error reporting system.
 208
 209 ERR     This library is used to report errors.  The error system records
 210         library number, function number (in the library) and reason
 211         number.  Multiple errors can be reported so that an 'error' trace
 212         is created.  The errors can be printed in numeric or textual form.
 213