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 previous versions
  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 @ref{gnutls_session_get_random}
  42
  43 @item @funcintref{gnutls_session_get_master_secret}
  44 @tab Replaced by the keying material exporters discussed in @ref{Keying Material Exporters}
  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_data}.
  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