[SCM] GNU gnutls branch, gnutls_3_0_x, updated. gnutls_3_0_0-36-gdbeae92

[Nikos Mavrogiannopoulos]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU gnutls".

http://git.savannah.gnu.org/cgit/gnutls.git/commit/?id=dbeae928aa4db45aacbeb42a79e67de3057a2c18

The branch, gnutls_3_0_x has been updated
       via  dbeae928aa4db45aacbeb42a79e67de3057a2c18 (commit)
      from  84f0da8c988b8fcd052a4636c33d747a38d8c9e4 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit dbeae928aa4db45aacbeb42a79e67de3057a2c18
Author: Nikos Mavrogiannopoulos <address@hidden>
Date:   Thu Aug 11 16:14:29 2011 +0200

    Added session initialization discussion

-----------------------------------------------------------------------

Summary of changes:
 doc/cha-gtls-app.texi  |  239 ++++++++++++++++++++++++++++++++++++++++++++----
 doc/cha-intro-tls.texi |  180 +-----------------------------------
 doc/cha-library.texi   |   20 ++++
 lib/system_override.c  |   23 ++---
 4 files changed, 253 insertions(+), 209 deletions(-)

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 69b17b1..2bcb5b3 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -5,6 +5,8 @@
 
 @menu
 * Preparation::
+* Session initialization::
+* Priority Strings::
 * Client examples::
 * Server examples::
 * Miscellaneous examples::
@@ -23,7 +25,6 @@ the following subsections.
 * Headers::
 * Initialization::
 * Version check::
-* Debugging and auditing::
 * Building the source::
 @end menu
 
@@ -65,24 +66,6 @@ with the dynamic linker an old version is actually used.  So 
you may
 want to check that the version is okay right after program start-up.
 See the function @funcref{gnutls_check_version}.
 
address@hidden Debugging and auditing
address@hidden Debugging and auditing
-
-In many cases things may not go as expected and further information,
-to assist debugging, from @acronym{GnuTLS} is desired. 
-Those are the cases where the @funcref{gnutls_global_set_log_level} and
address@hidden are to be used. Those will print
-verbose information on the @acronym{GnuTLS} functions internal flow.
-
-
-When debugging is not required, important issues, such as detected
-attacks on the protocol still need to be logged. This is provided
-by the logging function set by
address@hidden The set function
-accepts the detected error message and the corresponding
-TLS session. The session information might be used to derive IP addresses
-or other information about the peer involved.
-
 @node Building the source
 @subsection Building the source
 
@@ -130,6 +113,224 @@ specifying both options to @command{pkg-config}:
 gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
 @end smallexample
 
