Added discussion on compatibility issues.

diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index beb6fb0575c01c857cae7f69d83d5ba336766416..78b6f905753c54c03ef9dc4cf256c93fb265ab59 100644 (file)
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -635,6 +635,31 @@ It might also be useful to be able to check for expired sessions in
 order to remove them, and save space. The function
 @ref{gnutls_db_check_entry} is provided for that reason.
 
+@subsection Compatibility issues
+The @acronym{TLS} handshake is a complex procedure that negotiates all
+required parameters for a secure session. @acronym{GnuTLS} supports
+several @acronym{TLS} extensions, as well as the latest known published
+version being @acronym{TLS} 1.2. However few implementations are not able to
+properly interoperate once faced with extensions or version protocols
+they do not support and understand. The @acronym{TLS} protocol allows for 
+graceful downgrade to the commonly supported options, but practice shows that 
+it is not always implemented correctly. 
+
+Because there is no way to handle maximum compatibility with such broken peers
+without sacrificing security, @acronym{GnuTLS} ignores such peers by default. 
+This might not be acceptable in several cases
+thus we allow enabling maximum compatibility with such peers using
+priority strings (see @ref{Priority Strings}). An example priority string that will
+disable all supported  @acronym{TLS} protocol versions except for
+the widely supported @acronym{SSL} 3.0 and @acronym{TLS} 1.0
+is shown below:
+@example
+NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
+@end example
+This priority string provides wider compatibility to broken peers. 
+We suggest however to use the normal defaults and only switch to such compatibility
+modes only when compatibility issues occur.
+
 @node TLS Extensions
 @section TLS Extensions
 @cindex TLS Extensions