updated documentation to allow latex output.

1 files changed, 49 insertions, 53 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index 9336ab5834..9a9bb38598 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -35,7 +35,7 @@ are:
 
 @acronym{X.509} certificates contain the public parameters, of a
 public key algorithm, and an authority's signature, which proves the
-authenticity of the parameters.  @xref{The X.509 trust model}, for
+authenticity of the parameters.  See @ref{The X.509 trust model}, for
 more information on @acronym{X.509} protocols.
 
 @subsection Authentication Using @acronym{OpenPGP} Keys
@@ -47,9 +47,8 @@ whether a signer is trusted the key is considered trusted or not.
 @acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
 based on the @xcite{TLSPGP} proposal.
 
-@xref{The OpenPGP trust model}, for more information about the
-@acronym{OpenPGP} trust model.  For a more detailed introduction to
-@acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}.
+More information on the @acronym{OpenPGP} trusted model is provided in @ref{The OpenPGP trust model}.
+For a more detailed introduction to @acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}.
 
 @subsection Using Certificate Authentication
 
@@ -62,8 +61,8 @@ 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
 @acronym{TLS} session is initialized, in a certificate credentials
 structure. This should be done by using
-@ref{gnutls_certificate_set_x509_key_file} or
-@ref{gnutls_certificate_set_openpgp_key_file} depending on the
+@funcref{gnutls_certificate_set_x509_key_file} or
+@funcref{gnutls_certificate_set_openpgp_key_file} depending on the
 certificate type.  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
@@ -77,26 +76,26 @@ callback can be set using the functions:
 
 @itemize
 
-@item @ref{gnutls_certificate_server_set_retrieve_function}
+@item @funcref{gnutls_certificate_server_set_retrieve_function}
 
-@item @ref{gnutls_certificate_client_set_retrieve_function}
+@item @funcref{gnutls_certificate_client_set_retrieve_function}
 
 @end itemize
 
 Clients and servers that will select certificates using callback
 functions should select a certificate according the peer's signature
 algorithm preferences. To get those preferences use
-@ref{gnutls_sign_algorithm_get_requested}.
+@funcref{gnutls_sign_algorithm_get_requested}.
 
 Certificate verification is possible by loading the trusted
 authorities into the credentials structure by using
-@ref{gnutls_certificate_set_x509_trust_file} or
-@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
+@funcref{gnutls_certificate_set_x509_trust_file} or
+@funcref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
 keys. Note however that the peer's certificate is not automatically
-verified, you should call @ref{gnutls_certificate_verify_peers2},
+verified, you should call @funcref{gnutls_certificate_verify_peers2},
 after a successful handshake, to verify the signatures of the
 certificate.  An alternative way, which reports a more detailed
-verification output, is to use @ref{gnutls_certificate_get_peers} to
+verification output, is to use @funcref{gnutls_certificate_get_peers} to
 obtain the raw certificate of the peer and verify it using the
 functions discussed in @ref{The X.509 trust model}.
 
@@ -211,7 +210,7 @@ and the server using a certificate.
 The advantage of @acronym{SRP} authentication, over other proposed
 secure password authentication schemes, is that @acronym{SRP} does not
 require the server to hold the user's password.  This kind of
-protection is similar to the one used traditionally in the @emph{UNIX}
+protection is similar to the one used traditionally in the @acronym{UNIX}
 @file{/etc/passwd} file, where the contents of this file did not cause
 harm to the system security if they were revealed.  The @acronym{SRP}
 needs instead of the plain password something called a verifier, which
@@ -223,8 +222,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 paper
-@xcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:
+The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP}.  
+The supported @acronym{SRP} key exchange methods are:
 
 @table @code
 
@@ -243,9 +242,9 @@ authenticated using a certificate with RSA parameters.
 
 If clients supporting @acronym{SRP} know the username and password
 before the connection, should initialize the client credentials and
-call the function @ref{gnutls_srp_set_client_credentials}.
+call the function @funcref{gnutls_srp_set_client_credentials}.
 Alternatively they could specify a callback function by using the
-function @ref{gnutls_srp_set_client_credentials_function}.  This has
+function @funcref{gnutls_srp_set_client_credentials_function}.  This has
 the advantage that allows probing the server for @acronym{SRP}
 support.  In that case the callback function will be called twice per
 handshake.  The first time is before the ciphersuite is negotiated,
@@ -260,27 +259,27 @@ In server side the default behaviour 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 can be specified using the
-@ref{gnutls_srp_set_server_credentials_file}.  If a different
+@funcref{gnutls_srp_set_server_credentials_file}.  If a different
 password file format is to be used, then the function
-@ref{gnutls_srp_set_server_credentials_function}, should be called,
+@funcref{gnutls_srp_set_server_credentials_function}, should be called,
 in order to set an appropriate callback.
 
 Some helper functions such as
 
 @itemize
 
-@item @ref{gnutls_srp_verifier}
+@item @funcref{gnutls_srp_verifier}
 
-@item @ref{gnutls_srp_base64_encode}
+@item @funcref{gnutls_srp_base64_encode}
 
