gnutls-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[SCM] GNU gnutls branch, master, updated. gnutls_3_0_8-23-g5cbd39f


From: Nikos Mavrogiannopoulos
Subject: [SCM] GNU gnutls branch, master, updated. gnutls_3_0_8-23-g5cbd39f
Date: Sat, 26 Nov 2011 09:29:40 +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=5cbd39faca0e1d1c40d69eda063d3002bad58f64

The branch, master has been updated
       via  5cbd39faca0e1d1c40d69eda063d3002bad58f64 (commit)
      from  d702ff5cd2a28c2d3f0ea02156f7d536b138276a (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 5cbd39faca0e1d1c40d69eda063d3002bad58f64
Author: Nikos Mavrogiannopoulos <address@hidden>
Date:   Sat Nov 26 10:31:44 2011 +0100

    documentation updates.

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

Summary of changes:
 doc/cha-gtls-app.texi    |  128 ++++++++++++++++++++++++++++++++++++++++-----
 doc/cha-intro-tls.texi   |  103 ++++++-------------------------------
 doc/scripts/mytexi2latex |    6 +-
 3 files changed, 132 insertions(+), 105 deletions(-)

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 1c73f4b..7054312 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -301,38 +301,40 @@ current session using @funcref{gnutls_credentials_set}.
 
 @node Certificate credentials
 @subsection Certificates
address@hidden Server certificate authentication
 
 When using certificates the server is required to have at least one
-certificate and private key pair. A client may or may not have such a
-pair. 
+certificate and private key pair. Clients may not hold such
+a pair, but a server could require it. On this section we discuss
+general issues applying to both client and server certificates. The next
+section will elaborate on issues arising from client authentication only.
 
 
@showfuncB{gnutls_certificate_allocate_credentials,gnutls_certificate_free_credentials}
 
-After the credentials structures are initialized using the functions
-above, the certificate and key pair should be loaded. This should
-occur before any @acronym{TLS} session is initialized.
+After the credentials structures are initialized, the certificate 
+and key pair must be loaded. This occurs before any @acronym{TLS} 
+session is initialized, and the same structures are reused for multiple 
sessions.
 Depending on the certificate type different loading functions
-are available, and are shown below.
-In the @acronym{X.509} case, the functions will
-also accept and use a certificate list that leads to a trusted
-authority. The certificate list must be ordered in such way that every
+are available, as shown below.
+For @acronym{X.509} certificates, the functions will
+accept and use a certificate chain that leads to a trusted
+authority. The certificate chain must be ordered in such way that every
 certificate certifies the one before it. The trusted authority's
-certificate need not to be included, since the peer should possess it
+certificate need not to be included since the peer should possess it
 already.
 
 
@showfuncC{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_file}
 
 
@showfuncD{gnutls_certificate_set_openpgp_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_key}
 
-As an alternative to loading from files, a callback may be used so that the 
-server or the client can specify the certificate and the key at the handshake 
time.
+As an alternative to loading from files or buffers, a callback may be used for 
the 
+server or the client to specify the certificate and the key at the handshake 
time.
 In that case a certificate should be selected according the peer's signature
 algorithm preferences. To get those preferences use
 @funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below.
 
 
@showfuncB{gnutls_certificate_set_retrieve_function,gnutls_sign_algorithm_get_requested}
 
-
 Certificate verification is possible by loading the trusted
 authorities into the credentials structure by using
 the following functions, applicable to X.509 and OpenPGP certificates.
@@ -372,6 +374,24 @@ for the acceptable security levels.} than the elliptic 
curves counterpart
 requires parameters to be generated and associated with a credentials
 structure by the server (see @ref{Parameter generation}). 
 
+
address@hidden Client certificate authentication
+
+If a certificate is to be requested from the client during the handshake, the 
server
+will send a certificate request message. This behavior is controlled 
@funcref{gnutls_certificate_server_set_request}.
+The request contains a list of the acceptable by the server certificate 
signers. This list
+is constructed using the trusted certificate authorities of the server.
+In cases where the server supports a large number of certificate authorities
+it makes sense not to advertise all of the names to save bandwidth. That can
+be controlled using the function 
@funcref{gnutls_certificate_send_x509_rdn_sequence}. 
+This however will have the side-effect of not restricting the client to 
certificates
+signed by server's acceptable signers.
+
address@hidden
+
address@hidden
+
+
 @node SRP credentials
 @subsection SRP
 
@@ -606,8 +626,8 @@ messages may arrive out of order.
 
 The @funcref{gnutls_record_check_pending} helper function is available to 
 allow checking whether data are available to be read in a @acronym{GnuTLS} 
session 
-buffers. Note that this function complements but does not replace 
@code{select()},
-i.e., @funcref{gnutls_record_check_pending} reports no data to be read, 
@code{select()}
+buffers. Note that this function complements but does not replace 
@funcintref{select},
+i.e., @funcref{gnutls_record_check_pending} reports no data to be read, 
@funcintref{select}
 should be called to check for data in the network buffers.
 
 @showfuncdesc{gnutls_record_check_pending}
@@ -806,12 +826,64 @@ will allow V1 CAs in chains.
 @section Advanced and other topics
 
 @menu
