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:

  * Quick fix. Explicitly call gnutls_transport_set_lowat (session, 1); after gnutls_init.

  * Long term fix. Because later versions of gnutls abolish the functionality of using the system call select to check for gnutls pending data, the function gnutls_record_check_pending has to be used to achieve the same functionality as described in Asynchronous operation.

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 function   Replacement

gnutls_transport_set_lowat
To 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_random

They are replaced by the safer function gnutls_session_get_random

gnutls_session_get_master_secret
Replaced by the keying material exporters discussed in Deriving keys for other applications/protocols

gnutls_transport_set_global_errno
Replaced by using the system's errno facility or gnutls_transport_set_errno.

gnutls_x509_privkey_verify_data
Replaced by gnutls_pubkey_verify_data2.

gnutls_certificate_verify_peers
Replaced by gnutls_certificate_verify_peers2.

gnutls_psk_netconf_derive_key
Removed. The key derivation function was never standardized.

gnutls_session_set_finished_function
Removed.

gnutls_ext_register
Removed. Extension registration API is now internal to allow easier changes in the API.

gnutls_certificate_get_x509_crls, gnutls_certificate_get_x509_cas
Removed to allow updating the internal structures. Replaced by gnutls_certificate_get_issuer.

gnutls_certificate_get_openpgp_keyring
Removed.

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 function   Replacement

gnutls_pubkey_verify_hash
The function gnutls_pubkey_verify_hash2 is provided and
is functionally equivalent and safer to use.

gnutls_pubkey_verify_data
The 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 function   Replacement

gnutls_privkey_sign_raw_data
The 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 function   Replacement

gnutls_global_init
No longer required. The library is initialized using a constructor.

gnutls_global_deinit
No 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 function   Replacement

Priority string "NORMAL" has been modified
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"

gnutls_certificate_client_set_retrieve_function,
gnutls_certificate_server_set_retrieve_function
gnutls_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_init
No 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_priority
gnutls_priority_set_direct.

gnutls_sign_callback_get,
gnutls_sign_callback_set
gnutls_privkey_import_ext3

gnutls_x509_crt_verify_hash
gnutls_pubkey_verify_hash2

gnutls_x509_crt_verify_data
gnutls_pubkey_verify_data2

gnutls_privkey_sign_raw_data
gnutls_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 functionality   Replacement

The priority strings "+COMP" are a no-op
TLS compression is no longer available.

The hash function SHA2-224 is a no-op for TLS1.2
TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash
algorithm. As such it was removed for simplicity.

The compression-related functions are deprecated
No 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_sign
These signing functions will no longer sign using SHA1, but with a secure hash algorithm.