reorganized documentation

11 files changed, 151 insertions, 135 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index 58851b54c3..e51a3c9a51 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -8,7 +8,8 @@ TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex serv1.tex ex1.tex ex2.tex ex3.
 	funcs.tex examples.tex ex4.tex ../../libextra/gnutls-extra-api.tex \
 	memory.tex intro.tex openpgp.tex x509.tex howto.tex openssl.tex \
 	ex-rfc2818.tex appendix.tex x509cert.xml.tex pgpcert.xml.tex \
-	serv-export.tex serv-srp.tex programs.tex
+	serv-export.tex serv-srp.tex programs.tex library.tex certificate.tex \
+	tlsintro.tex
 
 gnutls.html: $(TEX_OBJECTS)            
 	-latex2html gnutls.tex -no_navigation -split 0 \
diff --git a/doc/tex/certificate.tex b/doc/tex/certificate.tex
new file mode 100644
index 0000000000..ec3ce0055a
--- /dev/null
+++ b/doc/tex/certificate.tex
@@ -0,0 +1,118 @@
+\chapter{More on certificate authentication}
+
+\section{The X.509 trust model}
+\label{x509:trust}
+
+The X.509 protocols rely on a hierarchical trust model. In this trust model
+Certification Authorities (CAs) are used to certify entities.
+Usually more than one certification authorities exist, and certification
+authorities may certify other authorities to issue certificates as well,
+following a hierachical model. 
+One needs to trust one or more CAs for his secure
+communications. In that case only the certificates issued by the trusted
+authorities are acceptable. 
+
+\par The use of X.509 certificates requires some functions which will 
+assist in parsing them. \gnutls{} includes functions which extract 
+parameters from given X.509 certificates. Some of them are:
+\begin{itemize}
+\item \printfunc{gnutls_x509_extract_certificate_dn}{gnutls\_x509\_extract\_certificate\_dn}
+\item \printfunc{gnutls_x509_extract_certificate_serial}{gnutls\_x509\_extract\_certificate\_serial}
+\item \printfunc{gnutls_x509_extract_certificate_subject_alt_name}{gnutls\_x509\_extract\_certificate\_subject\_alt\_name}
+\end{itemize}
+
+Given the complexity of the X.509 protocols we do not expect these limited 
+functions to cover every need. Thus a function which converts X.509 DER certificates
+to an XML form is provided. See appendix \ref{xml} on page \pageref{xml} for
+more information.
+
+
+\par
+Verifying certificate\index{Verifying certificate paths} paths is also important in X.509 authentication.
+For this purpose you can use the
+\printfunc{gnutls_x509_verify_certificate}{gnutls\_x509\_verify\_certificate}
+function. A more generic one is also provided and can be used with all
+of the certificate authentication methods, but is limited to a session. See the
+\printfunc{gnutls_certificate_verify_peers}{gnutls\_certificate\_verify\_peers}
+function.
+
+\par
+Note that \gnutls{} is not a generic purpose X.509 toolkit\footnote{Aegypten is such a toolkit. See 
+\htmladdnormallink{http://www.gnupg.org/aegypten/}{http://www.gnupg.org/aegypten/}}. 
+\gnutls{} only includes the required,
+in order to use the TLS ciphersuites which depend on X.509 certificates.
+
+
+\section{The OpenPGP trust model}
+\label{pgp:trust}
+
+The OpenPGP key authentication relies on a distributed trust model, called
+the "web of trust". The "web of trust" uses a decentralized system of 
+trusted introducers, which are the same as a CA. OpenPGP allows anyone to 
+sign anyone's else public key. When Alice signs Bob's key, she is introducing 
+Bob's key to anyone who trusts Alice. If someone trusts Alice to introduce
+keys, then Alice is a trusted introducer in the mind of that observer.
+
+\begin{figure}[hbtp]
+\includegraphics[height=9cm,width=11cm]{pgp-fig1}
+\label{fig:pgp1}
+\end{figure}
+
+For example: If David trusts Alice to be an introducer, and Alice signed
+Bob's key, Dave also trusts Bob's key to be the real one.
+
+There are some key points that are important in that model. In the example
+Alice has to sign Bob's key, only if she is sure that the key belongs
+to Bob. Otherwise she may also make Dave falsely believe that this
+is Bob's key. Dave has also the responsibility to know who to trust.
+This model is similar to real life relations.
+
+Just see how Charlie behaves in the previous example. Although he has 
+signed Bob's key - because he knows, somehow, that it belongs to Bob - 
+he does not trust Bob to be an introducer. Charlie decided to trust only 
+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.
+
+\par
+First we've to differentiate between ownertrust and validity. Sometimes trust
+and validity is used as a synonym but this is not correct.
+\par
+The ownertrust describes how trustworthy the signature of a special
+key owner is. Even if we've three or more signatures to make a key valid,
+it's possible that we don't trust the owner at all and thus we don't trust 
+the signature he made. There are different ownertrust levels:
+\begin{enumerate}
+\item Don't know
+\item I do NOT trust
+\item I trust marginally
+\item I trust fully
+\item I trust ulitmately.
+\end{enumerate}
+
+For example we need three marginally trusted signature to make a key
+valid or one full trusted signature. The ultimate trust is only used
+when we are the owner of a key and we also have the secret key.
+\par
+In the case we don't trust the owner, those signatures are skipped
+for the web of trust calculation.
+\par
+All checks in GnuTLS are done in \printfunc{gnutls_openpgp_verify_key}{gnutls\_openpgp\_verify\_key}. 
+If a trustdb is available, this is the file which contains all information about the
+key owner (ownertrust), additional checks are performed.
+\\
+First we get the trustdb entry to see if the key is not disabled because
+those keys shouldn't be used at all. Another possible case is that we
+don't trust the key, which means we don't need to perform further checks.
+\par
+If the ownertrust is at least marginal we continue to check all signatures
+the key contains to get the validity of the key. It is likely that the
+public keyring does not contain all needed keys to check all signatures.
+When a signature could not be checked due to a missing key, the function 
+tries the next signature. When NO public key is available, the function
+checks at least the self signature which must be valid in any case because
+it was created by the key itself.
+\\
+Validity means if the signatures on the key are valid and the key was not 
+changed by somebody or corrupted during transport.
+
diff --git a/doc/tex/ciphers.tex b/doc/tex/ciphers.tex
index 08c9edfa4c..06f0e6b13b 100644
--- a/doc/tex/ciphers.tex
+++ b/doc/tex/ciphers.tex
@@ -1,4 +1,4 @@
-\subsection{Symmetric encryption algorithms}
+\section{Symmetric encryption algorithms}
 \par
 Confidentiality is provided by using block encryption algorithms like {\bf 3DES}, 
 {\bf AES\footnote{AES or Advanced Encryption Standard is actually the RIJNDAEL algorithm. This is the
diff --git a/doc/tex/ciphersuites.tex b/doc/tex/ciphersuites.tex
index 9d2a1f8e9b..f8b765d369 100644
--- a/doc/tex/ciphersuites.tex
+++ b/doc/tex/ciphersuites.tex
@@ -1,4 +1,3 @@
-\newpage
 \subsection{TLS cipher suites}
 \par 
 The Handshake Protocol of \tlsI{} negotiates cipher suites 
diff --git a/doc/tex/gnutls.tex b/doc/tex/gnutls.tex
index 6ceec8da9d..4fd1279011 100644
--- a/doc/tex/gnutls.tex
+++ b/doc/tex/gnutls.tex
@@ -23,26 +23,16 @@
 \fancyhead[RO,LE]{\empty}
 \fancyfoot[C]{\thepage}
 
-\chapter{The Library}
-
 \input{intro}
 
-\input{layers}
-
-\input{translayer}
-
-\input{record}
-
-\input{alert}
+\input{tlsintro}
 
-\input{handshake}
-
-\input{errors}
-
-\input{memory}
+\input{library}
 
 \input{auth}
 
+\input{certificate}
+
 \input{howto}
 
 \input{examples}
diff --git a/doc/tex/intro.tex b/doc/tex/intro.tex
index 568e520274..3b3d1ed9bd 100644
--- a/doc/tex/intro.tex
+++ b/doc/tex/intro.tex
@@ -1,5 +1,6 @@
-\section{Introduction}
+\chapter{Introduction}
 
+\section{Description}
 \par
 In brief \gnutls{} can be described as a portable library which offers
 an API to access secure communication protocols. These protocols provide
@@ -28,7 +29,7 @@ See \htmladdnormallink{http://www.gnutls.org/}{http://www.gnutls.org/}
 and \htmladdnormallink{http://www.gnu.org/software/gnutls/}{http://www.gnu.org/software/gnutls/} 
 for updated versions of the \gnutls{} software and this document.
 
-\subsection{Current state}
+\section{Current state}
 
 Currently \gnutls{} implements:
 \begin{itemize}
diff --git a/doc/tex/layers.tex b/doc/tex/layers.tex
index 5ca2b8db5a..fedae1ae1f 100644
--- a/doc/tex/layers.tex
+++ b/doc/tex/layers.tex
@@ -1,4 +1,3 @@
-\newpage
 \section{TLS layers\index{TLS layers}}
 
 \tlsI{} is a layered protocol, and consists of the Record Protocol,
diff --git a/doc/tex/library.tex b/doc/tex/library.tex
new file mode 100644
index 0000000000..cb6bc62c05
--- /dev/null
+++ b/doc/tex/library.tex
@@ -0,0 +1,5 @@
+\chapter{The Library}
+
+\input{errors}
+
+\input{memory}
diff --git a/doc/tex/openpgp.tex b/doc/tex/openpgp.tex
index c8a6a68511..6677b8df40 100644
--- a/doc/tex/openpgp.tex
+++ b/doc/tex/openpgp.tex
@@ -1,83 +1,9 @@
 \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. 
 
-\subsection{The OpenPGP trust model in \gnutls{}}
-\label{sec:pgp}
-
-\subsubsection{The OpenPGP trust model}
-
-The OpenPGP key authentication relies on a distributed trust model, called
-the "web of trust". The "web of trust" uses a decentralized system of 
-trusted introducers, which are the same as a CA. OpenPGP allows anyone to 
-sign anyone's else public key. When Alice signs Bob's key, she is introducing 
-Bob's key to anyone who trusts Alice. If someone trusts Alice to introduce
-keys, then Alice is a trusted introducer in the mind of that observer.
-
-\begin{figure}[hbtp]
-\includegraphics[height=9cm,width=11cm]{pgp-fig1}
-\label{fig:pgp1}
-\end{figure}
-
-For example: If David trusts Alice to be an introducer, and Alice signed
-Bob's key, Dave also trusts Bob's key to be the real one.
-
-There are some key points that are important in that model. In the example
-Alice has to sign Bob's key, only if she is sure that the key belongs
-to Bob. Otherwise she may also make Dave falsely believe that this
-is Bob's key. Dave has also the responsibility to know who to trust.
-This model is similar to real life relations.
-
-Just see how Charlie behaves in the previous example. Although he has 
-signed Bob's key - because he knows, somehow, that it belongs to Bob - 
-he does not trust Bob to be an introducer. Charlie decided to trust only 
-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.
-
-
-\subsubsection{GnuTLS functions}
-
-First we've to differentiate between ownertrust and validity. Sometimes trust
-and validity is used as a synonym but this is not correct.
-\par
-The ownertrust describes how trustworthy the signature of a special
-key owner is. Even if we've three or more signatures to make a key valid,
-it's possible that we don't trust the owner at all and thus we don't trust 
-the signature he made. There are different ownertrust levels:
-\begin{enumerate}
-\item Don't know
-\item I do NOT trust
-\item I trust marginally
-\item I trust fully
-\item I trust ulitmately.
-\end{enumerate}
-
-For example we need three marginally trusted signature to make a key
-valid or one full trusted signature. The ultimate trust is only used
-when we are the owner of a key and we also have the secret key.
-\par
-In the case we don't trust the owner, those signatures are skipped
-for the web of trust calculation.
-\par
-All checks in GnuTLS are done in \printfunc{gnutls_openpgp_verify_key}{gnutls\_openpgp\_verify\_key}. 
-If a trustdb is available, this is the file which contains all information about the
-key owner (ownertrust), additional checks are performed.
-\\
-First we get the trustdb entry to see if the key is not disabled because
-those keys shouldn't be used at all. Another possible case is that we
-don't trust the key, which means we don't need to perform further checks.
-\par
-If the ownertrust is at least marginal we continue to check all signatures
-the key contains to get the validity of the key. It is likely that the
-public keyring does not contain all needed keys to check all signatures.
-When a signature could not be checked due to a missing key, the function 
-tries the next signature. When NO public key is available, the function
-checks at least the self signature which must be valid in any case because
-it was created by the key itself.
-\\
-Validity means if the signatures on the key are valid and the key was not 
-changed by somebody or corrupted during transport.
-
-
+See \ref{pgp:trust} on page \pageref{pgp:trust} for more information 
+about the OpenPGP trust model.
diff --git a/doc/tex/tlsintro.tex b/doc/tex/tlsintro.tex
new file mode 100644
index 0000000000..03ef17161c
--- /dev/null
+++ b/doc/tex/tlsintro.tex
@@ -0,0 +1,12 @@
+\chapter{Introduction to \tls{}}
+
+\input{layers}
+
+\input{translayer}
+
+\input{record}
+
+\input{alert}
+
+\input{handshake}
+
diff --git a/doc/tex/x509.tex b/doc/tex/x509.tex
index bc25b8a0a2..a30634c1fd 100644
--- a/doc/tex/x509.tex
+++ b/doc/tex/x509.tex
@@ -2,14 +2,6 @@
 
 This authentication method is part of the certificate authentication
 method in \gnutls{}.
-The X.509 protocols rely on a hierarchical trust model. In this trust model
-Certification Authorities (CAs) are used to certify entities.
-Usually more than one certification authorities exist, and certification
-authorities may certify other authorities to issue certificates as well,
-following a hierachical model. 
-One needs to trust one or more CAs for his secure
-communications. In that case only the certificates issued by the trusted
-authorities are acceptable. 
 \par
 X.509 certificates contain the public parameters, 
 of a public key algorithm, and the authority's signature, which proves the
@@ -18,32 +10,5 @@ authenticity of the parameters.
 The key exchange methods shown in \hyperref{figure}{figure }{}{fig:cert} are
 available in X.509 authentication. 
 
-\par The use of X.509 certificates requires some functions which will 
-assist in parsing them. \gnutls{} includes functions which extract 
-parameters from given X.509 certificates. Some of them are:
-\begin{itemize}
-\item \printfunc{gnutls_x509_extract_certificate_dn}{gnutls\_x509\_extract\_certificate\_dn}
-\item \printfunc{gnutls_x509_extract_certificate_serial}{gnutls\_x509\_extract\_certificate\_serial}
-\item \printfunc{gnutls_x509_extract_certificate_subject_alt_name}{gnutls\_x509\_extract\_certificate\_subject\_alt\_name}
-\end{itemize}
-
-Given the complexity of the X.509 protocols we do not expect these limited 
-functions to cover every need. Thus a function which converts X.509 DER certificates
-to an XML form is provided. See appendix \ref{xml} on page \pageref{xml} for
-more information.
-
-\par
-Verifying certificate\index{Verifying certificate paths} paths is also important in X.509 authentication.
-For this purpose you can use the
-\printfunc{gnutls_x509_verify_certificate}{gnutls\_x509\_verify\_certificate}
-function. A more generic one is also provided and can be used with all
-of the certificate authentication methods, but is limited to a session. See the
-\printfunc{gnutls_certificate_verify_peers}{gnutls\_certificate\_verify\_peers}
-function.
-
-\par
-Note that \gnutls{} is not a generic purpose X.509 toolkit\footnote{Aegypten is such a toolkit. See 
-\htmladdnormallink{http://www.gnupg.org/aegypten/}{http://www.gnupg.org/aegypten/}}. 
-\gnutls{} only includes the required,
-in order to use the TLS ciphersuites which depend on X.509 certificates.
-
+See \ref{x509:trust} on page \pageref{x509:trust} for more information
+on X.509 protocols.