[SCM] GNU gnutls branch, gnutls_3_0_x, updated. gnutls_3_0_0-34-gb21e796

[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=b21e7965a268cd9f27bbfc573b6d456a54a34fdc

The branch, gnutls_3_0_x has been updated
       via  b21e7965a268cd9f27bbfc573b6d456a54a34fdc (commit)
      from  54c67e6e4a7ff27b1fe6dffac7d26c75d0f87f7d (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 b21e7965a268cd9f27bbfc573b6d456a54a34fdc
Author: Nikos Mavrogiannopoulos <address@hidden>
Date:   Wed Aug 10 18:31:23 2011 +0200

    updated documentation

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

Summary of changes:
 doc/cha-auth.texi            |  189 +++++++++++++++++-------------------------
 doc/cha-gtls-app.texi        |    6 ++
 lib/gnutls_psk.c             |   15 ++-
 lib/gnutls_x509.c            |   10 +-
 lib/openpgp/gnutls_openpgp.c |    8 +-
 5 files changed, 101 insertions(+), 127 deletions(-)

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index 1006493..1d1209a 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -21,10 +21,13 @@ are:
 The rule for each method is to allocate a credentials
 structure containing data required for authentication and
 associate that structure with the session using
address@hidden In the next paragraphs
address@hidden Various authentication methods might
+require additional data to be stored in the credential structures,
+such as ephemeral Diffie-Hellman parameters etc.
+In the next paragraphs
 we elaborate on supported authentication methods.
 
address@hidden
address@hidden
 
 @menu
 * Certificate authentication::
@@ -32,7 +35,6 @@ we elaborate on supported authentication methods.
 * Authentication using SRP::
 * Authentication using PSK::
 * Authentication and credentials::
-* Parameters stored in credentials::
 @end menu
 
 @node Certificate authentication
@@ -63,15 +65,18 @@ For a more detailed introduction to @acronym{OpenPGP} and 
@acronym{GnuPG} see @x
 In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
 certificates are part of the certificate authentication and thus are
 handled using a common API.
-
 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. The certificate and key pair should be loaded, before any
address@hidden session is initialized, in a certificate credentials
-structure. This should be done by using
address@hidden or
address@hidden depending on the
-certificate type.  In the @acronym{X.509} case, the functions will
+pair. 
+
address@hidden,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.
+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
 certificate certifies the one before it. The trusted authority's
@@ -82,23 +87,24 @@ already.
 
 @showfuncdesc{gnutls_certificate_set_x509_key_file}
 
address@hidden
-
-As an alternative, a callback may be used so the server or the client
-specifies the certificate and the key at the handshake time
-using @funcref{gnutls_certificate_set_retrieve_function}. 
+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.
 In that case a certificate should be selected according the peer's signature
 algorithm preferences. To get those preferences use
address@hidden
address@hidden Both functions are shown below.
 
address@hidden
address@hidden
+
address@hidden
 
 
 Certificate verification is possible by loading the trusted
 authorities into the credentials structure by using
address@hidden or
address@hidden for openpgp
-keys. Note however that the peer's certificate is not automatically
+the following functions, applicable to X.509 and OpenPGP certificates.
+
address@hidden,gnutls_certificate_set_openpgp_keyring_file}
+
+Note however that the peer's certificate is not automatically
 verified, you should call @funcref{gnutls_certificate_verify_peers2},
 after a successful handshake or during if 
@funcref{gnutls_certificate_set_verify_function}
 has been used, to verify the certificate's signature.
@@ -109,29 +115,26 @@ functions discussed in @ref{The X.509 trust model}.
 
 @showfuncdesc{gnutls_certificate_verify_peers2}
 
-In a handshake, the negotiated cipher suite depends on the
-certificate's parameters, so not all key exchange methods will be
+In a handshake, the negotiated cipher suite also depends on the
+certificate's parameters, so some key exchange methods might not be
 available with some certificates. @acronym{GnuTLS} will disable
 ciphersuites that are not compatible with the key, or the enabled
 authentication methods.  For example keys marked as sign-only, will
-not be able to access the plain RSA ciphersuites, but only the
address@hidden ones. It is recommended not to use RSA keys for both
-signing and encryption. If possible use the same key for the
address@hidden and @code{RSA_EXPORT} ciphersuites, which use signing,
-and a different key for the plain RSA ciphersuites, which use
-encryption.  All the key exchange methods shown below are available in
-certificate authentication.
+not be able to access the plain RSA ciphersuites, that require
+decryption. It is not recommended to use RSA keys for both
+signing and encryption. If possible use a different key for the
address@hidden which uses signing and @code{RSA} that requires decryption.
+All the key exchange methods shown in @ref{tab:key-exchange} are
+available in certificate authentication.
 
 @showfuncdesc{gnutls_certificate_set_verify_function}
 
 Note that the DHE key exchange methods are generally
 address@hidden really depends on the group used.  Primes with
 lesser bits are always faster, but also easier to break.  See @ref{Selecting 
cryptographic key sizes}
-for the acceptable security levels.} than plain RSA and require Diffie
-Hellman parameters to be generated and associated with a credentials
-structure, by the server. For more information check the @ref{Parameter 
generation}
-section. The key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
-certificates are shown in @ref{tab:key-exchange}.
+for the acceptable security levels.} 
+and require Diffie-Hellman parameters to be generated and associated with a 
credentials
+structure, by the server (see @ref{Parameter generation}).
 
 @float Table,tab:key-exchange
 @multitable @columnfractions .3 .7
