some updated in documentation

13 files changed, 131 insertions, 81 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index ddac1639d7..7227d8a12c 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -15,7 +15,7 @@ TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex fdl.tex ../../lib/x509/x509-ap
 	macros.tex cover.tex ciphersuites.tex handshake.tex translayer.tex \
 	auth.tex ciphers.tex errors.tex layers.tex alert.tex record.tex \
 	funcs.tex examples.tex ../../libextra/gnutls-extra-api.tex \
-	memory.tex openpgp.tex x509.tex howto.tex openssl.tex \
+	memory.tex cert_auth.tex howto.tex openssl.tex \
 	appendix.tex x509cert.xml.tex pgpcert.xml.tex \
 	programs.tex library.tex certificate.tex record_weaknesses.tex \
 	tlsintro.tex compression.tex $(EXAMPLE_OBJECTS) preface.tex \
diff --git a/doc/tex/auth.tex b/doc/tex/auth.tex
index 4fea3dd6af..48bfc6555e 100644
--- a/doc/tex/auth.tex
+++ b/doc/tex/auth.tex
@@ -10,46 +10,7 @@ The available authentication methods in \gnutls{} are:
  \item SRP authentication
 \end{enumerate}
 
-% x.509 section
-\input{x509}
-
-\begin{figure}[hbtp]
-\index{Key exchange algorithms}
-\begin{tabular}{|l|p{9cm}|}
-\hline
-RSA & The RSA algorithm is used to encrypt a key and send it to the peer.
-The certificate must allow the key to be used for encryption.
-\\
-\hline
-RSA\_EXPORT & The RSA algorithm is used to encrypt a key and send it to the peer.
-In the EXPORT algorithm, the server signs temporary RSA parameters of 512
-bits -- which are considered weak -- and sends them to the client.
-\\
-\hline
-DHE\_RSA & The RSA algorithm is used to sign Ephemeral Diffie Hellman
-parameters which are sent to the peer. The key in the certificate must allow
-the key to be used for signing. Note that key exchange algorithms which use
-Ephemeral Diffie Hellman parameters, offer perfect forward secrecy.
-\\
-\hline
-DHE\_DSS & The DSS algorithm is used to sign Ephemeral Diffie Hellman
-parameters which are sent to the peer. DSS stands for Digital Signature
-Standard.
-\\
-\hline
-\end{tabular}
-
-\caption{Key exchange algorithms for OpenPGP and X.509 certificates.}
-\label{fig:cert}
-
-\end{figure}
-
-
-% openpgp section
-
-\input{openpgp}
-
-
+\input{cert_auth}
 
 \section{Anonymous authentication\index{Anonymous authentication}}
 The anonymous key exchange perform encryption but there is no indication of 
