Upgrading from previous versions (GnuTLS 3.8.4)

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:

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 SSL 3.0 protocol is a no-op	SSL 3.0 is no longer compiled in by default. It is a legacy protocol which is completely eliminated from public internet. As such it was removed to reduce the attack vector for applications using the library.
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 SRP key exchange accepted parameters outside the [TLSSRP] spec	The SRP key exchange is restricted to [TLSSRP] spec parameters to protect clients from MitM attacks.
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.
gnutls_certificate_set_ocsp_status_request_file	This 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-PSS	It 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.
TLS session identifiers are not shared with the server under TLS 1.3.	The TLS session identifiers are persistent across resumption only on server side and can be obtained as before via gnutls_session_get_id2.
gnutls_pkcs11_privkey_generate3, gnutls_pkcs11_copy_secret_key, gnutls_pkcs11_copy_x509_privkey2	These functions no longer create an exportable key by default; they require the flag `GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE` to do so.
gnutls_db_set_retrieve_function, gnutls_db_set_store_function, gnutls_db_set_remove_function	These functions are no longer relevant under TLS 1.3; resumption under TLS 1.3 is done via session tickets, c.f. gnutls_session_ticket_enable_server.
gnutls_session_get_data2, gnutls_session_get_data	These functions may introduce a slight delay under TLS 1.3 for few milliseconds. Check output of gnutls_session_get_flags for GNUTLS_SFLAGS_SESSION_TICKET before calling this function to avoid delays. To work efficiently under TLS 1.3 this function requires the application setting gnutls_transport_set_pull_timeout_function.
SRP and RSA-PSK key exchanges are not supported under TLS 1.3	SRP and RSA-PSK key exchanges are not supported in TLS 1.3, so when these key exchanges are present in a priority string, TLS 1.3 is disabled.
Anonymous key exchange is not supported under TLS 1.3	There is no anonymous key exchange supported under TLS 1.3, so if an anonymous key exchange method is set in a priority string, and no certificate credentials are set in the client or server, TLS 1.3 will not be negotiated.
ECDHE-PSK and DHE-PSK keywords have the same meaning under TLS 1.3	In the priority strings, both `ECDHEPSK` and `DHEPSK` indicate the intent to support an ephemeral key exchange with the pre-shared key. The parameters of the key exchange are negotiated with the supported groups specified in the priority string.
Authentication-only ciphersuites are not supported under TLS 1.3	Ciphersuites with the `NULL` cipher (i.e., authentication-only) are not supported in TLS 1.3, so when they are specified in a priority string, TLS 1.3 is disabled.
Supplemental data is not supported under TLS 1.3	The TLS supplemental data handshake message (RFC 4680) is not supported under TLS 1.3, so if the application calls gnutls_supplemental_register or gnutls_session_supplemental_register, TLS 1.3 is disabled.
The GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION macro is a no-op	The macro was non-functional and because of the nature of the definition of the no-well-defined date for certificates (a real date), it will not be fixed or re-introduced.