address@hidden Session initialization
address@hidden Session initialization
+
+In the previous sections we have discussed the global initialization
+required for GnuTLS as well as the initialization required for each
+authentication method's credentials (see @ref{Authentication methods}).
+In this section we elaborate on the TLS or DTLS session initiation.
+Each session is initialized using @funcref{gnutls_init} which among
+others is used to specify the type of the connection (server or client), 
+and the underlying protocol type, i.e., datagram (UDP) or reliable (TCP).
+
address@hidden
+
+After the session initialization details on the allowed ciphersuites
+and protocol versions should be set using the priority functions
+such as @funcref{gnutls_priority_set_direct}. We elaborate on them
+in @ref{Priority Strings}.
+The credentials used for the key exchange method, such as certificates 
+or usernames and passwords should also be associated with the session
+current session using @funcref{gnutls_credentials_set} (see 
@ref{Authentication methods}). 
+
+The next step is to setup the underlying transport layer details. The
+Berkeley sockets for TCP are implicitly used by default in GnuTLS, thus a
+call to @funcref{gnutls_transport_set_ptr} would be sufficient to
+specify the socket descriptor.
+
address@hidden
+
+If however another transport layer than TCP is selected, then
+the following functions have to be specified.
+
address@hidden
address@hidden
address@hidden
+
+In the case of DTLS it is also desirable to override the
+functions above with functions that emulate the operation
+of @code{recvfrom} and @code{sendto}. In addition
+the following function must also be called to specify a 
+callback that will receive data from within a specified
+time limit.
+
address@hidden
+
+
address@hidden Priority Strings
address@hidden Priority strings
+
+In order to specify cipher suite preferences on client or server side, the
+previously mentioned priority functions accept a string
+that specifies the enabled for the handshake algorithms.
+That string may contain some high level keyword such as
+the keywords in @ref{tab:prio-keywords}
+or it might contain special keywords, to be explained
+later on.
+
address@hidden,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set}
+
address@hidden Table,tab:prio-keywords
address@hidden @columnfractions .30 .70
address@hidden Keyword @tab Description
address@hidden PERFORMANCE @tab
+All the "secure" ciphersuites are enabled,
+limited to 128 bit ciphers and sorted by terms of speed
+performance.
+
address@hidden NORMAL @tab
+Means all "secure" ciphersuites. The 256-bit ciphers are
+included as a fallback only.  The ciphers are sorted by security
+margin.
+
address@hidden SECURE128 @tab
+Means all "secure" ciphersuites of security level 128-bit
+or more.
+
address@hidden SECURE192 @tab
+Means all "secure" ciphersuites of security level 192-bit
+or more.
+
address@hidden SUITEB128 @tab
+Means all the NSA Suite B cryptography (RFC5430) ciphersuites
+with an 128 bit security level.
+
address@hidden SUITEB192 @tab
+Means all the NSA Suite B cryptography (RFC5430) ciphersuites
+with an 192 bit security level.
+
address@hidden EXPORT @tab
+Means all ciphersuites are enabled, including the
+low-security 40 bit ciphers.
+
address@hidden NONE @tab
+Means nothing is enabled.  This disables even protocols and
+compression methods. It should be followed by the
+algorithms to be enabled.
+
address@hidden multitable
address@hidden priority string keywords.}
address@hidden float
+
+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 must followed by the algorithms to be enabled,
+and is used to provide the exact list of requested address@hidden 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:
address@hidden @asis
address@hidden '!' or '-' 
+appended with an algorithm will remove this algorithm.
address@hidden "+" 
+appended with an algorithm will add this algorithm.
address@hidden table
+
+
address@hidden Table,tab:prio-algorithms
address@hidden @columnfractions .30 .70
address@hidden Type @tab Keywords
address@hidden Ciphers @tab
+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 algorithms from NORMAL
+priority.
+
address@hidden Key exchange @tab
+RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
+PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The
+Catch all name is KX-ALL which will add all the algorithms from NORMAL
+priority.
+
address@hidden MAC @tab
+MD5, SHA1, SHA256, AEAD (used with
+GCM ciphers only). All algorithms from NORMAL priority can be accessed with 
MAC-ALL.
+
address@hidden Compression algorithms @tab
+COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
+
address@hidden TLS versions @tab
+VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
+VERS-TLS1.2. Catch all is VERS-TLS-ALL.
+
address@hidden Signature algorithms @tab
+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.
+
address@hidden Elliptic curves @tab
+CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all 
is CURVE-ALL.
+
address@hidden multitable
address@hidden supported priority strings.}
address@hidden float
+
+
+
address@hidden Table,tab:prio-special
address@hidden @columnfractions .50 .50
address@hidden Keyword @tab Description
+
address@hidden %COMPAT @tab
+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.
+
address@hidden %DISABLE_SAFE_RENEGOTIATION @tab
+will disable safe renegotiation
+completely.  Do not use unless you know what you are doing.
+Testing purposes only.
+
address@hidden %UNSAFE_RENEGOTIATION @tab
+will allow handshakes and re-handshakes
+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.
+
address@hidden %PARTIAL_RENEGOTIATION @tab
+will allow initial handshakes to proceed,
+but not re-handshakes.  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.
+
address@hidden %SAFE_RENEGOTIATION @tab
+will enforce safe renegotiation.  Clients and
+servers will refuse to talk to an insecure peer.  Currently this
+causes interoperability problems, but is required for full protection.
+
address@hidden %SSL3_RECORD_VERSION @tab
+will use SSL3.0 record version in client hello.
+This is the default.
+
address@hidden %LATEST_RECORD_VERSION @tab
+will use the latest TLS version record version in client hello.
+
address@hidden %VERIFY_ALLOW_SIGN_RSA_MD5 @tab
+will allow RSA-MD5 signatures in certificate chains.
+
address@hidden %VERIFY_ALLOW_X509_V1_CA_CRT @tab
+will allow V1 CAs in chains.
+
address@hidden multitable
address@hidden priority string keywords.}
address@hidden float
+
 
 @node Client examples
 @section Client examples
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 4cb90cd..433cdab 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -99,10 +99,8 @@ since signals do not interrupt @acronym{GnuTLS}' functions.
 timers and waiting for peer's messages during the handshake process,
 @acronym{GnuTLS} will block and might be interrupted by signals. The
 blocking operation of @acronym{GnuTLS} during @acronym{DTLS} handshake
-can be changed using the appropriate flags in @funcref{gnutls_init}.
-
address@hidden
-
+can be changed using the appropriate flags in @funcref{gnutls_init} (see
address@hidden initialization}).
 By default, if the transport functions are not set, @acronym{GnuTLS}
 will use the Berkeley sockets. 
 
