From: Nikos Mavrogiannopoulos Date: Mon, 20 Jun 2011 17:15:40 +0000 (+0200) Subject: figures were made floating. X-Git-Tag: gnutls_2_99_4~27 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7114ead4d4e0e4159001089f861c60c80f5bb417;p=thirdparty%2Fgnutls.git figures were made floating. --- diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 2342618d2d..c4675ae4ed 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -20,12 +20,15 @@ entities. Usually more than one certification authorities exist, and 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:: @@ -308,11 +311,13 @@ CA. @acronym{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. +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 @@ -390,9 +395,12 @@ main advantage is that it allows operations on private key objects such as decry 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 diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi index 29bc25c572..a889a04b9d 100644 --- a/doc/cha-internals.texi +++ b/doc/cha-internals.texi @@ -18,34 +18,49 @@ happens inside the black box. @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 @@ -53,10 +68,7 @@ In @acronym{GnuTLS} authentication methods can be implemented quite 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} @@ -64,6 +76,11 @@ structures@footnote{such as the @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 @@ -73,9 +90,12 @@ its pointers has to be registered in @code{gnutls_algorithms.c} in the @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 @@ -311,9 +331,12 @@ API was introduced in. @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 @@ -324,9 +347,12 @@ those is a challenging task for every cryptographic application or 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 diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index d8dc5bc3a9..adfe22f627 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -49,9 +49,12 @@ alert protocol is above the record protocol. The Handshake protocol is responsible for the security parameters' negotiation, the initial key exchange and authentication. @xref{The Handshake Protocol}, for more information about the handshake -protocol. The protocol layering in TLS is shown in the figure below. +protocol. The protocol layering in TLS is shown in @ref{fig:tls-layers}. -@center @image{gnutls-layers,12cm} +@float Figure,fig:tls-layers +@image{gnutls-layers,12cm} +@caption{The TLS protocol layers.} +@end float @node The transport layer @section The Transport Layer diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 5f738e1b7d..84e88e8a99 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -61,11 +61,8 @@ smaller library, with the required features, can be generated. @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 @@ -75,6 +72,11 @@ for the deinitialization function which frees all memory allocated in 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, @@ -88,7 +90,7 @@ using the appropriate functions, and put its trusted certificates in 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. diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex index e24ad9e3cb..38bbfd53c1 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -10,6 +10,7 @@ use constant MULTITABLE => 6; use constant EXAMPLE => 7; use constant SMALL_EXAMPLE => 8; use constant QUOTE => 9; +use constant FLOAT => 10; sub unescape() { @@ -71,6 +72,13 @@ while ($line = ) { } $line =~ s/\@item(.*)/\\item $1/g; $prev_mode = $mode; + } elsif ($mode == FLOAT) { + if ($line =~ s/\@end float/\\label\{$label\}\n\\end{figure}/g) { + $mode = NORMAL; + } + $line =~ s/\@image\{(\w)\,($spacematch)\}/\\includegraphics\[width=$2\]\{$1\}/g; + $line =~ s/\@caption\{/\\caption\{/g; + $prev_mode = $mode; } elsif ($mode == TABLE_ITEMIZE) { if ($line =~ s/\@end table/\n\\end{itemize}/g) { $mode = NORMAL; @@ -188,6 +196,10 @@ while ($line = ) { if ($line =~ s/\@itemize/\\begin{itemize}/g) { $mode = ITEMIZE; } + if ($line =~ s/\@float Figure\,(.*)/\\begin{figure}[htp]/g) { + $label = $1; + $mode = FLOAT; + } if ($line =~ s/\@enumerate/\\begin{enumerate}/g) { $mode = ENUMERATE; }