documented updates
[gnutls.git] / doc / cha-upgrade.texi
blobe52ce29458ed17a3bfe7ea48ea4726039c55d642
1 @node Upgrading from previous versions
2 @appendix Upgrading from previous versions
3 @cindex upgrading
5 The GnuTLS library typically maintains binary and source code compatibility
6 across versions. The releases that have the major version increased
7 break binary compatibility but source compatibility is provided.
8 This section lists exceptional cases where changes to existing code are
9 required due to library changes.
11 @heading Upgrading to 2.12.x from previous versions
13 GnuTLS 2.12.x is binary compatible with previous versions but changes the
14 semantics of @funcintref{gnutls_transport_set_lowat}, which might cause breakage
15 in applications that relied on its default value be 1. Two fixes
16 are proposed:
17 @itemize
18 @item  Quick fix. Explicitly call @code{gnutls_transport_set_lowat (session, 1);}
19 after @funcref{gnutls_init}.
20 @item Long term fix. Because later versions of gnutls abolish the functionality 
21 of using the system call @funcintref{select} to check for gnutls pending data, the 
22 function @funcref{gnutls_record_check_pending} has to be used to achieve the same 
23 functionality as described in @ref{Asynchronous operation}.
24 @end itemize
26 @heading Upgrading to 3.0.x from 2.12.x
28 GnuTLS 3.0.x is source compatible with previous versions except for the functions
29 listed below.
31 @multitable @columnfractions .30 .60
32 @headitem Old function @tab Replacement
34 @item @funcintref{gnutls_transport_set_lowat} @tab
35 To replace its functionality the function @funcref{gnutls_record_check_pending} has to be used,
36 as described in @ref{Asynchronous operation}
38 @item @funcintref{gnutls_session_get_server_random},
39 @funcintref{gnutls_session_get_client_random} 
40 @tab 
41 They are replaced by the safer function @funcref{gnutls_session_get_random}
43 @item @funcintref{gnutls_session_get_master_secret} 
44 @tab Replaced by the keying material exporters discussed in @ref{Keying Material Exporters}
46 @item @funcintref{gnutls_transport_set_global_errno}
47 @tab Replaced by using the system's errno fascility or @funcref{gnutls_transport_set_errno}.
49 @item @funcintref{gnutls_x509_privkey_verify_data}
50 @tab Replaced by @funcref{gnutls_pubkey_verify_data}.
52 @item @funcintref{gnutls_certificate_verify_peers}
53 @tab Replaced by @funcref{gnutls_certificate_verify_peers2}.
55 @item @funcintref{gnutls_psk_netconf_derive_key}
56 @tab Removed. The key derivation function was never standardized.
58 @item @funcintref{gnutls_session_set_finished_function}
59 @tab Removed.
61 @item @funcintref{gnutls_ext_register}
62 @tab Removed. Extension registration API is now internal to allow easier changes in the API.
64 @item @funcintref{gnutls_certificate_get_x509_crls}, @funcintref{gnutls_certificate_get_x509_cas}
65 @tab Removed to allow updating the internal structures. Replaced by @funcref{gnutls_certificate_get_issuer}.
67 @item @funcintref{gnutls_certificate_get_openpgp_keyring}
68 @tab Removed.
70 @item @funcintref{gnutls_ia_*}
71 @tab Removed. The inner application extensions were completely removed (they failed to be standardized).
73 @end multitable
75 @heading Upgrading to 3.1.x from 3.0.x
77 GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few
78 functions have been deprecated and are listed below.
80 @multitable @columnfractions .30 .60
81 @headitem Old function @tab Replacement
83 @item @funcintref{gnutls_pubkey_verify_hash} 
84 @tab The function @funcref{gnutls_pubkey_verify_hash2} is provided and
85 is functionally equivalent and safer to use.
87 @item @funcintref{gnutls_pubkey_verify_data} 
88 @tab The function @funcref{gnutls_pubkey_verify_data2} is provided and
89 is functionally equivalent and safer to use.
91 @end multitable