Next: , Previous: , Up: Top   [Contents][Index]


Appendix A Upgrading from previous versions

The GnuTLS library typically maintains binary and source code compatibility across versions. The releases that have the major version increased break binary compatibility but source compatibility is provided. This section lists exceptional cases where changes to existing code are required due to library changes.

Upgrading to 2.12.x from previous versions

GnuTLS 2.12.x is binary compatible with previous versions but changes the semantics of gnutls_transport_set_lowat, which might cause breakage in applications that relied on its default value be 1. Two fixes are proposed:

Upgrading to 3.0.x from 2.12.x

GnuTLS 3.0.x is source compatible with previous versions except for the functions listed below.

Old functionReplacement
gnutls_transport_set_lowatTo replace its functionality the function gnutls_record_check_pending has to be used, as described in Asynchronous operation
gnutls_session_get_server_random, gnutls_session_get_client_randomThey are replaced by the safer function gnutls_session_get_random
gnutls_session_get_master_secretReplaced by the keying material exporters discussed in Deriving keys for other applications/protocols
gnutls_transport_set_global_errnoReplaced by using the system’s errno facility or gnutls_transport_set_errno.
gnutls_x509_privkey_verify_dataReplaced by gnutls_pubkey_verify_data2.
gnutls_certificate_verify_peersReplaced by gnutls_certificate_verify_peers2.
gnutls_psk_netconf_derive_keyRemoved. The key derivation function was never standardized.
gnutls_session_set_finished_functionRemoved.
gnutls_ext_registerRemoved. Extension registration API is now internal to allow easier changes in the API.
gnutls_certificate_get_x509_crls, gnutls_certificate_get_x509_casRemoved to allow updating the internal structures. Replaced by gnutls_certificate_get_issuer.
gnutls_certificate_get_openpgp_keyringRemoved.
gnutls_ia_Removed. The inner application extensions were completely removed (they failed to be standardized).

Upgrading to 3.1.x from 3.0.x

GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few functions have been deprecated and are listed below.

Old functionReplacement
gnutls_pubkey_verify_hashThe function gnutls_pubkey_verify_hash2 is provided and is functionally equivalent and safer to use.
gnutls_pubkey_verify_dataThe function gnutls_pubkey_verify_data2 is provided and is functionally equivalent and safer to use.

Upgrading to 3.2.x from 3.1.x

GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few functions have been deprecated and are listed below.

Old functionReplacement
gnutls_privkey_sign_raw_dataThe function gnutls_privkey_sign_hash is equivalent when the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA is specified.

Upgrading to 3.3.x from 3.2.x

GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases; however there few changes in semantics which are listed below.

Old functionReplacement
gnutls_global_initNo longer required. The library is initialized using a constructor.
gnutls_global_deinitNo longer required. The library is deinitialized using a destructor.

Upgrading to 3.4.x from 3.3.x

GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases; however, several deprecated functions were removed, and are listed below.

Old functionReplacement
Priority string "NORMAL" has been modifiedThe 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"
gnutls_certificate_client_set_retrieve_function, gnutls_certificate_server_set_retrieve_functiongnutls_certificate_set_retrieve_function
gnutls_certificate_set_rsa_export_params, gnutls_rsa_export_get_modulus_bits, gnutls_rsa_export_get_pubkey, gnutls_rsa_params_cpy, gnutls_rsa_params_deinit, gnutls_rsa_params_export_pkcs1, gnutls_rsa_params_export_raw, gnutls_rsa_params_generate2, gnutls_rsa_params_import_pkcs1, gnutls_rsa_params_import_raw, gnutls_rsa_params_initNo replacement; the library does not support the RSA-EXPORT ciphersuites.
gnutls_pubkey_verify_hash,gnutls_pubkey_verify_hash2.
gnutls_pubkey_verify_data,gnutls_pubkey_verify_data2.
gnutls_x509_crt_get_verify_algorithm,No replacement; a similar function is gnutls_x509_crt_get_signature_algorithm.
gnutls_pubkey_get_verify_algorithm,No replacement; a similar function is gnutls_pubkey_get_preferred_hash_algorithm.
gnutls_certificate_type_set_priority, gnutls_cipher_set_priority, gnutls_compression_set_priority, gnutls_kx_set_priority, gnutls_mac_set_priority, gnutls_protocol_set_prioritygnutls_priority_set_direct.
gnutls_sign_callback_get, gnutls_sign_callback_setgnutls_privkey_import_ext3
gnutls_x509_crt_verify_hashgnutls_pubkey_verify_hash2
gnutls_x509_crt_verify_datagnutls_pubkey_verify_data2
gnutls_privkey_sign_raw_datagnutls_privkey_sign_hash with the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA

Upgrading to 3.6.x from 3.5.x

GnuTLS 3.6.x is source and binary compatible with GnuTLS 3.5.x releases; however, there are minor differences, listed below.

Old functionalityReplacement
The priority strings "+COMP" are a no-opTLS compression is no longer available.
The hash function SHA2-224 is a no-op for TLS1.2TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash algorithm. As such it was removed for simplicity.
The SRP key exchange accepted parameters outside the [TLSSRP] specThe SRP key exchange is restricted to [TLSSRP] spec parameters to protect clients from MitM attacks.
The compression-related functions are deprecatedNo longer use gnutls_compression_get, gnutls_compression_get_name, gnutls_compression_list, and gnutls_compression_get_id.
gnutls_x509_crt_sign, gnutls_x509_crl_sign, gnutls_x509_crq_signThese signing functions will no longer sign using SHA1, but with a secure hash algorithm.
gnutls_certificate_set_ocsp_status_request_fileThis function will return an error if the loaded response doesn’t match any of the present certificates. To revert to previous semantics set the GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK flag using gnutls_certificate_set_flags.
The callback gnutls_privkey_import_ext3 is not flexible enough for new signature algorithms such as RSA-PSSIt is replaced with gnutls_privkey_import_ext4
Re-handshake functionality is not applicable under TLS 1.3.It is replaced by separate key update and re-authentication functionality which can be accessed directly via gnutls_session_key_update and gnutls_reauth.
gnutls_pkcs11_privkey_generate3, gnutls_pkcs11_copy_secret_key, gnutls_pkcs11_copy_x509_privkey2These functions no longer create an exportable key by default; they require the flag GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE to do so.

Next: , Previous: , Up: Top   [Contents][Index]