|
Packit Service |
4684c1 |
@node Upgrading from previous versions
|
|
Packit Service |
4684c1 |
@appendix Upgrading from previous versions
|
|
Packit Service |
4684c1 |
@cindex upgrading
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The GnuTLS library typically maintains binary and source code compatibility
|
|
Packit Service |
4684c1 |
across versions. The releases that have the major version increased
|
|
Packit Service |
4684c1 |
break binary compatibility but source compatibility is provided.
|
|
Packit Service |
4684c1 |
This section lists exceptional cases where changes to existing code are
|
|
Packit Service |
4684c1 |
required due to library changes.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 2.12.x from previous versions
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 2.12.x is binary compatible with previous versions but changes the
|
|
Packit Service |
4684c1 |
semantics of @funcintref{gnutls_transport_set_lowat}, which might cause breakage
|
|
Packit Service |
4684c1 |
in applications that relied on its default value be 1. Two fixes
|
|
Packit Service |
4684c1 |
are proposed:
|
|
Packit Service |
4684c1 |
@itemize
|
|
Packit Service |
4684c1 |
@item Quick fix. Explicitly call @code{gnutls_transport_set_lowat (session, 1);}
|
|
Packit Service |
4684c1 |
after @funcref{gnutls_init}.
|
|
Packit Service |
4684c1 |
@item Long term fix. Because later versions of gnutls abolish the functionality
|
|
Packit Service |
4684c1 |
of using the system call @funcintref{select} to check for gnutls pending data, the
|
|
Packit Service |
4684c1 |
function @funcref{gnutls_record_check_pending} has to be used to achieve the same
|
|
Packit Service |
4684c1 |
functionality as described in @ref{Asynchronous operation}.
|
|
Packit Service |
4684c1 |
@end itemize
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.0.x from 2.12.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.0.x is source compatible with previous versions except for the functions
|
|
Packit Service |
4684c1 |
listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old function @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_transport_set_lowat} @tab
|
|
Packit Service |
4684c1 |
To replace its functionality the function @funcref{gnutls_record_check_pending} has to be used,
|
|
Packit Service |
4684c1 |
as described in @ref{Asynchronous operation}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_session_get_server_random},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_session_get_client_random}
|
|
Packit Service |
4684c1 |
@tab
|
|
Packit Service |
4684c1 |
They are replaced by the safer function @funcref{gnutls_session_get_random}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_session_get_master_secret}
|
|
Packit Service |
4684c1 |
@tab Replaced by the keying material exporters discussed in @ref{Deriving keys for other applications/protocols}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_transport_set_global_errno}
|
|
Packit Service |
4684c1 |
@tab Replaced by using the system's errno facility or @funcref{gnutls_transport_set_errno}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_x509_privkey_verify_data}
|
|
Packit Service |
4684c1 |
@tab Replaced by @funcref{gnutls_pubkey_verify_data2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_verify_peers}
|
|
Packit Service |
4684c1 |
@tab Replaced by @funcref{gnutls_certificate_verify_peers2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_psk_netconf_derive_key}
|
|
Packit Service |
4684c1 |
@tab Removed. The key derivation function was never standardized.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_session_set_finished_function}
|
|
Packit Service |
4684c1 |
@tab Removed.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_ext_register}
|
|
Packit Service |
4684c1 |
@tab Removed. Extension registration API is now internal to allow easier changes in the API.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_get_x509_crls}, @funcintref{gnutls_certificate_get_x509_cas}
|
|
Packit Service |
4684c1 |
@tab Removed to allow updating the internal structures. Replaced by @funcref{gnutls_certificate_get_issuer}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_get_openpgp_keyring}
|
|
Packit Service |
4684c1 |
@tab Removed.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_ia_}
|
|
Packit Service |
4684c1 |
@tab Removed. The inner application extensions were completely removed (they failed to be standardized).
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.1.x from 3.0.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few
|
|
Packit Service |
4684c1 |
functions have been deprecated and are listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old function @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_pubkey_verify_hash}
|
|
Packit Service |
4684c1 |
@tab The function @funcref{gnutls_pubkey_verify_hash2} is provided and
|
|
Packit Service |
4684c1 |
is functionally equivalent and safer to use.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_pubkey_verify_data}
|
|
Packit Service |
4684c1 |
@tab The function @funcref{gnutls_pubkey_verify_data2} is provided and
|
|
Packit Service |
4684c1 |
is functionally equivalent and safer to use.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.2.x from 3.1.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few
|
|
Packit Service |
4684c1 |
functions have been deprecated and are listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old function @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_privkey_sign_raw_data}
|
|
Packit Service |
4684c1 |
@tab The function @funcref{gnutls_privkey_sign_hash} is equivalent
|
|
Packit Service |
4684c1 |
when the flag @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} is specified.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.3.x from 3.2.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases;
|
|
Packit Service |
4684c1 |
however there few changes in semantics which are listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old function @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_global_init}
|
|
Packit Service |
4684c1 |
@tab No longer required. The library is initialized using a constructor.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_global_deinit}
|
|
Packit Service |
4684c1 |
@tab No longer required. The library is deinitialized using a destructor.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.4.x from 3.3.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.4.x is source compatible with GnuTLS 3.3.x releases;
|
|
Packit Service |
4684c1 |
however, several deprecated functions were removed, and are listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old function @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Priority string "NORMAL" has been modified
|
|
Packit Service |
4684c1 |
@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 Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_client_set_retrieve_function},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_certificate_server_set_retrieve_function}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_certificate_set_retrieve_function}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_set_rsa_export_params},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_export_get_modulus_bits},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_export_get_pubkey},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_cpy},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_deinit},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_export_pkcs1},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_export_raw},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_generate2},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_import_pkcs1},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_import_raw},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_rsa_params_init}
|
|
Packit Service |
4684c1 |
@tab No replacement; the library does not support the RSA-EXPORT ciphersuites.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_pubkey_verify_hash},
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_pubkey_verify_hash2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_pubkey_verify_data},
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_pubkey_verify_data2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_x509_crt_get_verify_algorithm},
|
|
Packit Service |
4684c1 |
@tab No replacement; a similar function is @funcref{gnutls_x509_crt_get_signature_algorithm}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_pubkey_get_verify_algorithm},
|
|
Packit Service |
4684c1 |
@tab No replacement; a similar function is @funcref{gnutls_pubkey_get_preferred_hash_algorithm}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_certificate_type_set_priority},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_cipher_set_priority},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_compression_set_priority},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_kx_set_priority},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_mac_set_priority},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_protocol_set_priority}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_priority_set_direct}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_sign_callback_get},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_sign_callback_set}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_privkey_import_ext3}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_x509_crt_verify_hash}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_pubkey_verify_hash2}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_x509_crt_verify_data}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_pubkey_verify_data2}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcintref{gnutls_privkey_sign_raw_data}
|
|
Packit Service |
4684c1 |
@tab @funcref{gnutls_privkey_sign_hash} with the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@heading Upgrading to 3.6.x from 3.5.x
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS 3.6.x is source and binary compatible with GnuTLS 3.5.x releases;
|
|
Packit Service |
4684c1 |
however, there are minor differences, listed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .30 .60
|
|
Packit Service |
4684c1 |
@headitem Old functionality @tab Replacement
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The priority strings "+COMP" are a no-op
|
|
Packit Service |
4684c1 |
@tab TLS compression is no longer available.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The SSL 3.0 protocol is a no-op
|
|
Packit Service |
4684c1 |
@tab SSL 3.0 is no longer compiled in by default. It is a legacy protocol
|
|
Packit Service |
4684c1 |
which is completely eliminated from public internet. As such it was removed
|
|
Packit Service |
4684c1 |
to reduce the attack vector for applications using the library.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The hash function SHA2-224 is a no-op for TLS1.2
|
|
Packit Service |
4684c1 |
@tab TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash
|
|
Packit Service |
4684c1 |
algorithm. As such it was removed for simplicity.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The SRP key exchange accepted parameters outside the @xcite{TLSSRP} spec
|
|
Packit Service |
4684c1 |
@tab The SRP key exchange is restricted to @xcite{TLSSRP} spec parameters
|
|
Packit Service |
4684c1 |
to protect clients from MitM attacks.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The compression-related functions are deprecated
|
|
Packit Service |
4684c1 |
@tab No longer use @funcintref{gnutls_compression_get},
|
|
Packit Service |
4684c1 |
@funcintref{gnutls_compression_get_name}, @funcintref{gnutls_compression_list},
|
|
Packit Service |
4684c1 |
and @funcintref{gnutls_compression_get_id}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcref{gnutls_x509_crt_sign}, @funcref{gnutls_x509_crl_sign}, @funcref{gnutls_x509_crq_sign}
|
|
Packit Service |
4684c1 |
@tab These signing functions will no longer sign using SHA1, but with a secure hash algorithm.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcref{gnutls_certificate_set_ocsp_status_request_file}
|
|
Packit Service |
4684c1 |
@tab This function will return an error if the loaded response doesn't match
|
|
Packit Service |
4684c1 |
any of the present certificates. To revert to previous semantics set the @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK}
|
|
Packit Service |
4684c1 |
flag using @funcref{gnutls_certificate_set_flags}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The callback @funcref{gnutls_privkey_import_ext3} is not flexible enough for new signature algorithms such as RSA-PSS
|
|
Packit Service |
4684c1 |
@tab It is replaced with @funcref{gnutls_privkey_import_ext4}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Re-handshake functionality is not applicable under TLS 1.3.
|
|
Packit Service |
4684c1 |
@tab It is replaced by separate key update and re-authentication functionality
|
|
Packit Service |
4684c1 |
which can be accessed directly via @funcref{gnutls_session_key_update} and @funcref{gnutls_reauth}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item TLS session identifiers are not shared with the server under TLS 1.3.
|
|
Packit Service |
4684c1 |
@tab The TLS session identifiers are persistent across resumption only on
|
|
Packit Service |
4684c1 |
server side and can be obtained as before via @funcref{gnutls_session_get_id2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcref{gnutls_pkcs11_privkey_generate3}, @funcref{gnutls_pkcs11_copy_secret_key}, @funcref{gnutls_pkcs11_copy_x509_privkey2}
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcref{gnutls_db_set_retrieve_function}, @funcref{gnutls_db_set_store_function}, @funcref{gnutls_db_set_remove_function}
|
|
Packit Service |
4684c1 |
@tab These functions are no longer relevant under TLS 1.3; resumption under
|
|
Packit Service |
4684c1 |
TLS 1.3 is done via session tickets, c.f. @funcref{gnutls_session_ticket_enable_server}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @funcref{gnutls_session_get_data2}, @funcref{gnutls_session_get_data}
|
|
Packit Service |
4684c1 |
@tab These functions may introduce a slight delay under TLS 1.3 for few
|
|
Packit Service |
4684c1 |
milliseconds. Check output of @funcref{gnutls_session_get_flags} for GNUTLS_SFLAGS_SESSION_TICKET
|
|
Packit Service |
4684c1 |
before calling this function to avoid delays. To work efficiently under
|
|
Packit Service |
4684c1 |
TLS 1.3 this function requires the application setting
|
|
Packit Service |
4684c1 |
@funcref{gnutls_transport_set_pull_timeout_function}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item SRP and RSA-PSK key exchanges are not supported under TLS 1.3
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Anonymous key exchange is not supported under TLS 1.3
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item ECDHE-PSK and DHE-PSK keywords have the same meaning under TLS 1.3
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Authentication-only ciphersuites are not supported under TLS 1.3
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Supplemental data is not supported under TLS 1.3
|
|
Packit Service |
4684c1 |
@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.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item The GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION macro is a no-op
|
|
Packit Service |
4684c1 |
@tab The macro was non-functional and because of the nature of the
|
|
Packit Service |
4684c1 |
definition of the no-well-defined date for certificates (a real date),
|
|
Packit Service |
4684c1 |
it will not be fixed or re-introduced.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|