@@ -196,7 +199,12 @@ require Diffie-Hellman parameters to be generated by the 
server and
 associated with an anonymous credentials structure. Check
 @ref{Parameter generation} for more information.
 
-Supported anonymous key exchange algorithms:
+The initialization functions for the credentials are shown below.
+
address@hidden,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials}
+
+
+The supported anonymous key exchange algorithms are:
 
 @table @code
 
@@ -214,7 +222,7 @@ efficient than ANON_DH on equivalent security levels.
 @cindex @acronym{SRP} authentication
 
 Authentication via the Secure Remote Password protocol,
address@hidden@address@hidden is described in @xcite{RFC2945}},
address@hidden (see @xcite{RFC2945} for a description of SRP),
 is supported.  The @acronym{SRP} key exchange is an extension to the
 @acronym{TLS} protocol, and it is a password based authentication
 (unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates).
@@ -237,8 +245,8 @@ the system's users passwords with the @acronym{SRP} password
 files. That way @acronym{SRP} authentication could be used for all the
 system's users.
 
-The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP}.  
-The supported @acronym{SRP} key exchange methods are:
+The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP} and
+the supported @acronym{SRP} key exchange methods are:
 
 @table @code
 
@@ -255,29 +263,34 @@ authenticated using a certificate with RSA parameters.
 
 @end table
 
-If clients supporting @acronym{SRP} know the username and password
-before the connection, should initialize client credentials and
-call @funcref{gnutls_srp_set_client_credentials}.
+The initialization functions in SRP credentials differ between
+client and server.
+
address@hidden,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials}
+
+Clients supporting @acronym{SRP} should set the username and password
+prior to connection, to the credentials structure.
 Alternatively @funcref{gnutls_srp_set_client_credentials_function}
-may be used to specify a callback function.
-The callback will be called once during the @acronym{TLS} handshake.
+may be used instead, to specify a callback function that should return the
+SRP username and password.
+The callback is called once during the @acronym{TLS} handshake.
 
address@hidden,gnutls_srp_set_client_credentials_function}
address@hidden
+
address@hidden
 
 In server side the default behavior of @acronym{GnuTLS} is to read
 the usernames and @acronym{SRP} verifiers from password files. These
-password files are the ones used by the @emph{Stanford srp libraries}
-and @funcref{gnutls_srp_set_server_credentials_file} can be used to
-specify them. If a different
-password file format is to be used, then 
+password file format is compatible the with the @emph{Stanford srp libraries}
+format.  If a different password file format is to be used, then 
 @funcref{gnutls_srp_set_server_credentials_function} should be called,
-to set an appropriate callback.
+to set an appropriate callback. 
 
 @showfuncdesc{gnutls_srp_set_server_credentials_file}
 
 @showfuncdesc{gnutls_srp_set_server_credentials_function}
 
-Helper functions are included in @acronym{GnuTLS}, and can be used to generate 
and
+Other helper functions are included in @acronym{GnuTLS}, used to generate and
 maintain @acronym{SRP} verifiers and password files.  A program to
 manipulate the required parameters for @acronym{SRP} authentication is
 also included.  See @ref{srptool}, for more information.
@@ -314,15 +327,21 @@ exchange.  This method offers perfect forward secrecy.
 
 @end table
 