@@ -354,7 +352,6 @@ controlling of the handshake protocol, i.e., the 
ciphersuite negotiation.
 
 @menu
 * TLS Cipher Suites::           TLS session parameters.
-* Priority Strings::            Defining how parameters are negotiated.
 * Client Authentication::       Requesting a certificate from the client.
 * Resuming Sessions::           Reusing previously established keys.
 * Interoperability::            About interoperability with other 
implementations.
@@ -388,179 +385,6 @@ that you consider weak.
 
 All the supported ciphersuites are listed in @ref{ciphersuites}.
 
address@hidden Priority Strings
address@hidden Priority strings
-
-In order to specify cipher suite preferences on client or server side, the
-previously shown priority functions accept a string
-that specifies the enable for the handshake algorithms.
-That string may contain some high level keyword such as
-the keywords in @ref{tab:prio-keywords}
-or it might contain special keywords, to be explained
-later on.
-
address@hidden,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set}
-
address@hidden Table,tab:prio-keywords
address@hidden @columnfractions .30 .70
address@hidden Keyword @tab Description
address@hidden PERFORMANCE @tab
-All the "secure" ciphersuites are enabled,
-limited to 128 bit ciphers and sorted by terms of speed
-performance.
-
address@hidden NORMAL @tab
-Means all "secure" ciphersuites. The 256-bit ciphers are
-included as a fallback only.  The ciphers are sorted by security
-margin.
-
address@hidden SECURE128 @tab
-Means all "secure" ciphersuites of security level 128-bit
-or more.
-
address@hidden SECURE192 @tab
-Means all "secure" ciphersuites of security level 192-bit
-or more.
-
address@hidden SUITEB128 @tab
-Means all the NSA Suite B cryptography (RFC5430) ciphersuites
-with an 128 bit security level.
-
address@hidden SUITEB192 @tab
-Means all the NSA Suite B cryptography (RFC5430) ciphersuites
-with an 192 bit security level.
-
address@hidden EXPORT @tab
-Means all ciphersuites are enabled, including the
-low-security 40 bit ciphers.
-
address@hidden NONE @tab
-Means nothing is enabled.  This disables even protocols and
-compression methods. It should be followed by the
-algorithms to be enabled.
-
address@hidden multitable
address@hidden priority string keywords.}
address@hidden float
-
-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 must followed by the algorithms to be enabled,
-and is used to provide the exact list of requested address@hidden 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:
address@hidden @asis
address@hidden '!' or '-' 
-appended with an algorithm will remove this algorithm.
address@hidden "+" 
-appended with an algorithm will add this algorithm.
address@hidden table
-
-
address@hidden Table,tab:prio-algorithms
address@hidden @columnfractions .30 .70
address@hidden Type @tab Keywords
address@hidden Ciphers @tab
-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 algorithms from NORMAL
-priority.
-
address@hidden Key exchange @tab
-RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
-PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The
-Catch all name is KX-ALL which will add all the algorithms from NORMAL
-priority.
-
address@hidden MAC @tab
-MD5, SHA1, SHA256, AEAD (used with
-GCM ciphers only). All algorithms from NORMAL priority can be accessed with 
MAC-ALL.
-
address@hidden Compression algorithms @tab
-COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
-
address@hidden TLS versions @tab
-VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
-VERS-TLS1.2. Catch all is VERS-TLS-ALL.
-
address@hidden Signature algorithms @tab
-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.
-
address@hidden Elliptic curves @tab
-CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all 
is CURVE-ALL.
-
address@hidden multitable
address@hidden supported priority strings.}
address@hidden float
-
-
-
address@hidden Table,tab:prio-special
address@hidden @columnfractions .50 .50
address@hidden Keyword @tab Description
-
address@hidden %COMPAT @tab
-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.
-
address@hidden %DISABLE_SAFE_RENEGOTIATION @tab
-will disable safe renegotiation
-completely.  Do not use unless you know what you are doing.
-Testing purposes only.
-
address@hidden %UNSAFE_RENEGOTIATION @tab
-will allow handshakes and re-handshakes
-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.
-
address@hidden %PARTIAL_RENEGOTIATION @tab
-will allow initial handshakes to proceed,
-but not re-handshakes.  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.
-
address@hidden %SAFE_RENEGOTIATION @tab
-will enforce safe renegotiation.  Clients and
-servers will refuse to talk to an insecure peer.  Currently this
-causes interoperability problems, but is required for full protection.
-
address@hidden %SSL3_RECORD_VERSION @tab
-will use SSL3.0 record version in client hello.
-This is the default.
-
address@hidden %LATEST_RECORD_VERSION @tab
-will use the latest TLS version record version in client hello.
-
address@hidden %VERIFY_ALLOW_SIGN_RSA_MD5 @tab
-will allow RSA-MD5 signatures in certificate chains.
-
address@hidden %VERIFY_ALLOW_X509_V1_CA_CRT @tab
-will allow V1 CAs in chains.
-
address@hidden multitable
address@hidden priority string keywords.}
address@hidden float
-
 @node Client Authentication
 @subsection Client authentication
 @cindex Client Certificate authentication
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 98448c4..cf5a2cf 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -130,6 +130,26 @@ a function, these error codes will be documented in the 
function's
 reference.  See @ref{Error codes}, for a description of the available 
 error codes.
 
