For portability use BUF_strndup instead of strndup.
[openssl.git] / doc / ssleay.txt
index 3e964c2..29ea0ee 100644 (file)
@@ -1,10 +1,26 @@
 
 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.
+relevent but I'm working (very slowly) on new documentation.
 The current version can be found online at
 
 http://www.cryptsoft.com/ssleay/doc
@@ -523,17 +539,17 @@ int X509_verify_cert(
 The applications
 
 Ok, where to begin....
-In the begining, when SSLeay was small (April 1995), there
+In the beginning, when SSLeay was small (April 1995), there
 were but few applications, they did happily cohabit in
 the one bin directory.  Then over time, they did multiply and grow,
 and they started to look like microsoft software; 500k to print 'hello world'.
 A new approach was needed.  They were coalessed into one 'Monolithic'
 application, ssleay.  This one program is composed of many programs that
-can all be compiled independantly.
+can all be compiled independently.
 
 ssleay has 3 modes of operation.
-1) If the ssleay binaray has the name of one of its component programs, it
-executes that program and then exits.  This can be achieve by using hard or
+1) If the ssleay binary has the name of one of its component programs, it
+executes that program and then exits.  This can be achieved by using hard or
 symbolic links, or failing that, just renaming the binary.
 2) If the first argument to ssleay is the name of one of the component
 programs, that program runs that program and then exits.
@@ -1169,7 +1185,7 @@ typedef struct bio_st
        example is for BIO_s_sock().  A socket needs to be 
        assigned to the BIO before it can be used.
 -      'shutdown', this flag indicates if the underlying 
-       comunication primative being used should be closed/freed 
+       communication primitive being used should be closed/freed 
        when the BIO is closed.
 -      'flags' is used to hold extra state.  It is primarily used 
        to hold information about why a non-blocking operation 
@@ -1717,7 +1733,7 @@ int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b);
 
 int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
        Multiply a by a and return the result in 'r'. 'r' must not be
-       'a'.  This function is alot faster than BN_mul(r,a,a).  This is r=a*a.
+       'a'.  This function is a lot faster than BN_mul(r,a,a).  This is r=a*a.
 
 int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
        Divide 'm' by 'd' and return the result in 'dv' and the remainder
@@ -1783,7 +1799,7 @@ int BN_set_word(BIGNUM *a, unsigned long w);
 
 unsigned long BN_get_word(BIGNUM *a);
        Returns 'a' in an unsigned long.  Not remarkably, often 'a' will
-       be biger than a word, in which case 0xffffffffL is returned.
+       be bigger than a word, in which case 0xffffffffL is returned.
 
 Word Operations
 These functions are much more efficient that the normal bignum arithmetic
@@ -2042,7 +2058,7 @@ Now you will notice that macros like
                 PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \
                                        (char *)x, NULL,NULL,0,NULL)
 Don't do encryption normally.  If you want to PEM encrypt your X509 structure,
-either just call PEM_ASN1_write directly or just define you own
+either just call PEM_ASN1_write directly or just define your own
 macro variant.  As you can see, this macro just sets all encryption related
 parameters to NULL.
 
@@ -3781,12 +3797,12 @@ patent law and ITAR restrictions.
 
 Inside the USA there is also the unresolved issue of RC4/RC2 which were
 made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2).  I have
-copies of the origional postings if people are interested.  RSA I believe 
+copies of the original postings if people are interested.  RSA I believe 
 claim that they were 'trade-secrets' and that some-one broke an NDA in 
 revealing them.  Other claim they reverse engineered the algorithms from 
-compiled binaries.  If the algorithms were reverse engineered, I belive 
+compiled binaries.  If the algorithms were reverse engineered, I believe 
 RSA had no legal leg to stand on.  If an NDA was broken, I don't know.
-Regardless, RSA, I belive, is willing to go to court over the issue so 
+Regardless, RSA, I believe, is willing to go to court over the issue so 
 licencing is probably the best idea, or at least talk to them.
 If there are people who actually know more about this, pease let me know, I 
 don't want to vilify or spread miss-information if I can help it.
@@ -4127,7 +4143,7 @@ CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc().
 If it is not defined, they are #defined to malloc(), free() and realloc().
 
 the CRYPTO_malloc() routines by default just call the underlying library
-functons.
+functions.
 
 If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is
 turned on.  CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off.
@@ -4169,7 +4185,7 @@ The ca program uses the ssleay.conf file for most of its configuration
 
 ./ca -help
 
