copied documentation from the devel branch.

10 files changed, 263 insertions, 51 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index 53c37c1a90..1d4f56dbf0 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -7,7 +7,7 @@ EXTRA_DIST = gnutls.tex gnutls.ps \
 EXAMPLE_OBJECTS = ex-alert.tex ex-client-srp.tex ex-serv-export.tex \
 	ex-client2.tex ex-x509-info.tex ex-rfc2818.tex \
 	ex-serv1.tex ex-client-resume.tex ex-serv-srp.tex \
-	ex-serv-pgp.tex ex-cert-select.tex \
+	ex-serv-pgp.tex ex-cert-select.tex cert_auth.tex \
 	ex-crq.tex ex-session-info.tex ex-pkcs12.tex
 
 TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex fdl.tex ../../lib/x509/x509-api.tex \
diff --git a/doc/tex/alert.tex b/doc/tex/alert.tex
index 3c1f13df27..58ae1727c1 100644
--- a/doc/tex/alert.tex
+++ b/doc/tex/alert.tex
@@ -14,8 +14,8 @@ and prevent future renegotiations using the current session ID.
 
 \par The alert messages are protected by the record protocol, thus
 the information that is included does not leak. You must take
-extreme care for the alert information not to leak to a possible attacker
-(via public log files etc).
+extreme care for the alert information not to leak to a possible attacker, 
+via public log files etc.
 
 \par
 \begin{itemize}
@@ -26,5 +26,5 @@ to map a gnutls error number to an alert signal.
 \item \printfunc{gnutls_alert_get}{gnutls\_alert\_get}:
 returns the last received alert.
 \item \printfunc{gnutls_alert_get_name}{gnutls\_alert\_get\_name}:
-returns the name (in a character array) of the given alert.
+returns the name, in a character array, of the given alert.
 \end{itemize}
diff --git a/doc/tex/cert_auth.tex b/doc/tex/cert_auth.tex
new file mode 100644
index 0000000000..742751bfd0
--- /dev/null
+++ b/doc/tex/cert_auth.tex
@@ -0,0 +1,125 @@
+\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. 
+In the 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
+certificate need not to be included, since the peer should possess it already.
+\par
+As an alternative, a callback may be used
+so the server or the client specify the certificate and the key at the handshake time.
+That callback can be set using the functions:
+\begin{itemize}
+\item \printfunc{gnutls_certificate_server_set_retrieve_function}{gnutls\_certificate\_server\_set\_retrieve\_function}
+\item \printfunc{gnutls_certificate_client_set_retrieve_function}{gnutls\_certificate\_client\_set\_retrieve\_function}
+\end{itemize}
+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 automatically 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 cipher suite depends on the 
+certificate's parameters, so not all key exchange methods will be available
+with some certificates. \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 DHE\_RSA ones. It is
+recommended not to use RSA keys for both signing and encryption. If possible
+use the same key for the DHE\_RSA and RSA\_EXPORT ciphersuites, which use signing,
+and a different key for the plain RSA ciphersuites, which use encryption.
+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. That means
+that even if the private key used for signing is compromised, it cannot be
+used to reveal past session data.
+\\
+\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 75740ae3fd..e21a8ba218 100644
--- a/doc/tex/certificate.tex
+++ b/doc/tex/certificate.tex
@@ -10,16 +10,16 @@ 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 hierarchical 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. See figure \ref{fig:x509-1} for a typical example.
 
-\begin{figure}[hbtp]
-\includegraphics[height=9.5cm,width=9cm]{x509-1}
+\begin{figure}[tbp]
+\caption{X.509 certification}
+\includegraphics[height=9.5cm,width=7cm]{x509-1}
 \label{fig:x509-1}
 \end{figure}
 
-
+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. See figure \ref{fig:x509-1} for a typical example.
 The API for handling X.509 certificates is described at section \ref{sec:x509api}
 on page \pageref{sec:x509api}. Some examples are listed below.
 
@@ -27,23 +27,84 @@ on page \pageref{sec:x509api}. Some examples are listed below.
 
 \subsection{X.509 certificates}
 An X.509 certificate usually contains information about the certificate
