Import of old SSLeay release: SSLeay 0.8.1b
[openssl.git] / 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