+* Session resumption::
 * Parameter generation::
 * Keying Material Exporters::
 * Channel Bindings::
+* Interoperability::
 * Compatibility with the OpenSSL library::
 @end menu
 
address@hidden Session resumption
address@hidden Session resumption
address@hidden resuming sessions
address@hidden session resumption
+
address@hidden Client side
+
+To reduce time and roundtrips spent in a handshake the client can   
+utilize session resumption. This requires the client to retrieve and store
+the session parameters. On new sessions to the same server the parameters must
+be re-associated with sessions using @funcref{gnutls_session_set_data}.
+
address@hidden,gnutls_session_get_id,gnutls_session_set_data}
+
+Keep in mind that sessions might be expired after some time, 
+and it may be normal for a server not to resume a session
+even it was requested.  That is to prevent temporal session keys
+from becoming long-term keys. Also note that as a client you must enable, 
using the
+priority functions, at least the algorithms used in the last session.
+
+It is highly recommended clients to enable the session ticket extension using 
address@hidden in order to allow resumption with 
+servers that do not store any state.
+
address@hidden
+
+
address@hidden Server side
+
+In order to support resumption a server might do it either by storing
+the session security parameters in a local database or by using session
+tickets (see @ref{Session tickets}) to delegate storage to the client. Because
+session tickets might not be supported by all clients, servers
+might combine the two methods.
+
+A storing server needs to specify callback functions to store, retrieve and 
delete session data. These can be
+registered with the functions below. The stored sessions in the database can 
be checked using @funcref{gnutls_db_check_entry}
+for expiration.
+
address@hidden,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function}
address@hidden
+
+A server utilizing tickets should use
address@hidden to generate a ticket encryption key and
+call @funcref{gnutls_session_ticket_enable_server} to enable the extension.
+
address@hidden
address@hidden
+
+
 @node Parameter generation
 @subsection Parameter generation
 @cindex parameter generation
@@ -922,6 +994,32 @@ Note that it must be run after a successful TLS handshake.
 @}
 @end smallexample
 
address@hidden Interoperability
address@hidden Interoperability
+
+The @acronym{TLS} protocols support many ciphersuites, extensions and version
+numbers. As a result, few implementations are 
+not able to properly interoperate once faced with extensions or version 
protocols
+they do not support and understand. The @acronym{TLS} protocol allows for a
+graceful downgrade to the commonly supported options, but practice shows 
+it is not always implemented correctly. 
+
+Because there is no way to achieve maximum interoperability with broken peers
+without sacrificing security, @acronym{GnuTLS} ignores such peers by default. 
+This might not be acceptable in cases where maximum compatibility
+is required. Thus we allow enabling compatibility with broken peers using
+priority strings (see @ref{Priority Strings}). An example priority string that
+is known to provide wide compatibility even with broken peers
+is shown below:
address@hidden
+NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
address@hidden verbatim
+This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and
+will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol
+options that are known to cause compatibility problems. Note however that
+there are known attacks against those protocol versions and
+this mode trades security for compatibility.
+
 @node Compatibility with the OpenSSL library
 @subsection Compatibility with the OpenSSL library
 @cindex OpenSSL
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 9bc63a0..5f5f77d 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -304,7 +304,6 @@ the handshake protocol, i.e., the ciphersuite negotiation.
 * Authentication::              TLS authentication.
 * Client Authentication::       Requesting a certificate from the client.
 * Resuming Sessions::           Reusing previously established keys.
-* Interoperability::            About interoperability with other 
implementations.
 @end menu
 
 
@@ -454,92 +453,27 @@ with the credential types is shown in 
@ref{tab:key-exchange-cred}.
 In the case of ciphersuites that use certificate authentication, the
 authentication of the client is optional in @acronym{TLS}.  A server
 may request a certificate from the client using the
address@hidden function. If a certificate
-is to be requested from the client during the handshake, the server
-will send a certificate request message that contains a list of
-acceptable certificate signers. In @acronym{GnuTLS} the certificate
-signers list is constructed using the trusted certificate authorities
-by the server. That is the ones set using the following functions.
-
address@hidden,gnutls_certificate_set_x509_trust_mem}
-
address@hidden
-
-In cases where the server supports a large number of certificate authorities
-it makes sense not to advertise all of the names to save bandwidth. That can
-be controlled using the function 
@funcref{gnutls_certificate_send_x509_rdn_sequence}. 
-This however will have the side-effect of not restricting the client to 
certificates
-signed by server's acceptable signers.
-
address@hidden
address@hidden function. We elaborate 
+in @ref{Certificate credentials}.
 
 @node Resuming Sessions
 @subsection Resuming sessions
 @anchor{resume}
 @cindex resuming sessions
address@hidden session resuming
address@hidden session resumption
 
 The TLS handshake process performs expensive calculations
 and a busy server might easily be put under load. To 
-reduce the load, clients may use session resumption. Session
-resumption is a feature of the @acronym{TLS} protocol which allows a
+reduce the load, session resumption may be used. This
+is a feature of the @acronym{TLS} protocol which allows a
 client to connect to a server after a successful handshake, without
 the expensive calculations.  This is achieved by re-using the previously