-@item @ref{gnutls_srp_base64_decode}
+@item @funcref{gnutls_srp_base64_decode}
 
 @end itemize
 
 are included in @acronym{GnuTLS}, and can be 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.  @xref{srptool}, for more information.
+also included.  See @ref{srptool}, for more information.
 
 
 @node Authentication using PSK
@@ -292,8 +291,8 @@ usernames and binary keys. This protocol avoids making use of public
 key infrastructure and expensive calculations, thus it is suitable for
 constraint clients.
 
-The implementation in @acronym{GnuTLS} is based on paper
-@xcite{TLSPSK}.  The supported @acronym{PSK} key exchange methods are:
+The implementation in @acronym{GnuTLS} is based on @xcite{TLSPSK}.  
+The supported @acronym{PSK} key exchange methods are:
 
 @table @code
 
@@ -308,9 +307,9 @@ exchange.  This method offers perfect forward secrecy.
 
 Clients supporting @acronym{PSK} should supply the username and key
 before the connection to the client credentials by calling the
-function @ref{gnutls_psk_set_client_credentials}.  Alternatively they
+function @funcref{gnutls_psk_set_client_credentials}.  Alternatively they
 could specify a callback function by using the function
-@ref{gnutls_psk_set_client_credentials_function}.  This has the
+@funcref{gnutls_psk_set_client_credentials_function}.  This has the
 advantage that the callback will be called only if @acronym{PSK} has
 been negotiated.
 
@@ -318,24 +317,24 @@ In server side the default behaviour of @acronym{GnuTLS} is to read
 the usernames and @acronym{PSK} keys from a password file. The
 password file should contain usernames and keys in hexadecimal
 format. The name of the password file can be stored to the credentials
-structure by calling @ref{gnutls_psk_set_server_credentials_file}.  If
+structure by calling @funcref{gnutls_psk_set_server_credentials_file}.  If
 a different password file format is to be used, then the function
-@ref{gnutls_psk_set_server_credentials_function}, should be used
+@funcref{gnutls_psk_set_server_credentials_function}, should be used
 instead.
 
 The server can help the client chose a suitable username and password,
 by sending a hint.  In the server, specify the hint by calling
-@ref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
+@funcref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
 the hint, for example in the callback function, using
-@ref{gnutls_psk_client_get_hint}.
+@funcref{gnutls_psk_client_get_hint}.
 
 Some helper functions such as:
 
 @itemize
 
-@item @ref{gnutls_hex_encode}
+@item @funcref{gnutls_hex_encode}
 
-@item @ref{gnutls_hex_decode}
+@item @funcref{gnutls_hex_decode}
 
 @end itemize
 
@@ -349,41 +348,38 @@ maintain @acronym{PSK} keys.
 In @acronym{GnuTLS} every key exchange method is associated with a
 credentials type. So in order to enable to enable a specific method,
 the corresponding credentials type should be initialized and set using
-@ref{gnutls_credentials_set}.  A mapping is shown below.
+@funcref{gnutls_credentials_set}.  A mapping is shown below.
 
 Key exchange algorithms and the corresponding credential types:
 
-@multitable @columnfractions .3 .3 .3
+@multitable @columnfractions .4 .25 .25
 
 @headitem Key exchange @tab Client credentials @tab Server credentials
 
-@item @code{KX_RSA}
-@item @code{KX_DHE_RSA}
-@item @code{KX_DHE_DSS}
-@item @code{KX_ECDHE_RSA}
-@item @code{KX_ECDHE_ECDSA}
-@item @code{KX_RSA_EXPORT}
+@item @code{KX_RSA},
+@code{KX_DHE_RSA},
+@code{KX_DHE_DSS},
+@code{KX_ECDHE_RSA},
+@code{KX_ECDHE_ECDSA},
+@code{KX_RSA_EXPORT}
 @tab @code{CRD_CERTIFICATE}
 @tab @code{CRD_CERTIFICATE}
 
-@item @code{KX_SRP_RSA}
+@item @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
 @tab @code{CRD_SRP}
-@tab @code{CRD_SRP}
-@item @code{KX_SRP_DSS}
-@tab
 @tab @code{CRD_CERTIFICATE}
 
 @item @code{KX_SRP}
 @tab @code{CRD_SRP}
 @tab @code{CRD_SRP}
 
-@item @code{KX_ANON_DH}
-@item @code{KX_ANON_ECDH}
+@item @code{KX_ANON_DH},
+@code{KX_ANON_ECDH}
 @tab @code{CRD_ANON}
 @tab @code{CRD_ANON}
 
-@item @code{KX_PSK}
-@item @code{KX_DHE_PSK}
+@item @code{KX_PSK},
+@code{KX_DHE_PSK}, @code{KX_ECDHE_PSK}
 @tab @code{CRD_PSK}
 @tab @code{CRD_PSK}
 
@@ -396,15 +392,15 @@ 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 @ref{gnutls_certificate_set_dh_params} and
-@ref{gnutls_certificate_set_rsa_export_params} can be used to
+functions like @funcref{gnutls_certificate_set_dh_params} and
+@funcref{gnutls_certificate_set_rsa_export_params} 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
-@ref{gnutls_certificate_set_params_function}.  An example is shown
+@funcref{gnutls_certificate_set_params_function}.  An example is shown
 below.
 
 @example