[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] GNU gnutls branch, gnutls_3_0_x, updated. gnutls_3_0_0-36-gdbeae92
From: |
Nikos Mavrogiannopoulos |
Subject: |
[SCM] GNU gnutls branch, gnutls_3_0_x, updated. gnutls_3_0_0-36-gdbeae92 |
Date: |
Thu, 11 Aug 2011 16:40:04 +0000 |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] GNU gnutls branch, gnutls_3_0_x, updated. gnutls_3_0_0-36-gdbeae92,
Nikos Mavrogiannopoulos <=