certification authorities may certify other authorities to issue
certificates as well, following a hierarchical model.
-@center @image{gnutls-x509,7cm}
+@float Figure,fig:x509
+@image{gnutls-x509,7cm}
+@caption{The X.509 hierarchical trust model.}
+@end float
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. The framework is illustrated on the figure above.
-Detailed examples are listed below.
+acceptable. The framework is illustrated on @ref{fig:x509}.
+Detailed examples involving X.509 certificates are listed below.
@menu
* X.509 certificates::
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.
+For example in @ref{fig:openpgp}, David trusts Alice to be an introducer and Alice
+signed Bob's key thus Dave trusts Bob's key to be the real one.
-@center @image{gnutls-pgp,8cm}
-
-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.
+@float Figure,fig:openpgp
+@image{gnutls-pgp,8cm}
+@caption{The OpenPGP trust model.}
+@end float
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
and signing without accessing the key itself.
Moreover it can be used to allow all applications in the same operating system to access
-shared cryptographic keys and certificates in a uniform way, as in the following picture.
+shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs11-vision}.
-@center @image{pkcs11-vision,8cm}
+@float Figure,fig:pkcs11-vision
+@image{pkcs11-vision,8cm}
+@caption{PKCS #11 module usage.}
+@end float
@subsection Initialization
To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tokens
@node The TLS Protocol
@section The TLS Protocol
-The main needs for the TLS protocol to be used are
-shown in the image below.
-
-@center @image{gnutls-client-server-use-case,9cm}
-
-This is being accomplished by the following object diagram.
+The main use case for the TLS protocol is shown in @ref{fig:client-server}.
+A user of a library implementing the protocol expects no less than this functionality,
+i.e., to be able to set parameters such as the accepted security level, perform a
+negotiation with the peer and be able to exchange data.
+
+@float Figure,fig:client-server
+@image{gnutls-client-server-use-case,9cm}
+@caption{TLS protocol use case.}
+@end float
+
+This in @acronym{GnuTLS} is being accomplished by an object-oriented architecture
+as shown in @ref{fig:gnutls-objects}.
Note that since @acronym{GnuTLS} is being developed in C
object are just structures with attributes. The operations listed
are functions that require the first parameter to be that object.
-@center @image{gnutls-objects,12cm}
+
+@float Figure,fig:gnutls-objects
+@image{gnutls-objects,12cm}
+@caption{GnuTLS objects.}
+@end float
@node TLS Handshake Protocol
@section TLS Handshake Protocol
The @acronym{GnuTLS} handshake protocol is implemented as a state
machine that waits for input or returns immediately when the non-blocking
-transport layer functions are used. The main idea is shown in the following
-figure.
+transport layer functions are used. The main idea is shown in @ref{fig:gnutls-handshake}.
-@center @image{gnutls-handshake-state,9cm}
+@float Figure,fig:gnutls-handshake
+@image{gnutls-handshake-state,9cm}
+@caption{GnuTLS handshake state machine.}
+@end float
Also the way the input is processed varies per ciphersuite. Several
implementations of the internal handlers are available and
@funcref{gnutls_handshake} only multiplexes the input to the appropriate
handler. For example a @acronym{PSK} ciphersuite has a different
implementation of the @code{process_client_key_exchange} than a
-certificate ciphersuite.
+certificate ciphersuite. We illustrate the idea in @ref{fig:gnutls-handshake-sequence}.
-@center @image{gnutls-handshake-sequence,12cm}
+@float Figure,fig:gnutls-handshake-sequence
+@image{gnutls-handshake-sequence,12cm}
+@caption{GnuTLS handshake process sequence.}
+@end float
@node TLS Authentication Methods
@section TLS Authentication Methods
easily. Since the required changes to add a new authentication method
affect only the handshake protocol, a simple interface is used. An
authentication method needs only to implement the functions as seen in
-the figure below.
-
-@center @image{gnutls-mod_auth_st,12cm}
-
+@ref{fig:gnutls-mod-auth}.
The functions that need to be implemented are the ones responsible for
interpreting the handshake protocol messages. It is common for such
functions to read data from one or more @code{credentials_t}
@code{gnutls_certificate_credentials_t} structures} and write data,
such as certificates, usernames etc. to @code{auth_info_t} structures.
+@float Figure,fig:gnutls-mod-auth
+@image{gnutls-mod_auth_st,12cm}
+@caption{GnuTLS authentication method structure.}
+@end float
+
Simple examples of existing authentication methods can be seen in
@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP
ciphersuites. After implementing these functions the structure holding
@node TLS Extension Handling
@section TLS Extension Handling
As with authentication methods, the TLS extensions handlers can be
-implemented using the following interface.
+implemented using the interface shown in @ref{fig:gnutls-ext}.
-@center @image{gnutls-extensions_st,12cm}
+@float Figure,fig:gnutls-ext
+@image{gnutls-extensions_st,12cm}
+@caption{GnuTLS extensions structure.}
+@end float
Here there are two functions, one for receiving the extension data
and one for sending. These functions have to check internally whether
@node Certificate Handling
@section Certificate Handling
What is provided by the certificate handling functions
-is summarized in the following diagram.
+is summarized in @ref{fig:gnutls-cert-use-case}.
-@center @image{gnutls-certificate-user-use-case,12cm}
+@float Figure,fig:gnutls-cert-use-case
+@image{gnutls-certificate-user-use-case,12cm}
+@caption{GnuTLS certificate subsystem use cases.}
+@end float
@node Cryptographic Backend
@section Cryptographic Backend
library. Unfortunately the cryptographic libraries that GnuTLS is based
on take no advantage of these properties. For this reason GnuTLS handles
this internally by following a layered approach to accessing
-cryptographic operations as in the following figure.
+cryptographic operations as in @ref{fig:crypto-layers}.
-@center @image{gnutls-crypto-layers,12cm}
+@float Figure,fig:crypto-layers
+@image{gnutls-crypto-layers,12cm}
+@caption{GnuTLS cryptographic back-end design.}
+@end float
The TLS layer uses a cryptographic provider layer, that will in turn either
use the default crypto provider - a crypto library, or use an external
@section General Idea
A brief description of how @acronym{GnuTLS} works internally is shown
-at the figure below. This section may be easier to understand after
+at @ref{fig:gnutls-design}. This section may be easier to understand after
having seen the examples at @ref{examples}.
-
-@center @image{gnutls-internals,12cm}
-
As shown in the figure, there is a read-only global state that is
initialized once by the global initialization function. This global
structure, among others, contains the memory allocation functions
the global structure and is called after the program has permanently
finished using @acronym{GnuTLS}.
+@float Figure,fig:gnutls-design
+@image{gnutls-internals,12cm}
+@caption{High level design of GnuTLS.}
+@end float
+
The credentials structure is used by some authentication methods, such
as certificate authentication. A
credentials structure may contain certificates, private keys,
this structure. The next step is to associate the credentials
structure with each @acronym{TLS} session.
-A @acronym{GnuTLS} session contains all the required stuff for a
+A @acronym{GnuTLS} session contains all the required information for a
session to handle one secure connection. This session calls directly
to the transport layer functions, in order to communicate with the
peer. Every session has a unique session ID shared with the peer.
projects / thirdparty / gnutls.git / commitdiff
