[SCM] GNU gnutls branch, master, updated. gnutls_3_0_0-36-g641115f

[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=641115f7ebcb29b1ff6ebd0aa5de13b94684c13b

The branch, master has been updated
       via  641115f7ebcb29b1ff6ebd0aa5de13b94684c13b (commit)
      from  f2dd1a574c79b5d2c378ce632d7469abaff9683e (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 641115f7ebcb29b1ff6ebd0aa5de13b94684c13b
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