Moved documentation of priority strings to manual and removed information from manpages and function pages that now reference the manual section.

4 files changed, 172 insertions, 74 deletions

diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 3232958f82..0535234a7f 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -316,6 +316,154 @@ To set whether client certificate is required or not.
 To initiate the handshake.
 @end table
 
+@subsection Priority strings
+The previously shown priority functions accept a string
+that specifies the algorithms to be enabled in a TLS handshake.
+This string may contain some high level keyword such as:
+
+@table @asis
+@item PERFORMANCE:
+All the "secure" ciphersuites are enabled,
+limited to 128 bit ciphers and sorted by terms of speed
+performance.
+
+@item NORMAL:
+Means all "secure" ciphersuites. The 256-bit ciphers are
+included as a fallback only.  The ciphers are sorted by security
+margin.
+
+@item SECURE128: 
+Means all "secure" ciphersuites with ciphers up to 128
+bits, sorted by security margin.
+
+@item SECURE256:
+Means all "secure" ciphersuites including the 256 bit
+ciphers, sorted by security margin.
+
+@item EXPORT:
+Means all ciphersuites are enabled, including the
+low-security 40 bit ciphers.
+
+@item NONE:
+Means nothing is enabled.  This disables even protocols and
+compression methods. It should be followed by the
+algorithms to be enabled.
+
+@end table
+
+or it might contain special keywords, that will be explained
+later on.
+
+Unless the first 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, OpenPGP.
+For key exchange algorithms when in NORMAL or SECURE levels the
+perfect forward secrecy algorithms take precedence of the other
+protocols.  In all cases all the supported key exchange algorithms
+ are enabled (except for the RSA-EXPORT which is only enabled in
+EXPORT level).
+
+The NONE keyword is 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.
+
+Keywords prepended to individual algorithms:
+@table @asis
+
+@item '!' or '-' 
+appended with an algorithm will remove this algorithm.
+
+@item "+" 
+appended with an algorithm will add this algorithm.
+
+@end table
+
+Individual algorithms:
+@table @asis
+@item Ciphers: 
+AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
+CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
+name is CIPHER-ALL which will add all the non-weak algorithms, i.e.
+all except ARCFOUR-40.
+
+@item Key exchange: 
+RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
+PSK, DHE-PSK, ANON-DH, RSA-EXPORT. The
+key exchange methods do not have a catch all.
+
+@item MAC: 
+MD5, SHA1, SHA256, AEAD (used with
+GCM ciphers only). Catch all is MAC-ALL.
+
+@item Compression algorithms: 
+COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
+
+@item TLS versions: 
+VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
+VERS-TLS1.2. Catch all is VERS-TLS-ALL.
+
+@item Signature algorithms: 
+SIGN-RSA-SHA1, SIGN-RSA-SHA224, 
+SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1, 
+SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
+is SIGN-ALL. This is only valid for TLS 1.2 and later.
+
+@end table
+
+
+Special keywords:
+@table @asis
+
+@item %COMPAT:
+will enable compatibility mode. It might mean that violations
+of the protocols are allowed as long as maximum compatibility with
+problematic clients and servers is achieved.
+
+@item %DISABLE_SAFE_RENEGOTIATION:
+will disable safe renegotiation
+completely.  Do not use unless you know what you are doing.
+Testing purposes only.
+
+@item %UNSAFE_RENEGOTIATION:
+will allow handshakes and rehandshakes
+without the safe renegotiation extension.  Note that for clients
+this mode is insecure (you may be under attack), and for servers it
+will allow insecure clients to connect (which could be fooled by an
+attacker).  Do not use unless you know what you are doing and want
+maximum compatibility.
+
+@item %PARTIAL_RENEGOTIATION:
+will allow initial handshakes to proceed,
+but not rehandshakes.  This leaves the client vulnerable to attack,
+and servers will be compatible with non-upgraded clients for
+initial handshakes.  This is currently the default for clients and
+servers, for compatibility reasons.
+
+@item %SAFE_RENEGOTIATION:
+will enforce safe renegotiation.  Clients and
+servers will refuse to talk to an insecure peer.  Currently this
+causes operability problems, but is required for full protection.
+
+@item %SSL3_RECORD_VERSION:
+will use SSL3.0 record version in client hello.
+This is the default.
+
+@item %LATEST_RECORD_VERSION:
+will use the latest TLS version record version in client hello.
+
+@item %VERIFY_ALLOW_SIGN_RSA_MD5:
+will allow RSA-MD5 signatures in certificate chains.
+
+@item %VERIFY_ALLOW_X509_V1_CA_CRT:
+will allow V1 CAs in chains.
+
+@end table
+
 @subsection TLS Cipher Suites
 
 The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index ffce898ebd..357d8c4938 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -7,7 +7,7 @@ privacy over insecure lines, and were designed to prevent
 eavesdropping, tampering, or message forgery.
 
 Technically @acronym{GnuTLS} is a portable ANSI C based library which
-implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to
+implements the protocols ranging from SSL 3.0 to TLS 1.2s (@xref{Introduction to
 TLS}, for a more detailed description of the protocols), accompanied
 with the required framework for authentication and public key
 infrastructure.  Important features of the @acronym{GnuTLS} library
@@ -15,7 +15,7 @@ include:
 
 @itemize
 
-@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols.
+@item Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
 
 @item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.
 
diff --git a/doc/manpages/gnutls-cli.1 b/doc/manpages/gnutls-cli.1
index 9b3b408a72..0b170ec6ab 100644
--- a/doc/manpages/gnutls-cli.1
+++ b/doc/manpages/gnutls-cli.1
@@ -28,18 +28,7 @@ More verbose output.
 .SS TLS/SSL control options
 .IP "\-\-priority \fIPRIORITY STRING\fR"
 TLS algorithms and protocols to enable.