+The initialization functions in PSK credentials differ between
+client and server.
+
address@hidden,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials}
+
 Clients supporting @acronym{PSK} should supply the username and key
-before the TLS session is established by calling 
address@hidden  Alternatively 
+before a TLS session is established.  Alternatively 
 @funcref{gnutls_psk_set_client_credentials_function} can be used to
 specify a callback function. This has the
 advantage that the callback will be called only if @acronym{PSK} has
 been negotiated.
 
address@hidden,gnutls_psk_set_client_credentials_function}
address@hidden
+
address@hidden
 
 In server side the default behavior of @acronym{GnuTLS} is to read
 the usernames and @acronym{PSK} keys from a password file. The
@@ -356,9 +375,11 @@ maintain @acronym{PSK} keys.
 @section Authentication and credentials
 
 In @acronym{GnuTLS} every key exchange method is associated with a
-credentials type. So in order to enable to enable a specific method,
+credentials type. For a key exchange method to be available it
+must be listed as a priority string (see @ref{Priority Strings}) and
 the corresponding credentials type should be initialized and set using
address@hidden  A mapping is shown in @ref{tab:key-exchange-cred}.
address@hidden  A mapping of the key exchange methods
+with the credential types is shown in @ref{tab:key-exchange-cred}.
 
 @float Table,tab:key-exchange-cred
 @multitable @columnfractions .4 .25 .25
@@ -396,61 +417,3 @@ the corresponding credentials type should be initialized 
and set using
 @caption{Key exchange algorithms and the corresponding credential types.}
 @end float
 
address@hidden Parameters stored in credentials
address@hidden Parameters stored in credentials
-
-Several parameters such as the ones used for Diffie-Hellman
-authentication are stored within the credentials structures, so all
-sessions can access them. Those parameters are stored in structures
-such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and
-functions like @funcref{gnutls_certificate_set_dh_params} and
address@hidden can be used to
-associate those parameters with the given credentials structure.
-
-Since those parameters need to be renewed from time to time and a
-global structure such as the credentials, may not be easy to modify
-since it is accessible by all sessions, an alternative interface is
-available using a callback function.  This can be set using the
address@hidden  An example is shown
-below.
-
address@hidden
-#include <gnutls.h>
-
-gnutls_rsa_params_t rsa_params;
-gnutls_dh_params_t dh_params;
-
-/* This function will be called once a session requests DH
- * or RSA parameters. The parameters returned (if any) will
- * be used for the first handshake only.
- */
-static int get_params( gnutls_session_t session,
-        gnutls_params_type_t type,
-        gnutls_params_st *st)
address@hidden
-   if (type == GNUTLS_PARAMS_RSA_EXPORT)
-      st->params.rsa_export = rsa_params;
-   else if (type == GNUTLS_PARAMS_DH)
-      st->params.dh = dh_params;
-   else return -1;
-
-   st->type = type;
-   /* do not deinitialize those parameters.
-    */
-   st->deinit = 0;
-
-   return 0;
address@hidden
-
-int main()
address@hidden
-   gnutls_certificate_credentials_t cert_cred;
-
-   initialize_params();
-
-   /* ...
-    */
-
-   gnutls_certificate_set_params_function( cert_cred, get_params);
address@hidden
address@hidden example
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index d4dec01..69b17b1 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -400,6 +400,12 @@ following functions can be used for these parameters.
 
 
@showfuncD{gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1}
 
+To allow renewal of the parameters within an application without
+accessing the credentials, which are a shared structure,
+an alternative interface is available using a callback function.  
+
address@hidden
+
 
 @node Keying Material Exporters
 @subsection Keying material exporters
diff --git a/lib/gnutls_psk.c b/lib/gnutls_psk.c
index 8c37618..6dad830 100644
--- a/lib/gnutls_psk.c
+++ b/lib/gnutls_psk.c
@@ -58,7 +58,8 @@ gnutls_psk_free_client_credentials 
(gnutls_psk_client_credentials_t sc)
  * This structure is complex enough to manipulate directly thus this
  * helper function is provided in order to allocate it.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_psk_allocate_client_credentials (gnutls_psk_client_credentials_t * sc)