-holder, the signer, a unique serial number, expiration dates and several other 
-fields\cite{RFC3280}. Several functions exist to generate and handle X.509
-certificates, all listed in \emph{gnutls/x509.h}. Some of them are:
-\begin{itemize}
-\item \printfunc{gnutls_x509_crt_init}{gnutls\_x509\_crt\_init}
-\item \printfunc{gnutls_x509_crt_import}{gnutls\_x509\_crt\_import}
-\item \printfunc{gnutls_x509_crt_get_dn}{gnutls\_x509\_crt\_get\_dn}
-\item \printfunc{gnutls_x509_crt_get_serial}{gnutls\_x509\_crt\_get\_serial}
-\item \printfunc{gnutls_x509_crt_get_subject_alt_name}{gnutls\_x509\_crt\_get\_subject\_alt\_name}
-\end{itemize}
+holder, the signer, a unique serial number, expiration dates and some other 
+fields \cite{RFC3280} as shown in the table below.
 
+\label{fig:x509}
+\begin{tabular}{|l||l|}
+\hline
+version & the field that indicates the version of the certificate.
+\\
+\hline
+serialNumber & this field holds a unique serial number per certificate.
+\\
+\hline
+issuer & holds the issuer's distinguished name
+\\
+\hline
+validity & the activation and expiration dates.
+\\
+\hline
+subject & the subject's distinguished name of the certificate.
+\\
+\hline
+\rowcolor[gray]{0.9}
+extensions & The extensions are fields only present in version 3 certificates.
+\\
+\hline
+\end{tabular}
+\\
+\\
 \par
-To demonstrate the X.509 parsing capabilities an example program is listed below.
-That program reads the peer's certificate, and prints information about it.
-
-\input{ex-x509-info}
+The certificate's \emph{subject or issuer name} is not just a single string. It is
+a Distinguished name and in the ASN.1 notation is a sequence of several object
+IDs with their corresponding values. Some of available OIDs to be used in an X.509
+distinguished name are defined in \emph{gnutls/x509.h}.
+\\
+\\
+The \emph{Version} field in a certificate has values either 1 or 3 for version 3 certificates.
+Version 1 certificates do not support the extensions field so it is not possible
+to distinguish a CA from a person, so their usage should be avoided.
+\\
+\\
+The \emph{validity} dates are there to indicate the date that the specific certificate
+was activated and the date the certificate's key would be considered invalid.
+\\
+\\
+Certificate \emph{extensions} are there to include information about the certificate's
+subject that did not fit in the typical certificate fields. Those may be
+e-mail addresses, flags that indicate whether the belongs to a CA etc.
+All the supported X.509 version 3 extensions are shown in the table below.
 
+\label{fig:x509_ext}
+\begin{tabular}{|l|l|p{6cm}|}
+\hline
+subject key ID & 2.5.29.14 & A unique ID of the subject's key.
+\\
+\hline
+key usage & 2.5.29.15 & Constraints the key's usage of the certificate.
+\\
+\hline
+subject alternative name & 2.5.29.17 & Alternative names to subject's distinguished name.
+\\
+\hline
+basic constraints & 2.5.29.19 & Indicates whether this is a CA certificate or not.
+\\
+\hline
+CRL distribution points & 2.5.29.31 & This extension is set by the CA, in order to inform about the issued CRLs.
+\\
+\hline
+\end{tabular}
+\\
+\\
+\par
+In \gnutls{} the X.509 certificate structures are handled using the
+\emph{gnutls\_x509\_crt} type and the corresponding private keys with
+the \emph{gnutls\_x509\_privkey} type.
+All the available functions for X.509 certificate handling have their 
+prototypes in \emph{gnutls/x509.h}. An example program to demonstrate the 
+X.509 parsing capabilities can be found at section \ref{ex:x509-info} on 
+page \pageref{ex:x509-info}.
 
 \subsection{Verifying X.509 certificate paths}
 Verifying certificate\index{Verifying certificate paths} paths is important 