-established keys. @acronym{GnuTLS} supports this feature, and the
-example in @ref{ex:resume-client} illustrates a typical use of it.
-
-Keep in mind that sessions might be expired after some time, 
-thus it may be normal for a server not to resume a session
-even if you requested that.  That is to prevent temporal session keys
-from becoming long-term keys. Also note that as a client you must enable, 
using the
-priority functions, at least the algorithms used in the last session.
-
-The resuming capability, mostly in the server side, is one of the
-problems of a thread-safe TLS implementations. The problem is that all
-threads must share information in order to be able to resume
-sessions. The gnutls approach is, in case of a client, to leave all
-the burden of resuming to the client, i.e., copy and keep the
-necessary parameters. The relevant functions are listed below.
-
address@hidden,gnutls_session_get_id,gnutls_session_set_data}
-
-Server side is different. A server needs to specify callback
-functions which store, retrieve and delete session data. These can be
-registered with the functions shown below.
-
address@hidden,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function}
-
-It might also be useful to be able to check for expired sessions in
-order to remove them, and save space. The function
address@hidden is provided for that reason.
-
address@hidden
-
address@hidden Interoperability
address@hidden Interoperability
-
-The @acronym{TLS} protocols support many ciphersuites, extensions and version
-numbers. As a result, few implementations are 
-not able to properly interoperate once faced with extensions or version 
protocols
-they do not support and understand. The @acronym{TLS} protocol allows for a
-graceful downgrade to the commonly supported options, but practice shows 
-it is not always implemented correctly. 
-
-Because there is no way to achieve maximum interoperability with broken peers
-without sacrificing security, @acronym{GnuTLS} ignores such peers by default. 
-This might not be acceptable in cases where maximum compatibility
-is required. Thus we allow enabling compatibility with broken peers using
-priority strings (see @ref{Priority Strings}). An example priority string that
-is known to provide wide compatibility even with broken peers
-is shown below:
address@hidden
-NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
address@hidden verbatim
-This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and
-will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol
-options that are known to cause compatibility problems. Note however that
-there are known attacks against those protocol versions and
-this mode trades security for compatibility.
+established keys, meaning the server needs to store the state of established
+connections (unless session tickets are used -- @ref{Session tickets}).
+
+Session resumption is an integral part of @acronym{GnuTLS}, and 
address@hidden resumption} and @ref{ex:resume-client} illustrate typical 
+uses of it.
 
 @node TLS Extensions
 @section TLS extensions
@@ -603,19 +537,14 @@ client.
 @cindex session tickets
 @cindex tickets
 
-To resume a TLS session the server normally store some state.  This
-complicates deployment, and typical situations the client can cache
-information and send it to the server instead.  The Session Ticket
+To resume a TLS session the server normally store session parameters.  This
+complicates deployment, and could be avoiding by delegating the storage
+to the client. Because session parameters are sensitive they are encrypted
+and authenticated with a key only known to the server and then sent to the
+client. The Session Ticket
 extension implements this idea, and it is documented in
 RFC 5077 @xcite{TLSTKT}.
 
-Clients can enable support for TLS tickets with
address@hidden and servers use
address@hidden to generate a key and
address@hidden to enable the extension.
-Clients resume sessions using the normal session resumption procedure (see 
@ref{resume}).
-
address@hidden,gnutls_session_ticket_enable_server,gnutls_session_ticket_enable_client}
 
 @node Safe renegotiation
 @subsection Safe renegotiation
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index de5cda8..b2d1d5a 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -78,7 +78,7 @@ my $match = "[\\w\\d-\\.\\/address@hidden:\_\\\\\#]";
 my $spacematch = "[\\s\\w\\d-\\.\\/address@hidden:]";
 my $mathmatch = "[\\s\\w\\d-\\.\\/\\:\\(\\)\\+\\/\\^\\'\\=\{\}\\\\\\,]";
 my $underscorematch = "[\\s\\w\\d-\\.\\/address@hidden:\\~]";
-my $codematch = "[\\s\\w\\d-\\.\\/address@hidden:\\-\\\"\+\\%\\,]";
+my $codematch = "[\\s\\w\\d-\\.\\/address@hidden:\\-\\\"\+\\%\\#\\,]";
 my $extcodematch = "[\\s\\w\\d-\\.\\/address@hidden:\\-\\\"\+\\%\\,\\{\\}]";
 my ($line, $prev_mode);
 my ($verbatim, $label);
@@ -222,8 +222,8 @@ multitable:
                        }
                }
 
-               $line =~ s/address@hidden (.+)/\\paragraph{$1}/g;
-               $line =~ s/address@hidden (.+)/\\subsection{$1}/g;
+               $line =~ s/address@hidden (.+)/\\subsubsection\*{$1}/g;
+               $line =~ s/address@hidden (.+)/\\subsection\*{$1}/g;
 
                 if ($line =~ s/address@hidden (.+)/\\section{$1}/g) {
                        if ($label ne '') {


hooks/post-receive
-- 
GNU gnutls



reply via email to

[Prev in Thread] Current Thread [Next in Thread]