diff --git a/doc/tex/cert_auth.tex b/doc/tex/cert_auth.tex
new file mode 100644
index 0000000000..cef7fc7536
--- /dev/null
+++ b/doc/tex/cert_auth.tex
@@ -0,0 +1,112 @@
+\section{Certificate authentication}
+
+% x.509 section
+\subsection*{Authentication using X.509\index{X.509 certificates} certificates}
+
+X.509 certificates contain the public parameters, 
+of a public key algorithm, and an authority's signature, which proves the
+authenticity of the parameters.
+See section \ref{x509:trust} on page \pageref{x509:trust} for more information
+on X.509 protocols.
+
+% openpgp section
+
+\subsection*{Authentication using OpenPGP\index{OpenPGP!Keys} keys}
+\label{sec:pgp}
+
+OpenPGP keys also contain public parameters of a public key algorithm, and
+signatures from several other parties. Depending on whether a signer is
+trusted the key is considered trusted or not.
+\gnutls{}'s OpenPGP authentication implementation is based on the
+\cite{TLSPGP} proposal.
+
+See \ref{pgp:trust} on page \pageref{pgp:trust} for more information 
+about the OpenPGP trust model. For a more detailed introduction to OpenPGP
+and GnuPG see \cite{GPGH}.
+
+\subsection*{Using certificate authentication}
+
+In \gnutls{} both the OpenPGP and X.509 certificates are part of the
+certificate authentication and thus are handled using a common API.
+\par
+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 \tls{} session is initialized,
+in a certificate credentials structure. This should be done by using
+\printfunc{gnutls_certificate_set_x509_key_file}{gnutls\_certificate\_set\_x509\_key\_file}
+or
+\printfunc{gnutls_certificate_set_openpgp_key_file}{gnutls\_certificate\_set\_openpgp\_key\_file}
+depending on the certificate type. As an alternative, a callback may be used
+so the server or the client set the certificate at the handshake time.
+That callback can be set using
+\printfunc{gnutls_certificate_server_set_retrieve_function}{gnutls\_certificate\_server\_set\_retrieve\_function}
+or
+\printfunc{gnutls_certificate_client_set_retrieve_function}{gnutls\_certificate\_client\_set\_retrieve\_function}
+in case of a client.
+\par
+Certificate verification is possible by loading the trusted authorities
+into the credentials structure by using
+\printfunc{gnutls_certificate_set_x509_trust_file}{gnutls\_certificate\_set\_x509\_trust\_file}
+or
+\printfunc{gnutls_certificate_set_openpgp_keyring_file}{gnutls\_certificate\_set\_openpgp\_keyring\_file}
+for openpgp keys. Note however that the peer's certificate is not automaticaly verified,
+you should call \printfunc{gnutls_certificate_verify_peers}{gnutls\_certificate\_verify\_peers},
+after a successful handshake,
+to verify the signatures of the certificate. An alternative way, which reports
+a more detailed verification output, is to use
+\printfunc{gnutls_certificate_get_peers}{gnutls\_certificate\_get\_peers} to obtain
+the raw certificate of the peer and verify it using the functions discussed in
+section \ref{x509:trust} on page \pageref{x509:trust}. 
+
+\par
+In a handshake, the negotiated key exchange method depends on the 
+certificate's parameters, so not all key exchange methods will be available
+with some certificates. That is a certificate with DSA parameters will not
+be able to use the RSA key exchange method.
+All the key exchange methods shown in \hyperref{figure}{figure }{}{fig:cert} are
+available in certificate authentication. 
+Note that the DHE key exchange methods require Diffie Hellman parameters
+to be generated and associated with a credentials structure. The RSA-EXPORT
+method requires 512 bit RSA parameters, which should also be generated
+and associated with the credentials structure. See the functions:
+\begin{itemize}
+\item \printfunc{gnutls_dh_params_generate2}{gnutls\_dh\_params\_generate2}
+\item \printfunc{gnutls_certificate_set_dh_params}{gnutls\_certificate\_set\_dh\_params}
+\item \printfunc{gnutls_rsa_params_generate2}{gnutls\_rsa\_params\_generate2}
+\item \printfunc{gnutls_certificate_set_rsa_export_params}{gnutls\_certificate\_set\_rsa\_export\_params}
+\end{itemize}
+
+\begin{figure}[hbtp]
+\index{Key exchange algorithms}
+\begin{tabular}{|l|p{9cm}|}
+\hline
+RSA & The RSA algorithm is used to encrypt a key and send it to the peer.
+The certificate must allow the key to be used for encryption.
+\\
+\hline
+RSA\_EXPORT & The RSA algorithm is used to encrypt a key and send it to the peer.
+In the EXPORT algorithm, the server signs temporary RSA parameters of 512
+bits -- which are considered weak -- and sends them to the client.
+\\
+\hline
+DHE\_RSA & The RSA algorithm is used to sign Ephemeral Diffie Hellman
+parameters which are sent to the peer. The key in the certificate must allow
+the key to be used for signing. Note that key exchange algorithms which use
+Ephemeral Diffie Hellman parameters, offer perfect forward secrecy.
+\\
+\hline
+DHE\_DSS & The DSS algorithm is used to sign Ephemeral Diffie Hellman
+parameters which are sent to the peer. The certificate must contain DSA
+parameters to use this key exchange algorithm. DSS stands for Digital Signature
+Standard.
+\\
+\hline
+\end{tabular}
+
+\caption{Key exchange algorithms for OpenPGP and X.509 certificates.}
+\label{fig:cert}
+
+\end{figure}
+
+
diff --git a/doc/tex/certificate.tex b/doc/tex/certificate.tex
index 2f5067bc3c..3a456d453d 100644
--- a/doc/tex/certificate.tex
+++ b/doc/tex/certificate.tex
@@ -25,7 +25,7 @@ on page \pageref{sec:x509api}. Some examples are listed below.
 
 
 
-\subsection{X.509 certificates}
+\subsection*{X.509 certificates}
 An X.509 certificate usually contains information about the certificate
 holder, the signer, a unique serial number, expiration dates etc. Some
 functions of \gnutls{}' API for certificate parsing are:
