1@node Upgrading from previous versions 2@appendix Upgrading from previous versions 3@cindex upgrading 4 5The GnuTLS library typically maintains binary and source code compatibility 6across versions. The releases that have the major version increased 7break binary compatibility but source compatibility is provided. 8This section lists exceptional cases where changes to existing code are 9required due to library changes. 10 11@heading Upgrading to 2.12.x from previous versions 12 13GnuTLS 2.12.x is binary compatible with previous versions but changes the 14semantics of @funcintref{gnutls_transport_set_lowat}, which might cause breakage 15in applications that relied on its default value be 1. Two fixes 16are proposed: 17@itemize 18@item Quick fix. Explicitly call @code{gnutls_transport_set_lowat (session, 1);} 19after @funcref{gnutls_init}. 20@item Long term fix. Because later versions of gnutls abolish the functionality 21of using the system call @funcintref{select} to check for gnutls pending data, the 22function @funcref{gnutls_record_check_pending} has to be used to achieve the same 23functionality as described in @ref{Asynchronous operation}. 24@end itemize 25 26@heading Upgrading to 3.0.x from 2.12.x 27 28GnuTLS 3.0.x is source compatible with previous versions except for the functions 29listed below. 30 31@multitable @columnfractions .30 .60 32@headitem Old function @tab Replacement 33 34@item @funcintref{gnutls_transport_set_lowat} @tab 35To replace its functionality the function @funcref{gnutls_record_check_pending} has to be used, 36as described in @ref{Asynchronous operation} 37 38@item @funcintref{gnutls_session_get_server_random}, 39@funcintref{gnutls_session_get_client_random} 40@tab 41They are replaced by the safer function @funcref{gnutls_session_get_random} 42 43@item @funcintref{gnutls_session_get_master_secret} 44@tab Replaced by the keying material exporters discussed in @ref{Deriving keys for other applications/protocols} 45 46@item @funcintref{gnutls_transport_set_global_errno} 47@tab Replaced by using the system's errno facility or @funcref{gnutls_transport_set_errno}. 48 49@item @funcintref{gnutls_x509_privkey_verify_data} 50@tab Replaced by @funcref{gnutls_pubkey_verify_data2}. 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 75@heading Upgrading to 3.1.x from 3.0.x 76 77GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few 78functions have been deprecated and are listed below. 79 80@multitable @columnfractions .30 .60 81@headitem Old function @tab Replacement 82 83@item @funcintref{gnutls_pubkey_verify_hash} 84@tab The function @funcref{gnutls_pubkey_verify_hash2} is provided and 85is functionally equivalent and safer to use. 86 87@item @funcintref{gnutls_pubkey_verify_data} 88@tab The function @funcref{gnutls_pubkey_verify_data2} is provided and 89is functionally equivalent and safer to use. 90 91@end multitable 92 93@heading Upgrading to 3.2.x from 3.1.x 94 95GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few 96functions have been deprecated and are listed below. 97 98@multitable @columnfractions .30 .60 99@headitem Old function @tab Replacement 100 101@item @funcintref{gnutls_privkey_sign_raw_data} 102@tab The function @funcref{gnutls_privkey_sign_hash} is equivalent 103when the flag @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} is specified. 104 105@end multitable 106 107@heading Upgrading to 3.3.x from 3.2.x 108 109GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases; 110however there few changes in semantics which are listed below. 111 112@multitable @columnfractions .30 .60 113@headitem Old function @tab Replacement 114 115@item @funcintref{gnutls_global_init} 116@tab No longer required. The library is initialized using a constructor. 117 118@item @funcintref{gnutls_global_deinit} 119@tab No longer required. The library is deinitialized using a destructor. 120 121@end multitable 122 123@heading Upgrading to 3.4.x from 3.3.x 124 125GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases; 126however, several deprecated functions were removed, and are listed below. 127 128@multitable @columnfractions .30 .60 129@headitem Old function @tab Replacement 130 131@item Priority string "NORMAL" has been modified 132@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" 133 134@item @funcintref{gnutls_certificate_client_set_retrieve_function}, 135@funcintref{gnutls_certificate_server_set_retrieve_function} 136@tab @funcref{gnutls_certificate_set_retrieve_function} 137 138@item @funcintref{gnutls_certificate_set_rsa_export_params}, 139@funcintref{gnutls_rsa_export_get_modulus_bits}, 140@funcintref{gnutls_rsa_export_get_pubkey}, 141@funcintref{gnutls_rsa_params_cpy}, 142@funcintref{gnutls_rsa_params_deinit}, 143@funcintref{gnutls_rsa_params_export_pkcs1}, 144@funcintref{gnutls_rsa_params_export_raw}, 145@funcintref{gnutls_rsa_params_generate2}, 146@funcintref{gnutls_rsa_params_import_pkcs1}, 147@funcintref{gnutls_rsa_params_import_raw}, 148@funcintref{gnutls_rsa_params_init} 149@tab No replacement; the library does not support the RSA-EXPORT ciphersuites. 150 151@item @funcintref{gnutls_pubkey_verify_hash}, 152@tab @funcref{gnutls_pubkey_verify_hash2}. 153 154@item @funcintref{gnutls_pubkey_verify_data}, 155@tab @funcref{gnutls_pubkey_verify_data2}. 156 157@item @funcintref{gnutls_x509_crt_get_verify_algorithm}, 158@tab No replacement; a similar function is @funcref{gnutls_x509_crt_get_signature_algorithm}. 159 160@item @funcintref{gnutls_pubkey_get_verify_algorithm}, 161@tab No replacement; a similar function is @funcref{gnutls_pubkey_get_preferred_hash_algorithm}. 162 163@item @funcintref{gnutls_certificate_type_set_priority}, 164@funcintref{gnutls_cipher_set_priority}, 165@funcintref{gnutls_compression_set_priority}, 166@funcintref{gnutls_kx_set_priority}, 167@funcintref{gnutls_mac_set_priority}, 168@funcintref{gnutls_protocol_set_priority} 169@tab @funcref{gnutls_priority_set_direct}. 170 171@item @funcintref{gnutls_sign_callback_get}, 172@funcintref{gnutls_sign_callback_set} 173@tab @funcref{gnutls_privkey_import_ext3} 174 175@item @funcintref{gnutls_x509_crt_verify_hash} 176@tab @funcref{gnutls_pubkey_verify_hash2} 177 178@item @funcintref{gnutls_x509_crt_verify_data} 179@tab @funcref{gnutls_pubkey_verify_data2} 180 181@item @funcintref{gnutls_privkey_sign_raw_data} 182@tab @funcref{gnutls_privkey_sign_hash} with the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA 183 184@end multitable 185 186@heading Upgrading to 3.6.x from 3.5.x 187 188GnuTLS 3.6.x is source and binary compatible with GnuTLS 3.5.x releases; 189however, there are minor differences, listed below. 190 191@multitable @columnfractions .30 .60 192@headitem Old functionality @tab Replacement 193 194@item The priority strings "+COMP" are a no-op 195@tab TLS compression is no longer available. 196 197@item The SSL 3.0 protocol is a no-op 198@tab SSL 3.0 is no longer compiled in by default. It is a legacy protocol 199which is completely eliminated from public internet. As such it was removed 200to reduce the attack vector for applications using the library. 201 202@item The hash function SHA2-224 is a no-op for TLS1.2 203@tab TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash 204algorithm. As such it was removed for simplicity. 205 206@item The SRP key exchange accepted parameters outside the @xcite{TLSSRP} spec 207@tab The SRP key exchange is restricted to @xcite{TLSSRP} spec parameters 208to protect clients from MitM attacks. 209 210@item The compression-related functions are deprecated 211@tab No longer use @funcintref{gnutls_compression_get}, 212@funcintref{gnutls_compression_get_name}, @funcintref{gnutls_compression_list}, 213and @funcintref{gnutls_compression_get_id}. 214 215@item @funcref{gnutls_x509_crt_sign}, @funcref{gnutls_x509_crl_sign}, @funcref{gnutls_x509_crq_sign} 216@tab These signing functions will no longer sign using SHA1, but with a secure hash algorithm. 217 218@item @funcref{gnutls_certificate_set_ocsp_status_request_file} 219@tab This function will return an error if the loaded response doesn't match 220any of the present certificates. To revert to previous semantics set the @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} 221flag using @funcref{gnutls_certificate_set_flags}. 222 223@item The callback @funcref{gnutls_privkey_import_ext3} is not flexible enough for new signature algorithms such as RSA-PSS 224@tab It is replaced with @funcref{gnutls_privkey_import_ext4} 225 226@item Re-handshake functionality is not applicable under TLS 1.3. 227@tab It is replaced by separate key update and re-authentication functionality 228which can be accessed directly via @funcref{gnutls_session_key_update} and @funcref{gnutls_reauth}. 229 230@item TLS session identifiers are not shared with the server under TLS 1.3. 231@tab The TLS session identifiers are persistent across resumption only on 232server side and can be obtained as before via @funcref{gnutls_session_get_id2}. 233 234@item @funcref{gnutls_pkcs11_privkey_generate3}, @funcref{gnutls_pkcs11_copy_secret_key}, @funcref{gnutls_pkcs11_copy_x509_privkey2} 235@tab These functions no longer create an exportable key by default; they require the flag @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} to do so. 236 237@item @funcref{gnutls_db_set_retrieve_function}, @funcref{gnutls_db_set_store_function}, @funcref{gnutls_db_set_remove_function} 238@tab These functions are no longer relevant under TLS 1.3; resumption under 239TLS 1.3 is done via session tickets, c.f. @funcref{gnutls_session_ticket_enable_server}. 240 241@item @funcref{gnutls_session_get_data2}, @funcref{gnutls_session_get_data} 242@tab These functions may introduce a slight delay under TLS 1.3 for few 243milliseconds. Check output of @funcref{gnutls_session_get_flags} for GNUTLS_SFLAGS_SESSION_TICKET 244before calling this function to avoid delays. To work efficiently under 245TLS 1.3 this function requires the application setting 246@funcref{gnutls_transport_set_pull_timeout_function}. 247 248@item SRP and RSA-PSK key exchanges are not supported under TLS 1.3 249@tab 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. 250 251@item Anonymous key exchange is not supported under TLS 1.3 252@tab 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. 253 254@item ECDHE-PSK and DHE-PSK keywords have the same meaning under TLS 1.3 255@tab In the priority strings, both @code{ECDHE@-PSK} and @code{DHE@-PSK} 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. 256 257@item Authentication-only ciphersuites are not supported under TLS 1.3 258@tab Ciphersuites with the @code{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. 259 260@item Supplemental data is not supported under TLS 1.3 261@tab The TLS supplemental data handshake message (RFC 4680) is not supported under TLS 1.3, so if the application calls @funcref{gnutls_supplemental_register} or @funcref{gnutls_session_supplemental_register}, TLS 1.3 is disabled. 262 263@item The GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION macro is a no-op 264@tab The macro was non-functional and because of the nature of the 265definition of the no-well-defined date for certificates (a real date), 266it will not be fixed or re-introduced. 267 268@end multitable 269