updated interoperability and priority strings sections.

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index b9c7e693044ce4e741019042bb862ba22ea9bc44..7f3d338fdf996d8782d45e6340be9246f1aa2a4a 100644 (file)
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -734,9 +734,9 @@ Alerts messages may be sent to the peer using @funcref{gnutls_alert_send}.
 In order to specify cipher suite preferences on a TLS session
 there are priority functions that accept a string
 specifying the enabled for the handshake algorithms.
-That string may contain a high level keyword such as
-in @ref{tab:prio-keywords} or combination of a high level
-keyword, additional algorithm keywords and special keywords.
+That string may contain a single initial keyword such as
+in @ref{tab:prio-keywords} and may be followed by
+additional algorithm or special keywords.
 
 @showfuncB{gnutls_priority_set_direct,gnutls_priority_set}
 
@@ -784,10 +784,10 @@ compression methods. It should be followed by the
 algorithms to be enabled.
 
 @end multitable
-@caption{Supported priority string keywords.}
+@caption{Supported initial keywords.}
 @end float
 
-Unless the first keyword is "NONE" the defaults (in preference
+Unless the initial keyword is "NONE" the defaults (in preference
 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
 compression NULL; for certificate types X.509.
 In key exchange algorithms when in NORMAL or SECURE levels the
@@ -803,15 +803,19 @@ the algorithms at real-time during the protocol run, whilst
 the overall security level refers to off-line adversaries 
 (e.g. adversaries breaking the ciphertext years after it was captured).
 
-The NONE keyword, if used, must followed by the algorithms to be enabled,
-and is used to provide the exact list of requested algorithms@footnote{To avoid collisions in order to specify a compression algorithm in
-this string you have to prefix it with "COMP-", protocol versions
-with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other
-algorithms don't need a prefix.}. The order with which every algorithm
-is specified is significant. Similar algorithms specified before others
-will take precedence. The individual algorithms are shown in @ref{tab:prio-algorithms}
-and special keywords are in @ref{tab:prio-special}.
-The prefixes for individual algorithms are:
+The NONE keyword, if used, must followed by keywords specifying 
+the algorithms and protocols to be enabled. The other initial keywords may be 
+followed by such keywords.
+The order with which every algorithm or protocol
+is specified is significant. Algorithms specified before others
+will take precedence. The supported algorithms and protocols
+are shown in @ref{tab:prio-algorithms}. 
+To avoid collisions in order to specify a compression algorithm in
+the priority string you have to prefix it with "COMP-", protocol versions
+with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". 
+All other algorithms don't need a prefix. Each specified keyword can
+be prefixed with any of the following characters.
+
 @table @asis
 @item '!' or '-' 
 appended with an algorithm will remove this algorithm.
@@ -866,6 +870,8 @@ for the acceptable security levels.} than their elliptic curves counterpart
 requires parameters to be generated and associated with a credentials
 structure by the server (see @ref{Parameter generation}). 
 
+The available special keywords are shown in @ref{tab:prio-special}. 
+
 @float Table,tab:prio-special
 @multitable @columnfractions .45 .45
 @headitem Keyword @tab Description
@@ -932,6 +938,21 @@ Finally the ciphersuites enabled by any priority string can be
 listed using the @code{gnutls-cli} application (see @ref{The gnutls-cli tool}), 
 or by using the priority functions as in @ref{Listing the ciphersuites in a priority string}.
 
+Example priority strings are:
+@example
+The default priority:
+    "NORMAL"
+
+Specifying RSA with AES-128-CBC:
+    "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
+
+Specifying the defaults except ARCFOUR-128:
+    "NORMAL:-ARCFOUR-128"
+
+Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and enabling compression:
+    "SECURE128:-VERS-SSL3.0:+COMP-DEFLATE"
+@end example
+
 @node Advanced and other topics
 @section Advanced and other topics
 
@@ -1146,8 +1167,12 @@ NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
 @end verbatim
 This priority string will in addition to above, only enable SSL 3.0 and 
 TLS 1.0 as protocols. Note however that
-there are known attacks against those protocol versions and
-this mode trades security for compatibility.
+there are known attacks against those protocol versions, especially over
+the CBC-mode ciphersuites. To mitigate them another priority string
+that only allows the stream cipher ARCFOUR is below.
+@verbatim
+NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:-CIPHER-ALL:+ARCFOUR-128:%COMPAT
+@end verbatim
 
 @node Compatibility with the OpenSSL library
 @subsection Compatibility with the OpenSSL library

diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index f0063bf91bdcbf41dc566e883db5aea695069614..7a6f36f3909e86f17bfff2040a44f7bdd2a797fe 100644 (file)
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -219,7 +219,8 @@ encrypted packet.
 
 Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
 which is implemented in @acronym{GnuTLS}. For this reason we suggest
-to always negotiate the highest supported TLS version with the peer.
+to always negotiate the highest supported TLS version with the 
+peer@foonote{If this is not possible then please consult @ref{Interoperability}.}.
 For a detailed discussion of the issues see the archives of the TLS 
 Working Group mailing list and @xcite{CBCATT}.