\chapter{The Library}
\section{Introduction}
\par
-\gnutls is a portable library which implements the \tlsI and
-\sslIII protocols.
-\tls stands for 'Transport Layer Security' and is the sucessor of \ssl\footnote{
-\ssl or Secure Sockets Layer is a protocol designed by Netscape. \tlsI is based on
-\sslIII protocol. \sslII is a very old protocol which is
-not considered secure today. \sslII is not implemented in \gnutls}.
-\tlsI\footnote{described in {\it RFC 2246}} is an Internet protocol,
-defined by IETF\footnote{IETF or Internet Engineering Task Force
+\gnutls{} is a portable library which implements the \tlsI{} and
+\sslIII{} protocols.
+\tls{} stands for 'Transport Layer Security' and is the sucessor of \ssl{},
+the Secure Sockets Layer protocol designed by Netscape.
+
+\tlsI{}\footnote{described in {\it RFC 2246}} is an Internet protocol,
+defined by {IETF}\footnote{IETF or Internet Engineering Task Force
is a large open international community of network
designers, operators, vendors, and researchers concerned with the evolution of
-the Internet architecture and the smooth operation of the Internet. It is open to any interested individual.}
-that provides confidentiality, and authentication layers over a {reliable
-transport layer}\footnote{\tls is mostly used over {\emph{TCP/IP}} although this is not restrictive, you may
-use it over any reliable transport layer.}. \gnutls implements the
-above protocols in reentrant way in order to be used in multiple threads of
-execution (without the need for Critical Sections and locks). See
-http://www.gnutls.org/ and http://www.gnu.org/software/gnutls/ for
-updated versions of the \gnutls software and this document.
+the Internet architecture and the smooth operation of the Internet. It is open to any interested individual.},
+that provides confidentiality, and authentication layers over any
+transport layer.
+
+\par
+\gnutls{} implements the above
+protocols in a reentrant way. This allows multiple threads of
+execution, without the need for Critical Sections and locks. 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.
\par
-Currently \gnutls implements:
+Currently \gnutls{} implements:
\begin{itemize}
- \item the \tlsI and \sslIII protocols, without any weak algorithms\footnote{
-There are ciphersuites in \tlsI that are considered weak. These
+ \item the \tlsI{} and \sslIII{} protocols, without any weak algorithms\footnote{
+There are ciphersuites in \tlsI{} that are considered weak. These
ciphersuites are deliberately weak in order to be able to export encryption
software from some countries.}
\item {\bf X.509} Public Key Infrastructure (with several limitations).
- \item {\bf SRP} for \tls authentication.
- \item \tls {\bf Extension mechanism}
+ \item {\bf SRP} for \tls{} authentication.
+ \item \tls{} {\bf Extension mechanism}
\end{itemize}
\input{ciphersuites}
\input{errors}
\section{Client Examples}
-This section contains examples of \tls and \ssl clients, using \gnutls.
+This section contains examples of \tls{} and \ssl{} clients, using \gnutls{}.
\subsection{Simple Client example with X.509 Authentication}
Let's assume now that we want to create a client which communicates
with servers using the X509 authentication schema. The following client
-is a very simple \tls client, it does not support session resuming nor
+is a very simple \tls{} client, it does not support session resuming nor
any other fancy features.
\input{ex2}
\input{ex1}
\subsection{Simple Client example with SRP Authentication}
-Although {\bf SRP} is not part of the \tls standard, \gnutls implements
-{\it David Taylor's}\footnote{Work in progress.} proposal for using the SRP algorithm
-within the \tls handshake protocol. The following client
+Although {\bf SRP} is not part of the \tls{} standard, \gnutls{} implements
+{\it David Taylor's} proposal\footnote{This is work in progress.} for using the SRP algorithm
+within the \tls{} handshake protocol. The following client
is a very simple SRP-TLS client which connects to a server
and authenticates using {\it username} and {\it password}.
\input{srp1}
\section{Server Examples}
-This section contains examples of \tls and \ssl servers, using \gnutls.
+This section contains examples of \tls{} and \ssl{} servers, using \gnutls{}.
\subsection{Echo Server with X.509 and SRP authentication}
The following example is a server which supports both {\bf SRP} and {\bf X509} authentication.
the same server a client may use session resuming. {\bf Session resuming} is a
feature of the {\bf TLS} protocol which allows a client to connect to a server,
after a successful handshake, without the expensive calculations (by using the previously
-established keys). \gnutls supports this feature, and the
+established keys). \gnutls{} supports this feature, and the
example \hyperref{resume client}{resume client (see Section }{)}{resume-example} illustrates a typical use of it (This is a modification of the simple client example).
Servers only need to use the
\hyperref{gnutls\_db\_set\_name()}{gnutls\_db\_set\_name() (see Section }{)}{gnutls_db_set_name} function if they want to use the gdbm
not to block to wait for the DB to be ready for writing, but continue the
process normally (and do not save the parameters).
\par
- \gnutls also provides callback functions such as:
+ \gnutls{} also provides callback functions such as:
\hyperref{gnutls\_db\_set\_remove\_function()}{gnutls\_db\_set\_remove\_function() (see Section }{)}
{gnutls_db_set_remove_function},
\hyperref{gnutls\_db\_set\_store\_function()}{gnutls\_db\_set\_store\_function() (see Section }{)}
for expired sessions in order to remove them, and save space. This is what
\hyperref{gnutls\_db\_clean()}{gnutls\_db\_clean() (see Section }{)}
{gnutls_db_clean} does for the gdbm backend.
-\gnutls provides the function
+\gnutls{} provides the function
\hyperref{gnutls\_db\_check\_entry()}{gnutls\_db\_check\_entry() (see Section }{)
}{gnutls_db_check_entry}, which takes as input session data, and
returns a negative value if the data are to be removed.
\section{Transport Layer}
\par
-\gnutls can be used above any reliable transport layer. To do this you will only
+\gnutls{} can be used above any reliable transport layer. To do this you will only
need to set up the
\hyperref{gnutls\_transport\_set\_push\_func()}{gnutls\_transport\_set\_push\_func() (see Section }{)}{gnutls_transport_set_push_func} and
\hyperref{gnutls\_transport\_set\_pull\_func()}{gnutls\_transport\_set\_pull\_func() (see Section }{)}{gnutls_transport_set_pull_func}
functions. These functions will then be used by gnutls in order to send and receive data.
The functions specified should return -1 on error and should set errno appropriately.
-\gnutls supports EINTR and EAGAIN errno values. These values are
+\gnutls{} supports EINTR and EAGAIN errno values. These values are
usually used in non blocking IO and interrupted system calls.
The corresponding values (GNUTLS\_E\_INTERRUPTED, GNUTLS\_E\_AGAIN)
-will be returned to the caller of the gnutls function. \gnutls functions
+will be returned to the caller of the gnutls function. \gnutls{} functions
can be resumed (called again), if any of these values is returned.
\par
By default, if none of the above functions are called, gnutls will use
projects / thirdparty / gnutls.git / commitdiff
