[SCM] GNU gnutls branch, master, updated. gnutls_3_0_0-34-ge434950

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

The branch, master has been updated
       via  e4349502a4e7122469720944344aeded87a35dd8 (commit)
      from  18dc39549f3d7a52c42595acb1d872947d472ed3 (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 e4349502a4e7122469720944344aeded87a35dd8
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