added the change of priority string NORMAL in documentation
[gnutls:gnutls.git] / doc / cha-upgrade.texi
1 @node Upgrading from previous versions
2 @appendix Upgrading from previous versions
3 @cindex upgrading
4
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.
10
11 @heading Upgrading to 2.12.x from previous versions
12
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
25
26 @heading Upgrading to 3.0.x from 2.12.x
27
28 GnuTLS 3.0.x is source compatible with previous versions except for the functions
29 listed below.
30
31 @multitable @columnfractions .30 .60
32 @headitem Old function @tab Replacement
33
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}
37
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}
42
43 @item @funcintref{gnutls_session_get_master_secret} 
44 @tab Replaced by the keying material exporters discussed in @ref{Deriving keys for other applications/protocols}
45
46 @item @funcintref{gnutls_transport_set_global_errno}
47 @tab Replaced by using the system's errno fascility or @funcref{gnutls_transport_set_errno}.
48
49 @item @funcintref{gnutls_x509_privkey_verify_data}
50 @tab Replaced by @funcref{gnutls_pubkey_verify_data2}.
51
52 @item @funcintref{gnutls_certificate_verify_peers}
53 @tab Replaced by @funcref{gnutls_certificate_verify_peers2}.
54
55 @item @funcintref{gnutls_psk_netconf_derive_key}
56 @tab Removed. The key derivation function was never standardized.
57
58 @item @funcintref{gnutls_session_set_finished_function}
59 @tab Removed.
60
61 @item @funcintref{gnutls_ext_register}
62 @tab Removed. Extension registration API is now internal to allow easier changes in the API.
63
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}.
66
67 @item @funcintref{gnutls_certificate_get_openpgp_keyring}
68 @tab Removed.
69
70 @item @funcintref{gnutls_ia_}
71 @tab Removed. The inner application extensions were completely removed (they failed to be standardized).
72
73 @end multitable
74
75 @heading Upgrading to 3.1.x from 3.0.x
76
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.
79
80 @multitable @columnfractions .30 .60
81 @headitem Old function @tab Replacement
82
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.
86
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.
90
91 @end multitable
92
93 @heading Upgrading to 3.2.x from 3.1.x
94
95 GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few
96 functions have been deprecated and are listed below.
97
98 @multitable @columnfractions .30 .60
99 @headitem Old function @tab Replacement
100
101 @item @funcintref{gnutls_privkey_sign_raw_data} 
102 @tab The function @funcref{gnutls_privkey_sign_hash} is equivalent
103 when the flag @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} is specified.
104
105 @end multitable
106
107 @heading Upgrading to 3.3.x from 3.2.x
108
109 GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases;
110 however there few changes in semantics which are listed below.
111
112 @multitable @columnfractions .30 .60
113 @headitem Old function @tab Replacement
114
115 @item @funcintref{gnutls_global_init} 
116 @tab No longer required. The library is initialized using a constructor.
117
118 @item @funcintref{gnutls_global_deinit} 
119 @tab No longer required. The library is deinitialized using a destructor.
120
121 @end multitable
122
123 @heading Upgrading to 3.4.x from 3.3.x
124
125 GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases;
126 however, several deprecated functions were removed, and are listed below.
127
128 @multitable @columnfractions .30 .60
129 @headitem Old function @tab Replacement
130
131 @item Priority string "NORMAL" has been modified
132 @tab The following string emulates the 3.3.x behavior "NORMAL:+VERS-SSL3.0:+ARCFOUR-128:+DHE-DSS:+SIGN-DSA-SHA512:+SIGN-DSA-SHA256:+SIGN-DSA-SHA1"
133
134 @item @funcintref{gnutls_certificate_client_set_retrieve_function},
135 @funcintref{gnutls_certificate_server_set_retrieve_function}
136 @tab @funcref{gnutls_certificate_set_retrieve_function}
137
138 @item @funcintref{gnutls_certificate_set_rsa_export_params},
139 @funcintref{gnutls_rsa_export_get_modulus_bits},
140 @funcintref{gnutls_rsa_export_get_pubkey},
141 @funcintref{gnutls_rsa_params_cpy},
142 @funcintref{gnutls_rsa_params_deinit},
143 @funcintref{gnutls_rsa_params_export_pkcs1},
144 @funcintref{gnutls_rsa_params_export_raw},
145 @funcintref{gnutls_rsa_params_generate2},
146 @funcintref{gnutls_rsa_params_import_pkcs1},
147 @funcintref{gnutls_rsa_params_import_raw},
148 @funcintref{gnutls_rsa_params_init}
149 @tab No replacement; the library does not support the RSA-EXPORT ciphersuites.
150
151 @item @funcintref{gnutls_pubkey_verify_hash},
152 @tab @funcref{gnutls_pubkey_verify_hash2}.
153
154 @item @funcintref{gnutls_pubkey_verify_data},
155 @tab @funcref{gnutls_pubkey_verify_data2}.
156
157 @item @funcintref{gnutls_x509_crt_get_verify_algorithm},
158 @tab @funcref{gnutls_x509_crt_get_signature_algorithm}.
159
160 @item @funcintref{gnutls_pubkey_get_verify_algorithm},
161 @tab No replacement; a similar function is @funcref{gnutls_pubkey_get_preferred_hash_algorithm}.
162
163 @item @funcintref{gnutls_certificate_type_set_priority},
164 @funcintref{gnutls_cipher_set_priority},
165 @funcintref{gnutls_compression_set_priority},
166 @funcintref{gnutls_kx_set_priority},
167 @funcintref{gnutls_mac_set_priority},
168 @funcintref{gnutls_protocol_set_priority}
169 @tab @funcref{gnutls_priority_set_direct}.
170
171 @item @funcintref{gnutls_sign_callback_get},
172 @funcintref{gnutls_sign_callback_set}
173 @tab @funcref{gnutls_privkey_import_ext3}
174
175 @item @funcintref{gnutls_x509_crt_verify_hash}
176 @tab @funcref{gnutls_pubkey_verify_hash2}
177
178 @item @funcintref{gnutls_x509_crt_verify_data}
179 @tab @funcref{gnutls_pubkey_verify_data2}
180
181 @end multitable