- -verbose        - Talk alot while doing things
+ -verbose        - Talk a lot while doing things
  -config file    - A config file. If you don't want to use the
                   default config file
  -name arg       - The particular CA definition to use
@@ -4279,7 +4295,7 @@ X-Status:
 Loading client certs into MSIE 3.01
 ===================================
 
-This document conatains all the information necessary to succesfully set up 
+This document contains all the information necessary to successfully set up 
 some scripts to issue client certs to Microsoft Internet Explorer. It 
 includes the required knowledge about the model MSIE uses for client 
 certification and includes complete sample scripts ready to play with. The 
@@ -4320,7 +4336,7 @@ login password.
 2.) The practical usage
 -----------------------
 
-Unfortunatly since CAPI is a system API you can't access its functions from 
+Unfortunately since CAPI is a system API you can't access its functions from 
 HTML code directly. For this purpose Microsoft provides a wrapper called 
 certenr3.dll. This DLL accesses the CAPI functions and provides an interface 
 usable from Visual Basic Script. One needs to install that library on the 
@@ -4374,7 +4390,7 @@ AcceptCredentials(sessionID, credentials, 0, FALSE)
 
 CRL's and CA certs are not required simply just the client cert. (It seems to 
 me that both are not even checked somehow.) The only format of the base64 
-encoded object I succesfully used was all characters in a very long string 
+encoded object I successfully used was all characters in a very long string 
 without line feeds or carriage returns. (Hey, it doesn't matter, only a 
 computer reads it!)
 
@@ -4521,7 +4537,7 @@ text. I use two templates to have a clearer script.
 site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You 
 need utils.c from there too.
 
-2nd note: I'm note quite sure wether the gawk script really handles all 
+2nd note: I'm note quite sure whether the gawk script really handles all 
 possible inputs for the request right! Today I don't use this construction 
 anymore myself.
 
@@ -5087,7 +5103,7 @@ It is of a similar speed to DES and IDEA, so unless it is required for
 meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable
 to stick to IDEA, or for the paranoid, Tripple DES.
 
-Mind you, having said all that, I should mention that I just read alot and
+Mind you, having said all that, I should mention that I just read a lot and
 implement ciphers, I'm a 'babe in the woods' when it comes to evaluating
 ciphers :-).
 
@@ -5550,7 +5566,7 @@ These 2 functions create and destroy SSL_CTX structures
 
 The SSL_CTX has a session_cache_mode which is by default,
 in SSL_SESS_CACHE_SERVER mode.  What this means is that the library
-will automatically add new session-id's to the cache apon sucsessful
+will automatically add new session-id's to the cache upon successful
 SSL_accept() calls.
 If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added
 to the cache.
@@ -5564,12 +5580,12 @@ SSL_SESS_NO_CACHE_BOTH  - Either SSL_accept() or SSL_connect().
 If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are
 not automatically removed each 255, SSL_connect()s or SSL_accept()s.
 
-By default, apon every 255 successful SSL_connect() or SSL_accept()s,
+By default, upon every 255 successful SSL_connect() or SSL_accept()s,
 the cache is flush.  Please note that this could be expensive on
 a heavily loaded SSL server, in which case, turn this off and
 clear the cache of old entries 'manually' (with one of the functions
 listed below) every few hours.  Perhaps I should up this number, it is hard
