diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/cha-upgrade.texi | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/doc/cha-upgrade.texi b/doc/cha-upgrade.texi new file mode 100644 index 0000000..91c6803 --- /dev/null +++ b/doc/cha-upgrade.texi @@ -0,0 +1,268 @@ +@node Upgrading from previous versions +@appendix Upgrading from previous versions +@cindex upgrading + +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. + +@heading Upgrading to 2.12.x from previous versions + +GnuTLS 2.12.x is binary compatible with previous versions but changes the +semantics of @funcintref{gnutls_transport_set_lowat}, which might cause breakage +in applications that relied on its default value be 1. Two fixes +are proposed: +@itemize +@item Quick fix. Explicitly call @code{gnutls_transport_set_lowat (session, 1);} +after @funcref{gnutls_init}. +@item Long term fix. Because later versions of gnutls abolish the functionality +of using the system call @funcintref{select} to check for gnutls pending data, the +function @funcref{gnutls_record_check_pending} has to be used to achieve the same +functionality as described in @ref{Asynchronous operation}. +@end itemize + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old function @tab Replacement + +@item @funcintref{gnutls_transport_set_lowat} @tab +To replace its functionality the function @funcref{gnutls_record_check_pending} has to be used, +as described in @ref{Asynchronous operation} + +@item @funcintref{gnutls_session_get_server_random}, +@funcintref{gnutls_session_get_client_random} +@tab +They are replaced by the safer function @funcref{gnutls_session_get_random} + +@item @funcintref{gnutls_session_get_master_secret} +@tab Replaced by the keying material exporters discussed in @ref{Deriving keys for other applications/protocols} + +@item @funcintref{gnutls_transport_set_global_errno} +@tab Replaced by using the system's errno facility or @funcref{gnutls_transport_set_errno}. + +@item @funcintref{gnutls_x509_privkey_verify_data} +@tab Replaced by @funcref{gnutls_pubkey_verify_data2}. + +@item @funcintref{gnutls_certificate_verify_peers} +@tab Replaced by @funcref{gnutls_certificate_verify_peers2}. + +@item @funcintref{gnutls_psk_netconf_derive_key} +@tab Removed. The key derivation function was never standardized. + +@item @funcintref{gnutls_session_set_finished_function} +@tab Removed. + +@item @funcintref{gnutls_ext_register} +@tab Removed. Extension registration API is now internal to allow easier changes in the API. + +@item @funcintref{gnutls_certificate_get_x509_crls}, @funcintref{gnutls_certificate_get_x509_cas} +@tab Removed to allow updating the internal structures. Replaced by @funcref{gnutls_certificate_get_issuer}. + +@item @funcintref{gnutls_certificate_get_openpgp_keyring} +@tab Removed. + +@item @funcintref{gnutls_ia_} +@tab Removed. The inner application extensions were completely removed (they failed to be standardized). + +@end multitable + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old function @tab Replacement + +@item @funcintref{gnutls_pubkey_verify_hash} +@tab The function @funcref{gnutls_pubkey_verify_hash2} is provided and +is functionally equivalent and safer to use. + +@item @funcintref{gnutls_pubkey_verify_data} +@tab The function @funcref{gnutls_pubkey_verify_data2} is provided and +is functionally equivalent and safer to use. + +@end multitable + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old function @tab Replacement + +@item @funcintref{gnutls_privkey_sign_raw_data} +@tab The function @funcref{gnutls_privkey_sign_hash} is equivalent +when the flag @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} is specified. + +@end multitable + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old function @tab Replacement + +@item @funcintref{gnutls_global_init} +@tab No longer required. The library is initialized using a constructor. + +@item @funcintref{gnutls_global_deinit} +@tab No longer required. The library is deinitialized using a destructor. + +@end multitable + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old function @tab Replacement + +@item Priority string "NORMAL" has been modified +@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" + +@item @funcintref{gnutls_certificate_client_set_retrieve_function}, +@funcintref{gnutls_certificate_server_set_retrieve_function} +@tab @funcref{gnutls_certificate_set_retrieve_function} + +@item @funcintref{gnutls_certificate_set_rsa_export_params}, +@funcintref{gnutls_rsa_export_get_modulus_bits}, +@funcintref{gnutls_rsa_export_get_pubkey}, +@funcintref{gnutls_rsa_params_cpy}, +@funcintref{gnutls_rsa_params_deinit}, +@funcintref{gnutls_rsa_params_export_pkcs1}, +@funcintref{gnutls_rsa_params_export_raw}, +@funcintref{gnutls_rsa_params_generate2}, +@funcintref{gnutls_rsa_params_import_pkcs1}, +@funcintref{gnutls_rsa_params_import_raw}, +@funcintref{gnutls_rsa_params_init} +@tab No replacement; the library does not support the RSA-EXPORT ciphersuites. + +@item @funcintref{gnutls_pubkey_verify_hash}, +@tab @funcref{gnutls_pubkey_verify_hash2}. + +@item @funcintref{gnutls_pubkey_verify_data}, +@tab @funcref{gnutls_pubkey_verify_data2}. + +@item @funcintref{gnutls_x509_crt_get_verify_algorithm}, +@tab No replacement; a similar function is @funcref{gnutls_x509_crt_get_signature_algorithm}. + +@item @funcintref{gnutls_pubkey_get_verify_algorithm}, +@tab No replacement; a similar function is @funcref{gnutls_pubkey_get_preferred_hash_algorithm}. + +@item @funcintref{gnutls_certificate_type_set_priority}, +@funcintref{gnutls_cipher_set_priority}, +@funcintref{gnutls_compression_set_priority}, +@funcintref{gnutls_kx_set_priority}, +@funcintref{gnutls_mac_set_priority}, +@funcintref{gnutls_protocol_set_priority} +@tab @funcref{gnutls_priority_set_direct}. + +@item @funcintref{gnutls_sign_callback_get}, +@funcintref{gnutls_sign_callback_set} +@tab @funcref{gnutls_privkey_import_ext3} + +@item @funcintref{gnutls_x509_crt_verify_hash} +@tab @funcref{gnutls_pubkey_verify_hash2} + +@item @funcintref{gnutls_x509_crt_verify_data} +@tab @funcref{gnutls_pubkey_verify_data2} + +@item @funcintref{gnutls_privkey_sign_raw_data} +@tab @funcref{gnutls_privkey_sign_hash} with the flag GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA + +@end multitable + +@heading 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. + +@multitable @columnfractions .30 .60 +@headitem Old functionality @tab Replacement + +@item The priority strings "+COMP" are a no-op +@tab TLS compression is no longer available. + +@item The SSL 3.0 protocol is a no-op +@tab 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. + +@item The hash function SHA2-224 is a no-op for TLS1.2 +@tab TLS 1.3 no longer uses SHA2-224, and it was never a widespread hash +algorithm. As such it was removed for simplicity. + +@item The SRP key exchange accepted parameters outside the @xcite{TLSSRP} spec +@tab The SRP key exchange is restricted to @xcite{TLSSRP} spec parameters +to protect clients from MitM attacks. + +@item The compression-related functions are deprecated +@tab No longer use @funcintref{gnutls_compression_get}, +@funcintref{gnutls_compression_get_name}, @funcintref{gnutls_compression_list}, +and @funcintref{gnutls_compression_get_id}. + +@item @funcref{gnutls_x509_crt_sign}, @funcref{gnutls_x509_crl_sign}, @funcref{gnutls_x509_crq_sign} +@tab These signing functions will no longer sign using SHA1, but with a secure hash algorithm. + +@item @funcref{gnutls_certificate_set_ocsp_status_request_file} +@tab 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 @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} +flag using @funcref{gnutls_certificate_set_flags}. + +@item The callback @funcref{gnutls_privkey_import_ext3} is not flexible enough for new signature algorithms such as RSA-PSS +@tab It is replaced with @funcref{gnutls_privkey_import_ext4} + +@item Re-handshake functionality is not applicable under TLS 1.3. +@tab It is replaced by separate key update and re-authentication functionality +which can be accessed directly via @funcref{gnutls_session_key_update} and @funcref{gnutls_reauth}. + +@item TLS session identifiers are not shared with the server under TLS 1.3. +@tab The TLS session identifiers are persistent across resumption only on +server side and can be obtained as before via @funcref{gnutls_session_get_id2}. + +@item @funcref{gnutls_pkcs11_privkey_generate3}, @funcref{gnutls_pkcs11_copy_secret_key}, @funcref{gnutls_pkcs11_copy_x509_privkey2} +@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. + +@item @funcref{gnutls_db_set_retrieve_function}, @funcref{gnutls_db_set_store_function}, @funcref{gnutls_db_set_remove_function} +@tab These functions are no longer relevant under TLS 1.3; resumption under +TLS 1.3 is done via session tickets, c.f. @funcref{gnutls_session_ticket_enable_server}. + +@item @funcref{gnutls_session_get_data2}, @funcref{gnutls_session_get_data} +@tab These functions may introduce a slight delay under TLS 1.3 for few +milliseconds. Check output of @funcref{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 +@funcref{gnutls_transport_set_pull_timeout_function}. + +@item SRP and RSA-PSK key exchanges are not supported under TLS 1.3 +@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. + +@item Anonymous key exchange is not supported under TLS 1.3 +@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. + +@item ECDHE-PSK and DHE-PSK keywords have the same meaning under TLS 1.3 +@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. + +@item Authentication-only ciphersuites are not supported under TLS 1.3 +@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. + +@item Supplemental data is not supported under TLS 1.3 +@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. + +@item The GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION macro is a no-op +@tab 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. + +@end multitable |