@@ -86,7 +87,8 @@ gnutls_psk_allocate_client_credentials 
(gnutls_psk_client_credentials_t * sc)
  * key can be either in raw byte format or in Hex format (without the
  * 0x prefix).
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_psk_set_client_credentials (gnutls_psk_client_credentials_t res,
@@ -166,7 +168,8 @@ gnutls_psk_free_server_credentials 
(gnutls_psk_server_credentials_t sc)
  * This structure is complex enough to manipulate directly thus this
  * helper function is provided in order to allocate it.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_psk_allocate_server_credentials (gnutls_psk_server_credentials_t * sc)
@@ -189,7 +192,8 @@ gnutls_psk_allocate_server_credentials 
(gnutls_psk_server_credentials_t * sc)
  * %gnutls_psk_server_credentials_t structure.  This password file
  * holds usernames and keys and will be used for PSK authentication.
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_psk_set_server_credentials_file (gnutls_psk_server_credentials_t
@@ -229,7 +233,8 @@ gnutls_psk_set_server_credentials_file 
(gnutls_psk_server_credentials_t
  * the client to help it chose a good PSK credential (i.e., username
  * and password).
  *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  *
  * Since: 2.4.0
  **/
diff --git a/lib/gnutls_x509.c b/lib/gnutls_x509.c
index 0808799..a80ec0c 100644
--- a/lib/gnutls_x509.c
+++ b/lib/gnutls_x509.c
@@ -1347,7 +1347,7 @@ cleanup:
 
 /**
  * gnutls_certificate_set_x509_trust_file:
- * @res: is a #gnutls_certificate_credentials_t structure.
+ * @cred: is a #gnutls_certificate_credentials_t structure.
  * @cafile: is a file containing the list of trusted CAs (DER or PEM list)
  * @type: is PEM or DER
  *
@@ -1368,7 +1368,7 @@ cleanup:
  * error.
  **/
 int
-gnutls_certificate_set_x509_trust_file (gnutls_certificate_credentials_t res,
+gnutls_certificate_set_x509_trust_file (gnutls_certificate_credentials_t cred,
                                         const char *cafile,
                                         gnutls_x509_crt_fmt_t type)
 {
@@ -1379,7 +1379,7 @@ gnutls_certificate_set_x509_trust_file 
(gnutls_certificate_credentials_t res,
 #ifdef ENABLE_PKCS11
   if (strncmp (cafile, "pkcs11:", 7) == 0)
     {
-      return read_cas_url (res, cafile);
+      return read_cas_url (cred, cafile);
     }
 #endif
 
@@ -1391,9 +1391,9 @@ gnutls_certificate_set_x509_trust_file 
(gnutls_certificate_credentials_t res,
     }
 
   if (type == GNUTLS_X509_FMT_DER)
-    ret = parse_der_ca_mem (res, data, size);
+    ret = parse_der_ca_mem (cred, data, size);
   else
-    ret = parse_pem_ca_mem (res, data, size);
+    ret = parse_pem_ca_mem (cred, data, size);
 
   free (data);
 
diff --git a/lib/openpgp/gnutls_openpgp.c b/lib/openpgp/gnutls_openpgp.c
index 9ae679b..44ba47b 100644
--- a/lib/openpgp/gnutls_openpgp.c
+++ b/lib/openpgp/gnutls_openpgp.c
@@ -499,7 +499,7 @@ gnutls_openpgp_count_key_names (const gnutls_datum_t * cert)
 
 /**
  * gnutls_certificate_set_openpgp_keyring_file:
- * @c: A certificate credentials structure
+ * @cred: A certificate credentials structure
  * @file: filename of the keyring.
  * @format: format of keyring.
  *
@@ -513,14 +513,14 @@ gnutls_openpgp_count_key_names (const gnutls_datum_t * 
cert)
  **/
 int
 gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t
-                                             c, const char *file,
+                                             cred, const char *file,
                                              gnutls_openpgp_crt_fmt_t format)
 {
   gnutls_datum_t ring;
   size_t size;
   int rc;
 
-  if (!c || !file)
+  if (!cred || !file)
     {
       gnutls_assert ();
       return GNUTLS_E_INVALID_REQUEST;
@@ -535,7 +535,7 @@ gnutls_certificate_set_openpgp_keyring_file 
(gnutls_certificate_credentials_t
     }
 
   rc =
-    gnutls_certificate_set_openpgp_keyring_mem (c, ring.data, ring.size,
+    gnutls_certificate_set_openpgp_keyring_mem (cred, ring.data, ring.size,
                                                 format);
 
   free (ring.data);


hooks/post-receive
-- 
GNU gnutls