README.080

   1 This version of SSLeay has quite a lot of things different from the
   2 previous version.
   3
   4 Basically check all callback parameters, I will be producing documentation
   5 about how to use things in th future.  Currently I'm just getting 080 out
   6 the door.  Please not that there are several ways to do everything, and
   7 most of the applications in the apps directory are hybrids, some using old
   8 methods and some using new methods.
   9
  10 Have a look in demos/bio for some very simple programs and
  11 apps/s_client.c and apps/s_server.c for some more advanced versions.
  12 Notes are definitly needed but they are a week or so away.
  13
  14 Anyway, some quick nots from Tim Hudson (tjh@cryptsoft.com)
  15 ---
  16 Quick porting notes for moving from SSLeay-0.6.x to SSLeay-0.8.x to
  17 get those people that want to move to using the new code base off to
  18 a quick start.
  19
  20 Note that Eric has tidied up a lot of the areas of the API that were
  21 less than desirable and renamed quite a few things (as he had to break
  22 the API in lots of places anyrate). There are a whole pile of additional
  23 functions for making dealing with (and creating) certificates a lot
  24 cleaner.
  25
  26 01-Jul-97
  27 Tim Hudson
  28 tjh@cryptsoft.com
  29
  30 ---8<---
  31
  32 To maintain code that uses both SSLeay-0.6.x and SSLeay-0.8.x you could
  33 use something like the following (assuming you #include "crypto.h" which
  34 is something that you really should be doing).
  35
  36 #if SSLEAY_VERSION_NUMBER >= 0x0800
  37 #define SSLEAY8
  38 #endif
  39
  40 buffer.h -> splits into buffer.h and bio.h so you need to include bio.h
  41             too if you are working with BIO internal stuff (as distinct
  42             from simply using the interface in an opaque manner)
  43
  44 #include "bio.h"        - required along with "buffer.h" if you write
  45                           your own BIO routines as the buffer and bio
  46                           stuff that was intermixed has been separated
  47                           out
  48
  49 envelope.h -> evp.h  (which should have been done ages ago)
  50
  51 Initialisation ... don't forget these or you end up with code that
  52 is missing the bits required to do useful things (like ciphers):
  53
  54 SSLeay_add_ssl_algorithms()
  55 (probably also want SSL_load_error_strings() too but you should have
  56  already had that call in place)
  57
  58 SSL_CTX_new()   - requires an extra method parameter
  59                       SSL_CTX_new(SSLv23_method())
  60                       SSL_CTX_new(SSLv2_method())
  61                       SSL_CTX_new(SSLv3_method())
  62
  63                   OR to only have the server or the client code
  64                       SSL_CTX_new(SSLv23_server_method())
  65                       SSL_CTX_new(SSLv2_server_method())
  66                       SSL_CTX_new(SSLv3_server_method())
  67                   or
  68                       SSL_CTX_new(SSLv23_client_method())
  69                       SSL_CTX_new(SSLv2_client_method())
  70                       SSL_CTX_new(SSLv3_client_method())
  71
  72 SSL_set_default_verify_paths() ... renamed to the more appropriate
  73 SSL_CTX_set_default_verify_paths()
  74
  75 If you want to use client certificates then you have to add in a bit
  76 of extra stuff in that a SSLv3 server sends a list of those CAs that
  77 it will accept certificates from ... so you have to provide a list to
  78 SSLeay otherwise certain browsers will not send client certs.
  79
  80 SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(s_cert_file));
  81
  82
  83 X509_NAME_oneline(X)    -> X509_NAME_oneline(X,NULL,0)
  84                            or provide a buffer and size to copy the
  85                            result into
  86
  87 X509_add_cert ->  X509_STORE_add_cert (and you might want to read the
  88                   notes on X509_NAME structure changes too)
  89
  90
  91 VERIFICATION CODE
  92 =================
  93
  94 The codes have all be renamed from VERIFY_ERR_* to X509_V_ERR_* to
  95 more accurately reflect things.
  96
  97 The verification callback args are now packaged differently so that
  98 extra fields for verification can be added easily in future without
  99 having to break things by adding extra parameters each release :-)
 100
 101 X509_cert_verify_error_string -> X509_verify_cert_error_string
 102
 103
 104 BIO INTERNALS
 105 =============
 106
 107 Eric has fixed things so that extra flags can be introduced in
 108 the BIO layer in future without having to play with all the BIO
 109 modules by adding in some macros.
 110
 111 The ugly stuff using
 112         b->flags ~= (BIO_FLAGS_RW|BIO_FLAGS_SHOULD_RETRY)
 113 becomes
 114         BIO_clear_retry_flags(b)
 115
 116         b->flags |= (BIO_FLAGS_READ|BIO_FLAGS_SHOULD_RETRY)
 117 becomes
 118         BIO_set_retry_read(b)
 119
 120 Also ... BIO_get_retry_flags(b), BIO_set_flags(b)
 121
 122
 123
 124 OTHER THINGS
 125 ============
 126
 127 X509_NAME has been altered so that it isn't just a STACK ... the STACK
 128 is now in the "entries" field ... and there are a pile of nice functions
 129 for getting at the details in a much cleaner manner.
 130
 131 SSL_CTX has been altered ... "cert" is no longer a direct member of this
 132 structure ... things are now down under "cert_store" (see x509_vfy.h) and
 133 things are no longer in a CERTIFICATE_CTX but instead in a X509_STORE.
 134 If your code "knows" about this level of detail then it will need some
 135 surgery.
 136
 137 If you depending on the incorrect spelling of a number of the error codes
 138 then you will have to change your code as these have been fixed.
 139
 140 ENV_CIPHER "type" got renamed to "nid" and as that is what it actually
 141 has been all along so this makes things clearer.
 142 ify_cert_error_string(ctx->error));
 143
 144 SSL_R_NO_CIPHER_WE_TRUST -> SSL_R_NO_CIPHER_LIST
 145                         and SSL_R_REUSE_CIPHER_LIST_NOT_ZERO
 146
 147