-Unless the first keyword is "NONE" the defaults are:
-.IP 
-Protocols: TLS1.1, TLS1.0, and SSL3.0.
-.IP 
-Compression: NULL.
-.IP 
-Certificate types: X.509, OpenPGP.
-.IP
-Signature algorithms: RSA-SHA1, RSA-MD2, RSA-MD5, RSA-SHA256, RSA-SHA512,
-DSA-SHA1.
-.IP
-You can also use predefined sets of ciphersuites such as: 
+You can use predefined sets of ciphersuites such as: 
 .IP
 .B "PERFORMANCE"
 all the "secure" ciphersuites are enabled, limited to 128 bit
@@ -66,41 +55,24 @@ low-security 40 bit ciphers.
 nothing is enabled. This disables even protocols and
 compression methods.
 .IP
-.IP 
-Special keywords:
-.IP
-"!" or "-" appended with an algorithm will remove this algorithm.
-.IP
-"+" appended with an algorithm will add this algorithm.
 .IP
-"%COMPAT" will enable compatibility features for a server.
-.IP
-"%SSL3_RECORD_VERSION" force SSL3.0 record version in the first client
-hello. This is to avoid buggy servers from terminating connection.
-.IP
-"%UNSAFE_RENEGOTIATION" Permits (re-)handshakes even unsafe ones.
-.IP
-"%PARTIAL_RENEGOTIATION" Prevents renegotiation with clients and servers not
-supporting the safe renegotiation extension. (default)
-.IP
-"%SAFE_RENEGOTIATION" will enable safe renegotiation. This is the most
-secure and recommended option for clients. However this will prevent from
-connecting to legacy servers.
-.IP
-To avoid collisions in order to specify a compression algorithm in
-this string you have to prefix it with "COMP-", protocol versions
-with "VERS-" and certificate types with "CTYPE-". All other
-algorithms don't need a prefix.
+Check the GnuTLS manual on section "Priority strings" for
+more information on allowed keywords.
 .IP 
 .B Examples:
 .IP 
 "NORMAL"
 .IP 
-"NORMAL:%COMPAT"
+"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
+.IP 
+"NORMAL:-ARCFOUR-128" means normal ciphers except for ARCFOUR-128.
 .IP 
-"NORMAL:!AES-128-CBC"
+"SECURE:-VERS-SSL3.0:+COMP-DEFLATE" means that only secure ciphers are
+enabled, SSL3.0 is disabled, and libz compression enabled.
+.IP
+ "NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1"
 .IP 
-"NONE:+VERS-TLS1.0:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL"
+"NORMAL:%COMPAT" is the most compatible mode
 
 .IP "\-\-crlf"
 Send CR LF instead of LF.
diff --git a/doc/manpages/gnutls-serv.1 b/doc/manpages/gnutls-serv.1
index 4f6413c718..407475d89d 100644
--- a/doc/manpages/gnutls-serv.1
+++ b/doc/manpages/gnutls-serv.1
@@ -31,15 +31,7 @@ Act as an Echo Server.
 .SS TLS/SSL control options
 .IP "\-\-priority \fIPRIORITY STRING\fR"
 TLS algorithms and protocols to enable.
-Unless the first keyword is "NONE" the defaults are:
-.IP 
-Protocols: TLS1.1, TLS1.0, and SSL3.0.
-.IP 
-Compression: NULL.
-.IP 
-Certificate types: X.509, OpenPGP.
-.IP
-You can also use predefined sets of ciphersuites such as: 
+You can use predefined sets of ciphersuites such as: 
 .IP
 .B "PERFORMANCE"
 all the "secure" ciphersuites are enabled, limited to 128 bit
@@ -66,38 +58,24 @@ low-security 40 bit ciphers.
 nothing is enabled. This disables even protocols and
 compression methods.
 .IP
-.IP 
-Special keywords:
-.IP
-"!" or "-" appended with an algorithm will remove this algorithm.
-.IP
-"+" appended with an algorithm will add this algorithm.
 .IP
-"%COMPAT" will enable compatibility features for a server.
-.IP
-"%UNSAFE_RENEGOTIATION" Permits (re-)handshakes even unsafe ones.
-.IP
-"%PARTIAL_RENEGOTIATION" Prevents renegotiation with clients and servers not
-supporting the safe renegotiation extension. (default)
-.IP
-"%SAFE_RENEGOTIATION" will enable safe renegotiation. This is the most
-secure and recommended option for clients. However this will prevent from
-connecting to legacy servers.
-.IP
-To avoid collisions in order to specify a compression algorithm in
-this string you have to prefix it with "COMP-", protocol versions
-with "VERS-" and certificate types with "CTYPE-". All other
-algorithms don't need a prefix.
+Check the GnuTLS manual on section "Priority strings" for
+more information on allowed keywords.
 .IP 
 .B Examples:
 .IP 
 "NORMAL"
 .IP 
-"NORMAL:%COMPAT"
+"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
+.IP 
+"NORMAL:-ARCFOUR-128" means normal ciphers except for ARCFOUR-128.
 .IP 
-"NORMAL:!AES-128-CBC"
+"SECURE:-VERS-SSL3.0:+COMP-DEFLATE" means that only secure ciphers are
+enabled, SSL3.0 is disabled, and libz compression enabled.
+.IP
+ "NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1"
 .IP 
-"NONE:+VERS-TLS1.0:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL"
+"NORMAL:%COMPAT" is the most compatible mode
 
 .IP "\-g, \-\-generate"
 Generate Diffie-Hellman Parameters.