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