@@ -56,7 +117,7 @@ The function \printfunc{gnutls_certificate_verify_peers}{gnutls\_certificate\_ve
 is equivalent to the previous one, and will verify the peer's certificate in a TLS session.
 
 \begin{figure}[hbtp]
-\begin{tabular}{|l|p{9cm}|}
+\begin{tabular}{|l|p{7cm}|}
 
 \hline
 CERT\_INVALID & The certificate is not signed by one of the known authorities, or
@@ -85,17 +146,16 @@ for an example.
 \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.
+contain information about an applicant of a certificate service.
 It usually contains a private key, a distinguished name and secondary
 data such as a challenge password. \gnutls{} supports the requests
 defined in PKCS \#10. Other certificate request's format such as
 PKIX's RFC2511 are not currently supported.
-\par
-The following example is about generating a certificate request, and
-a private key. A certificate request can be later be processed by a CA,
-which should return a signed certificate.
 
-\input{ex-crq}
+In \gnutls{} the PKCS \#10 structures are handled using the
+\emph{gnutls\_x509\_crq} type. 
+An example of a certificate request generation can be found at section \ref{ex:crq}
+on page \pageref{ex:crq}.
 
 \subsection{PKCS \#12 structures\index{PKCS \#12}}
 A PKCS \#12 structure usually contains a user's private keys and
@@ -108,11 +168,9 @@ may hold several \emph{gnutls\_pkcs12\_bag} types. The Bag types are the
 holders of the actual data, which may be certificates, private
 keys or encrypted data. An Bag of type encrypted should be decrypted
 in order for its data to be accessed. 
-\par
-The following example is about generating a PKCS \#12 structure.
-
-\input{ex-pkcs12}
 
+An example of a PKCS \#12 structure generation can be found at section \ref{ex:pkcs12}
+on page \pageref{ex:pkcs12}.
 
 \section{The OpenPGP\index{OpenPGP!Keys} trust model}
 \label{pgp:trust}
@@ -145,6 +203,12 @@ 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*{OpenPGP keys}
+In \gnutls{} the OpenPGP key structures are handled using the
+\emph{gnutls\_openpgp\_key} type and the corresponding private keys with
+the \emph{gnutls\_openpgp\_privkey} type. All the prototypes for the key handling
+functions can be found at \emph{gnutls/openpgp.h}.
+
 \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''.
@@ -154,7 +218,6 @@ the assistance of external tools like GnuPG is recommended.
 There are two verification functions in \gnutls{},
 The \printfunc{gnutls_openpgp_key_verify_ring}{gnutls\_openpgp\_key\_verify\_ring}
 and the \printfunc{gnutls_openpgp_key_verify_trustdb}{gnutls\_openpgp\_key\_verify\_trustdb}. 
-\\
 The first one checks an OpenPGP key against a given set of public keys (keyring) and
 returns the key status. The key verification status is the same as in X.509 certificates,
 although the meaning and interpretation are different. For example an OpenPGP key may
@@ -165,7 +228,7 @@ The latter function checks a GnuPG trust database for the given key. This functi
 check the key signatures, only checks for disabled and revoked keys.
 
 \begin{figure}[hbtp]
-\begin{tabular}{|l|p{9cm}|}
+\begin{tabular}{|l|p{7cm}|}
 
 \hline
 CERT\_INVALID & A signature on the key is invalid. That means that the key was modified
diff --git a/doc/tex/ciphers.tex b/doc/tex/ciphers.tex
index a1d9c30950..6c4c5d48bc 100644
--- a/doc/tex/ciphers.tex
+++ b/doc/tex/ciphers.tex
@@ -6,11 +6,11 @@ Encryption Standard is actually the RIJNDAEL algorithm. This is the
 algorithm that replaced DES.}}, or
 stream algorithms like {\bf ARCFOUR\_128\footnote{ARCFOUR\_128 is a compatible
 algorithm with RSA's RC4 algorithm, which is considered to be a trade secret.}} See \hyperref{fig:ciphers}{figure }{}{fig:ciphers} for a complete list. 
-Ciphers are encryption algorithms that use a single (secret) key
+Ciphers are encryption algorithms that use a single, secret, key
 to encrypt and decrypt data. Block algorithms in TLS also provide protection
-against statistical analysis of the data. \gnutls{} makes use of this property
-thus, if you're using the \tlsI{} protocol, a random number of blocks will be
-appended to the data. This will prevent eavesdroppers from guessing the 
+against statistical analysis of the data. 
+Thus, if you're using the \tlsI{} protocol, a random number of blocks will be
+appended to data, to prevent eavesdroppers from guessing the 
 actual data size.
 
 \begin{figure}[hbtp]
diff --git a/doc/tex/examples.tex b/doc/tex/examples.tex
index 940b2b66b7..5b642a1357 100644
--- a/doc/tex/examples.tex
+++ b/doc/tex/examples.tex
@@ -95,4 +95,25 @@ This is a function that checks if an alert has been received
 in the current session.
 \input{ex-alert}
 
+\subsection{X.509 certificate parsing example}
+\label{ex:x509-info}
+To demonstrate the X.509 parsing capabilities an example program is listed below.
+That program reads the peer's certificate, and prints information about it.
+\input{ex-x509-info}
+
+\subsection{Certificate request generation}
+\label{ex:crq}
+The following example is about generating a certificate request, and
+a private key. A certificate request can be later be processed by a CA,
+which should return a signed certificate.
+
+\subsection{PKCS \#12 structure generation}
+\label{ex:pkcs12}
+The following example is about generating a PKCS \#12 structure.
+
+\input{ex-pkcs12}
+
+\input{ex-crq}
+
+
 \input{openssl}
diff --git a/doc/tex/gnutls.tex b/doc/tex/gnutls.tex
index db06189c27..2e1bf7d68e 100644
--- a/doc/tex/gnutls.tex
+++ b/doc/tex/gnutls.tex
@@ -6,6 +6,8 @@
 \usepackage{graphicx}
 \usepackage{makeidx}
 \usepackage{supertabular}
+\usepackage{color}
+\usepackage{colortbl}
 
 \input{macros}
 
@@ -34,12 +36,12 @@
 
 \input{auth}
 
+\input{certificate}
+
 \input{howto}
 
 \input{examples}
 
-\input{certificate}
-
 \input{programs}
 
 \input{funcs}
diff --git a/doc/tex/howto.tex b/doc/tex/howto.tex
index 0c03ef7dd9..d6823848f7 100644
--- a/doc/tex/howto.tex
+++ b/doc/tex/howto.tex
@@ -27,8 +27,7 @@ about the client, and popular methods like the host advertising in
 HTTP do not work\footnote{see also the Server Name Indication extension on \ref{serverind}, page \pageref{serverind}.}. 
 There is no way for the client to say ``I connected
 to YYY server'' before the Handshake starts, so the server cannot
-possibly know which certificate to use\footnote{There is some effort to solve
-this problem within \tls{}}.
+possibly know which certificate to use.
 
 \par
 Other than that it requires two separate ports to run a single service, which is 
@@ -123,7 +122,7 @@ CLIENT: BYE
 \par
 This method, if implemented properly, is far better than the
 traditional method, and the security properties remain the same, since only
-denial of service is possible. The benefit is the server may request
+denial of service is possible. The benefit is that the server may request
 additional data before the \tls{} Handshake protocol
 starts, in order to send the correct certificate, use the correct
 password file\footnote{in SRP authentication}, or anything else!
diff --git a/doc/tex/programs.tex b/doc/tex/programs.tex
index ca3ffe6ac5..d0a0d43467 100644
--- a/doc/tex/programs.tex
+++ b/doc/tex/programs.tex
@@ -98,8 +98,10 @@ Checking for OpenPGP authentication support (TLS extension)... no
 
 \section{The ``certtool'' program}
 
-This is a program to generate X.509 certificates, certificate requests, and
-private keys.
+This is a program to generate X.509 certificates, certificate requests, CRLs and
+private keys. The program can be used interactively or non interactively by
+specifying the \emph{--template} command line option. See \emph{doc/certtool.cfg},
+in the distribution, for an example of a template file.
 
 How to use certtool:
 
diff --git a/doc/tex/srp.tex b/doc/tex/srp.tex
index f1e15a85ee..5764299520 100644
--- a/doc/tex/srp.tex
+++ b/doc/tex/srp.tex
@@ -1,7 +1,7 @@
 \section{Authentication using SRP\index{SRP authentication}}
 
 Authentication using the SRP\footnote{SRP stands for Secure Remote Password and 
-is described in \cite{RFC2945}. The SRP key exchange is not a part of the \tlsI{} protocol}
+is described in \cite{RFC2945}. The SRP key exchange is an extension to the \tlsI{} protocol}
 protocol is actually password authentication. The two peers can be identified using a
 single password, or there can be combinations where the client is 
 authenticated using SRP and the server using a certificate.
@@ -73,6 +73,6 @@ Some helper functions such as
 are included in \gnutls{}, and may be used to generate, and maintain
 SRP verifiers, and password files. 
 A program to manipulate the required parameters 
-for SRP authentication is also included. See section \ref{srpcrypt} on 
-page \pageref{srpcrypt} for more information.
+for SRP authentication is also included. See section \ref{srptool} on 
+page \pageref{srptool} for more information.