|
Packit |
549fdc |
@node Upgrading from previous versions
|
|
Packit |
549fdc |
@appendix Upgrading from previous versions
|
|
Packit |
549fdc |
@cindex upgrading
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The GnuTLS library typically maintains binary and source code compatibility
|
|
Packit |
549fdc |
across versions. The releases that have the major version increased
|
|
Packit |
549fdc |
break binary compatibility but source compatibility is provided.
|
|
Packit |
549fdc |
This section lists exceptional cases where changes to existing code are
|
|
Packit |
549fdc |
required due to library changes.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 2.12.x from previous versions
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 2.12.x is binary compatible with previous versions but changes the
|
|
Packit |
549fdc |
semantics of @funcintref{gnutls_transport_set_lowat}, which might cause breakage
|
|
Packit |
549fdc |
in applications that relied on its default value be 1. Two fixes
|
|
Packit |
549fdc |
are proposed:
|
|
Packit |
549fdc |
@itemize
|
|
Packit |
549fdc |
@item Quick fix. Explicitly call @code{gnutls_transport_set_lowat (session, 1);}
|
|
Packit |
549fdc |
after @funcref{gnutls_init}.
|
|
Packit |
549fdc |
@item Long term fix. Because later versions of gnutls abolish the functionality
|
|
Packit |
549fdc |
of using the system call @funcintref{select} to check for gnutls pending data, the
|
|
Packit |
549fdc |
function @funcref{gnutls_record_check_pending} has to be used to achieve the same
|
|
Packit |
549fdc |
functionality as described in @ref{Asynchronous operation}.
|
|
Packit |
549fdc |
@end itemize
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.0.x from 2.12.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.0.x is source compatible with previous versions except for the functions
|
|
Packit |
549fdc |
listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old function @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_transport_set_lowat} @tab
|
|
Packit |
549fdc |
To replace its functionality the function @funcref{gnutls_record_check_pending} has to be used,
|
|
Packit |
549fdc |
as described in @ref{Asynchronous operation}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_session_get_server_random},
|
|
Packit |
549fdc |
@funcintref{gnutls_session_get_client_random}
|
|
Packit |
549fdc |
@tab
|
|
Packit |
549fdc |
They are replaced by the safer function @funcref{gnutls_session_get_random}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_session_get_master_secret}
|
|
Packit |
549fdc |
@tab Replaced by the keying material exporters discussed in @ref{Deriving keys for other applications/protocols}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_transport_set_global_errno}
|
|
Packit |
549fdc |
@tab Replaced by using the system's errno facility or @funcref{gnutls_transport_set_errno}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_x509_privkey_verify_data}
|
|
Packit |
549fdc |
@tab Replaced by @funcref{gnutls_pubkey_verify_data2}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_verify_peers}
|
|
Packit |
549fdc |
@tab Replaced by @funcref{gnutls_certificate_verify_peers2}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_psk_netconf_derive_key}
|
|
Packit |
549fdc |
@tab Removed. The key derivation function was never standardized.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_session_set_finished_function}
|
|
Packit |
549fdc |
@tab Removed.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_ext_register}
|
|
Packit |
549fdc |
@tab Removed. Extension registration API is now internal to allow easier changes in the API.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_get_x509_crls}, @funcintref{gnutls_certificate_get_x509_cas}
|
|
Packit |
549fdc |
@tab Removed to allow updating the internal structures. Replaced by @funcref{gnutls_certificate_get_issuer}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_get_openpgp_keyring}
|
|
Packit |
549fdc |
@tab Removed.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_ia_}
|
|
Packit |
549fdc |
@tab Removed. The inner application extensions were completely removed (they failed to be standardized).
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.1.x from 3.0.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few
|
|
Packit |
549fdc |
functions have been deprecated and are listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old function @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_pubkey_verify_hash}
|
|
Packit |
549fdc |
@tab The function @funcref{gnutls_pubkey_verify_hash2} is provided and
|
|
Packit |
549fdc |
is functionally equivalent and safer to use.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_pubkey_verify_data}
|
|
Packit |
549fdc |
@tab The function @funcref{gnutls_pubkey_verify_data2} is provided and
|
|
Packit |
549fdc |
is functionally equivalent and safer to use.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.2.x from 3.1.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few
|
|
Packit |
549fdc |
functions have been deprecated and are listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old function @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_privkey_sign_raw_data}
|
|
Packit |
549fdc |
@tab The function @funcref{gnutls_privkey_sign_hash} is equivalent
|
|
Packit |
549fdc |
when the flag @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} is specified.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.3.x from 3.2.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases;
|
|
Packit |
549fdc |
however there few changes in semantics which are listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old function @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_global_init}
|
|
Packit |
549fdc |
@tab No longer required. The library is initialized using a constructor.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_global_deinit}
|
|
Packit |
549fdc |
@tab No longer required. The library is deinitialized using a destructor.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.4.x from 3.3.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases;
|
|
Packit |
549fdc |
however, several deprecated functions were removed, and are listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old function @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Priority string "NORMAL" has been modified
|
|
Packit |
549fdc |
@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"
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_client_set_retrieve_function},
|
|
Packit |
549fdc |
@funcintref{gnutls_certificate_server_set_retrieve_function}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_certificate_set_retrieve_function}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_set_rsa_export_params},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_export_get_modulus_bits},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_export_get_pubkey},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_cpy},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_deinit},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_export_pkcs1},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_export_raw},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_generate2},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_import_pkcs1},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_import_raw},
|
|
Packit |
549fdc |
@funcintref{gnutls_rsa_params_init}
|
|
Packit |
549fdc |
@tab No replacement; the library does not support the RSA-EXPORT ciphersuites.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_pubkey_verify_hash},
|
|
Packit |
549fdc |
@tab @funcref{gnutls_pubkey_verify_hash2}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_pubkey_verify_data},
|
|
Packit |
549fdc |
@tab @funcref{gnutls_pubkey_verify_data2}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_x509_crt_get_verify_algorithm},
|
|
Packit |
549fdc |
@tab No replacement; a similar function is @funcref{gnutls_x509_crt_get_signature_algorithm}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_pubkey_get_verify_algorithm},
|
|
Packit |
549fdc |
@tab No replacement; a similar function is @funcref{gnutls_pubkey_get_preferred_hash_algorithm}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_certificate_type_set_priority},
|
|
Packit |
549fdc |
@funcintref{gnutls_cipher_set_priority},
|
|
Packit |
549fdc |
@funcintref{gnutls_compression_set_priority},
|
|
Packit |
549fdc |
@funcintref{gnutls_kx_set_priority},
|
|
Packit |
549fdc |
@funcintref{gnutls_mac_set_priority},
|
|
Packit |
549fdc |
@funcintref{gnutls_protocol_set_priority}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_priority_set_direct}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_sign_callback_get},
|
|
Packit |
549fdc |
@funcintref{gnutls_sign_callback_set}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_privkey_import_ext3}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_x509_crt_verify_hash}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_pubkey_verify_hash2}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_x509_crt_verify_data}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_pubkey_verify_data2}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcintref{gnutls_privkey_sign_raw_data}
|
|
Packit |
549fdc |
@tab @funcref{gnutls_privkey_sign_hash} with the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@heading Upgrading to 3.6.x from 3.5.x
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
GnuTLS 3.6.x is source and binary compatible with GnuTLS 3.5.x releases;
|
|
Packit |
549fdc |
however, there are minor differences, listed below.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@multitable @columnfractions .30 .60
|
|
Packit |
549fdc |
@headitem Old functionality @tab Replacement
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item The priority strings "+COMP" are a no-op
|
|
Packit |
549fdc |
@tab TLS compression is no longer available.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item The hash function SHA2-224 is a no-op for TLS1.2
|
|
Packit |
549fdc |
@tab TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash
|
|
Packit |
549fdc |
algorithm. As such it was removed for simplicity.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item The SRP key exchange accepted parameters outside the @xcite{TLSSRP} spec
|
|
Packit |
549fdc |
@tab The SRP key exchange is restricted to @xcite{TLSSRP} spec parameters
|
|
Packit |
549fdc |
to protect clients from MitM attacks.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item The compression-related functions are deprecated
|
|
Packit |
549fdc |
@tab No longer use @funcintref{gnutls_compression_get},
|
|
Packit |
549fdc |
@funcintref{gnutls_compression_get_name}, @funcintref{gnutls_compression_list},
|
|
Packit |
549fdc |
and @funcintref{gnutls_compression_get_id}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item @funcref{gnutls_x509_crt_sign}, @funcref{gnutls_x509_crl_sign}, @funcref{gnutls_x509_crq_sign}
|
|
Packit |
549fdc |
@tab These signing functions will no longer sign using SHA1, but with a secure hash algorithm.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|