@@ -45,7 +45,7 @@ is listed below.
 \input{ex-x509-info}
 
 
-\subsection{Verifying X.509 certificate paths}
+\subsection*{Verifying X.509 certificate paths}
 Verifying certificate\index{Verifying certificate paths} paths is important 
 in X.509 authentication. For this purpose the function
 \printfunc{gnutls_x509_crt_verify}{gnutls\_x509\_crt\_verify} is provided. The
@@ -82,7 +82,7 @@ owner is the one you expect. See section \ref{ex:rfc2818} on page \pageref{ex:rf
 for an example.
 
 
-\subsection{PKCS \#10 certificate requests\index{Certificate requests}\index
+\subsection*{PKCS \#10 certificate requests\index{Certificate requests}\index
 {PKCS \#10}}
 A certificate request is a structure, which
 is contains information about an applicant of a certificate service.
@@ -97,7 +97,7 @@ which should return a signed certificate.
 
 \input{ex-crq}
 
-\subsection{PKCS \#12 structures\index{PKCS \#12}}
+\subsection*{PKCS \#12 structures\index{PKCS \#12}}
 A PKCS \#12 structure usually contains a user's private keys and
 certificates. It is commonly used in browsers to export and import
 the user's identities.
@@ -139,7 +139,7 @@ Kevin, for some reason. A reason could be that Bob is lazy enough, and
 signs other people's keys without being sure that they belong to the 
 actual owner.
 
-\subsection{Verifying an OpenPGP key}
+\subsection*{Verifying an OpenPGP key}
 The verification functions of OpenPGP keys, included in \gnutls{}, 
 are simple ones, and do not use the features of the ``web of trust''.
 For that reason, if the verification needs are complex, 
diff --git a/doc/tex/ciphers.tex b/doc/tex/ciphers.tex
index 0cb46e9916..a1d9c30950 100644
--- a/doc/tex/ciphers.tex
+++ b/doc/tex/ciphers.tex
@@ -1,4 +1,4 @@
-\subsection{Encryption algorithms used in the record layer}
+\subsection*{Encryption algorithms used in the record layer}
 \index{Symmetric encryption algorithms}
 Confidentiality in the record layer is achieved by using symmetric block 
 encryption algorithms like {\bf 3DES}, {\bf AES\footnote{AES or Advanced 
diff --git a/doc/tex/ciphersuites.tex b/doc/tex/ciphersuites.tex
index 4899f59b0c..72fe2f8a11 100644
--- a/doc/tex/ciphersuites.tex
+++ b/doc/tex/ciphersuites.tex
@@ -1,4 +1,4 @@
-\subsection{TLS cipher suites}
+\subsection*{TLS cipher suites}
 \par 
 The Handshake Protocol of \tlsI{} negotiates cipher suites 
 of the form \\
diff --git a/doc/tex/compression.tex b/doc/tex/compression.tex
index 3a8e92bc00..6c16e4d9d6 100644
--- a/doc/tex/compression.tex
+++ b/doc/tex/compression.tex
@@ -1,4 +1,4 @@
-\subsection{Compression algorithms used in the record layer}
+\subsection*{Compression algorithms used in the record layer}
 \index{Compression algorithms}
 The TLS' record layer also supports compression. The algorithms
 implemented in \gnutls{} can be found in figure \ref{fig:compression}.
diff --git a/doc/tex/handshake.tex b/doc/tex/handshake.tex
index 283ac70e36..657fef695d 100644
--- a/doc/tex/handshake.tex
+++ b/doc/tex/handshake.tex
@@ -34,7 +34,7 @@ handshake.
 
 \input{ciphersuites}
 
-\subsection{Client authentication}
+\subsection*{Client authentication}
 In the case of ciphersuites that use certificate authentication, the
 authentication\index{Certificate authentication!Client} of the client is
 optional in \tls{}. A server may request a certificate from the client -- using the
@@ -46,7 +46,7 @@ by one of the server's acceptable signers. In \gnutls{} the server's acceptable
 signers list is constructed using the trusted CA certificates in the
 credentials structure.
 
-\subsection{Resuming Sessions\index{Resuming sessions}}
+\subsection*{Resuming Sessions\index{Resuming sessions}}
 \label{resume}
 \par
 The 
@@ -64,7 +64,7 @@ it may be normal for a server not to resume a session even if you requested that
 Also note that you must enable, using the priority functions, at least the
 algorithms used in the last session.
 
-\subsection{Resuming internals}
+\subsection*{Resuming internals}
 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
diff --git a/doc/tex/openpgp.tex b/doc/tex/openpgp.tex
deleted file mode 100644
index 8681cb2608..0000000000
--- a/doc/tex/openpgp.tex
+++ /dev/null
@@ -1,11 +0,0 @@
-\section{Authentication using OpenPGP\index{OpenPGP!Keys} keys}
-\label{sec:pgp}
-
-This authentication method is part of the certificate authentication
-method in \gnutls{}. All the key exchange methods shown in \hyperref{figure}{figure }{}{fig:cert} are
-available in OpenPGP authentication. The \gnutls{}'s implementation is based on the
-\cite{TLSPGP} proposal.
-
-See \ref{pgp:trust} on page \pageref{pgp:trust} for more information 
-about the OpenPGP trust model. For a more detailed introduction to OpenPGP
-and GnuPG see \cite{GPGH}.
diff --git a/doc/tex/preparation.tex b/doc/tex/preparation.tex
index 6d2a66fc31..7afeaf2c99 100644
--- a/doc/tex/preparation.tex
+++ b/doc/tex/preparation.tex
@@ -5,7 +5,7 @@ To use \gnutls{}, you have to perform some changes to your sources and
 your build system. The necessary changes are explained in the following
 subsections.
 
-\subsection{Headers}
+\subsection*{Headers}
 
 All the data types and functions of the \gnutls{} library are defined in
 the header file `gnutls/gnutls.h'. This must be included in all programs that
@@ -14,7 +14,7 @@ make use of the \gnutls{} library.
 The extra functionality of the \gnutlse{} library is available by
 including the header file `gnutls/extra.h' in your programs.
 
-\subsection{Version check}
+\subsection*{Version check}
 It is often desirable to check that the version of `gnutls' used is indeed
 one which fits all requirements.  Even with binary compatibility new
 features may have been introduced but due to problem with the dynamic
@@ -23,7 +23,7 @@ the version is okay right after program startup.
 See the function \printfunc{gnutls_check_version}{gnutls\_check\_version}
 
 
-\subsection{Building the source}
+\subsection*{Building the source}
 
 If you want to compile a source file including the `gnutls/gnutls.h' header
 file, you must make sure that the compiler can find it in the
diff --git a/doc/tex/record_weaknesses.tex b/doc/tex/record_weaknesses.tex
index 75c5696a11..e04f790475 100644
--- a/doc/tex/record_weaknesses.tex
+++ b/doc/tex/record_weaknesses.tex
@@ -1,4 +1,4 @@
-\subsection{Weaknesses and countermeasures}
+\subsection*{Weaknesses and countermeasures}
 \index{TLS protocols!Record}
 
 Some weaknesses that may affect the security of the Record layer have been
diff --git a/doc/tex/tls_extensions.tex b/doc/tex/tls_extensions.tex
index 0c54e2aa1b..23786c1f50 100644
--- a/doc/tex/tls_extensions.tex
+++ b/doc/tex/tls_extensions.tex
@@ -9,7 +9,7 @@ mainly in \cite{TLSEXT}. The extensions supported in \gnutls{} are
 \end{itemize}
 discussed in the subsections that follow.
 
-\subsection{Maximum fragment length negotiation}
+\subsection*{Maximum fragment length negotiation}
 \index{TLS Extensions!Maximum fragment length}
 
 This extension allows a \tlsI{} implementation to negotiate
@@ -21,7 +21,7 @@ and the
 \printfunc{gnutls_record_get_max_size}{gnutls\_record\_get\_max\_size}
 functions.
 
-\subsection{Server name indication}
+\subsection*{Server name indication}
 \index{TLS Extensions!Server name indication}
 
 A common problem in HTTPS servers is the fact that the \tls{}
diff --git a/doc/tex/x509.tex b/doc/tex/x509.tex
deleted file mode 100644
index ee078515a2..0000000000
--- a/doc/tex/x509.tex
+++ /dev/null
@@ -1,12 +0,0 @@
-\section{Authentication using X.509\index{X.509 certificates} certificates}
-
-This authentication method is part of the certificate authentication
-method in \gnutls{}.
-X.509 certificates contain the public parameters, 
-of a public key algorithm, and the authority's signature, which proves the
-authenticity of the parameters.
-The key exchange methods shown in \hyperref{figure}{figure }{}{fig:cert} are
-available in X.509 authentication. 
-\par
-See section \ref{x509:trust} on page \pageref{x509:trust} for more information
-on X.509 protocols.