address@hidden Debugging and auditing
+
+In many cases things may not go as expected and further information,
+to assist debugging, from @acronym{GnuTLS} is desired. 
+Those are the cases where the @funcref{gnutls_global_set_log_level} and
address@hidden are to be used. Those will print
+verbose information on the @acronym{GnuTLS} functions internal flow.
+
address@hidden,gnutls_global_set_log_function}
+
+When debugging is not required, important issues, such as detected
+attacks on the protocol still need to be logged. This is provided
+by the logging function set by
address@hidden The set function
+accepts the detected error message and the corresponding
+TLS session. The session information might be used to derive IP addresses
+or other information about the peer involved.
+
address@hidden
+
 @node Memory handling
 @section Memory handling
 
diff --git a/lib/system_override.c b/lib/system_override.c
index 9d631c5..82463d0 100644
--- a/lib/system_override.c
+++ b/lib/system_override.c
@@ -70,11 +70,11 @@ gnutls_transport_set_errno (gnutls_session_t session, int 
err)
  *
  * This is the function where you set a function for gnutls to receive
  * data.  Normally, if you use berkeley style sockets, do not need to
- * use this function since the default (recv(2)) will probably be ok.
+ * use this function since the default recv(2) will probably be ok.
  * The callback should return 0 on connection termination, a positive
  * number indicating the number of bytes received, and -1 on error.
  *
- * gnutls_pull_func is of the form,
+ * @gnutls_pull_func is of the form,
  * ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
  **/
 void
@@ -99,7 +99,7 @@ gnutls_transport_set_pull_function (gnutls_session_t session,
  *
  * The callback function is used in DTLS only.
  *
- * gnutls_pull_timeout_func is of the form,
+ * @gnutls_pull_timeout_func is of the form,
  * ssize_t (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, void*data, 
size_t size, unsigned int ms);
  *
  * Since: 3.0.0
@@ -119,12 +119,12 @@ gnutls_transport_set_pull_timeout_function 
(gnutls_session_t session,
  * This is the function where you set a push function for gnutls to
  * use in order to send data.  If you are going to use berkeley style
  * sockets, you do not need to use this function since the default
- * (send(2)) will probably be ok.  Otherwise you should specify this
+ * send(2) will probably be ok.  Otherwise you should specify this
  * function for gnutls to be able to send data.
  * The callback should return a positive number indicating the
  * bytes sent, and -1 on error.
  *
- * push_func is of the form,
+ * @push_func is of the form,
  * ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
  *
  **/
@@ -141,13 +141,12 @@ gnutls_transport_set_push_function (gnutls_session_t 
session,
  * @session: is a #gnutls_session_t structure.
  * @vec_func: a callback function similar to writev()
  *
- * This is the function where you set a push function for gnutls to
- * use in order to send data.  If you are going to use berkeley style
- * sockets, you do not need to use this function since the default
- * (send(2)) will probably be ok.  Otherwise you should specify this
- * function for gnutls to be able to send data.
+ * Using this function you can override the default writev(2)
+ * function for gnutls to send data. Setting this callback 
+ * instead of gnutls_transport_set_push_function() is recommended
+ * since it introduces less overhead in the TLS handshake process.
  *
- * vec_func is of the form,
+ * @vec_func is of the form,
  * ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * 
iov, int iovcnt);
  *
  * Since: 2.12.0
@@ -168,7 +167,7 @@ gnutls_transport_set_vec_push_function (gnutls_session_t 
session,
  * This is the function where you set a function to retrieve errno
  * after a failed push or pull operation.
  *
- * errno_func is of the form,
+ * @errno_func is of the form,
  * int (*gnutls_errno_func)(gnutls_transport_ptr_t);
  * and should return the errno.
  *


hooks/post-receive
-- 
GNU gnutls