-to say.  Remember, the '255' new calls is just a mechanims to get called
+to say.  Remember, the '255' new calls is just a mechanism to get called
 every now and then, in theory at most 255 new session-id's will have been
 added but if 100 are added every minute, you would still have
 500 in the cache before any would start being flushed (assuming a 3 minute
@@ -5612,10 +5628,10 @@ if copy is 1.  Otherwise, the reference count is not modified.
 void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and
 int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback.
 
-These callbacks are basically indended to be used by processes to
+These callbacks are basically intended to be used by processes to
 send their session-id's to other processes.  I currently have not implemented
-non-blocking semantics for these callbacks, it is upto the appication
-to make the callbacks effiecent if they require blocking (perhaps
+non-blocking semantics for these callbacks, it is upto the application
+to make the callbacks efficient if they require blocking (perhaps
 by 'saving' them and then 'posting them' when control returns from
 the SSL_accept().
 
@@ -5743,7 +5759,7 @@ strucutre but also the private key and certificate associated with
 
 EXAMPLES.
 
-So lets play at being a wierd SSL server.
+So lets play at being a weird SSL server.
 
 /* setup a context */
 ctx=SSL_CTX_new();
@@ -6010,7 +6026,7 @@ one at a time, or use 'aliases' to specify the preference and order for
 the ciphers.
 
 There are a large number of aliases, but the most importaint are
-kRSA, kDHr, kDHd and kEDH for key exchange types.
+kRSA, kDHr, kDHd and kDHE for key exchange types.
 
 aRSA, aDSS, aNULL and aDH for authentication
 DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers
@@ -6045,20 +6061,20 @@ $ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP'
 
 RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
 RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
-EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
-EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
+DHE-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
+DHE-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
 DES-CBC3-SHA            SSLv3 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=SHA1
 IDEA-CBC-MD5            SSLv3 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=SHA1
-EDH-RSA-DES-CBC-SHA     SSLv3 Kx=DH       Au=RSA  Enc=DES(56)   Mac=SHA1
-EDH-DSS-DES-CBC-SHA     SSLv3 Kx=DH       Au=DSS  Enc=DES(56)   Mac=SHA1
+DHE-RSA-DES-CBC-SHA     SSLv3 Kx=DH       Au=RSA  Enc=DES(56)   Mac=SHA1
+DHE-DSS-DES-CBC-SHA     SSLv3 Kx=DH       Au=DSS  Enc=DES(56)   Mac=SHA1
 DES-CBC-SHA             SSLv3 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=SHA1
 DES-CBC3-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=MD5 
 DES-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=DES(56)   Mac=MD5 
 IDEA-CBC-MD5            SSLv2 Kx=RSA      Au=RSA  Enc=IDEA(128) Mac=MD5 
 RC2-CBC-MD5             SSLv2 Kx=RSA      Au=RSA  Enc=RC2(128)  Mac=MD5 
 RC4-MD5                 SSLv2 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
-EXP-EDH-RSA-DES-CBC     SSLv3 Kx=DH(512)  Au=RSA  Enc=DES(40)   Mac=SHA1 export
-EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512)  Au=DSS  Enc=DES(40)   Mac=SHA1 export
+EXP-DHE-RSA-DES-CBC     SSLv3 Kx=DH(512)  Au=RSA  Enc=DES(40)   Mac=SHA1 export
+EXP-DHE-DSS-DES-CBC-SHA SSLv3 Kx=DH(512)  Au=DSS  Enc=DES(40)   Mac=SHA1 export
 EXP-DES-CBC-SHA         SSLv3 Kx=RSA(512) Au=RSA  Enc=DES(40)   Mac=SHA1 export
 EXP-RC2-CBC-MD5         SSLv3 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
 EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
@@ -6229,7 +6245,7 @@ SSL_get_app_data
 void SSL_CTX_set_default_verify
 
 /* This callback, if set, totaly overrides the normal SSLeay verification
- * functions and should return 1 on sucesss and 0 on failure */
+ * functions and should return 1 on success and 0 on failure */
 void SSL_CTX_set_cert_verify_callback
 
 /* The following are the same as the equivilent SSL_xxx functions.
@@ -6373,7 +6389,7 @@ 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 since they are often capable of functioning as independent
 libraries
 
 First up, the general ciphers and message digests supported by the library.
@@ -6425,7 +6441,7 @@ DH        This is an implementation of the
        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
+You may have noticed the preceding 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
@@ -6573,7 +6589,7 @@ This information can be used to recall the functions when the 'error'
 condition has dissapeared.
 
 After the connection has been made, information can be retrived about the
-SSL session and the session-id values that have been decided apon.
+SSL session and the session-id values that have been decided upon.
 The 'peer' certificate can be retrieved.
 
 The session-id values include
@@ -6796,7 +6812,7 @@ all include e_os.h which contains OS/environment specific information.
 If you need to add something todo with a particular environment,
 add it to this file.  It is worth remembering that quite a few libraries,
 like lhash, des, md, sha etc etc do not include crypto/cryptlib.h.  This
-is because these libraries should be 'independantly compilable' and so I
+is because these libraries should be 'independently compilable' and so I
 try to keep them this way.
 e_os.h is not so much a part of SSLeay, as the placing in one spot all the
 evil OS dependant muck.
@@ -6818,7 +6834,7 @@ everthing will work as expected.  Don't edit progs.h by hand.
 make links re-generates the symbolic links that are used.  The reason why
 I keep everything in its own directory, and don't put all the
 test programs and header files in 'test' and 'include' is because I want
-to keep the 'sub-libraries' independant.  I still 'pull' out
+to keep the 'sub-libraries' independent.  I still 'pull' out
 indervidual libraries for use in specific projects where the code is
 required.  I have used the 'lhash' library in just about every software
 project I have worked on :-).