Added discussion of the provided cryptographic functions. Internals is now included in the latex document (needs rewrite though)

14 files changed, 101 insertions, 47 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9fa4137eef..dad8bd9bec 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -66,21 +66,21 @@ gnutls_TEXINFOS += gnutls-certificate-user-use-case.dia	\
 gnutls_TEXINFOS += gnutls-client-server-use-case.dia	\
 	gnutls-client-server-use-case.eps		\
 	gnutls-client-server-use-case.png
-gnutls_TEXINFOS += gnutls-extensions_st.dia gnutls-extensions_st.eps	\
-	gnutls-extensions_st.png
+gnutls_TEXINFOS += gnutls-extensions.dia gnutls-extensions.eps	\
+	gnutls-extensions.png
 gnutls_TEXINFOS += gnutls-handshake-sequence.dia			\
 	gnutls-handshake-sequence.eps gnutls-handshake-sequence.png
 gnutls_TEXINFOS += gnutls-handshake-state.dia			\
 	gnutls-handshake-state.eps gnutls-handshake-state.png
-gnutls_TEXINFOS += gnutls-mod_auth_st.dia gnutls-mod_auth_st.eps	\
-	gnutls-mod_auth_st.png
+gnutls_TEXINFOS += gnutls-modauth.dia gnutls-modauth.eps	\
+	gnutls-modauth.png
 gnutls_TEXINFOS += gnutls-objects.dia gnutls-objects.eps	\
 	gnutls-objects.png
 
 imagesdir = $(infodir)
 images_DATA = gnutls-certificate-user-use-case.png		\
-	gnutls-extensions_st.png gnutls-handshake-state.png	\
-	gnutls-layers.png gnutls-mod_auth_st.png gnutls-pgp.png	\
+	gnutls-extensions.png gnutls-handshake-state.png	\
+	gnutls-layers.png gnutls-modauth.png gnutls-pgp.png	\
 	gnutls-client-server-use-case.png			\
 	gnutls-handshake-sequence.png gnutls-internals.png	\
 	gnutls-logo.png gnutls-objects.png gnutls-x509.png	\
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 1b5e47b060..d4dec0198f 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -9,6 +9,7 @@
 * Server examples::
 * Miscellaneous examples::
 * Advanced and other topics::
+* Using the cryptographic library::
 @end menu
 
 @node Preparation
@@ -491,3 +492,56 @@ Current limitations imposed by the compatibility layer include:
 
 @end itemize
 
+@node Using the cryptographic library
+@section Using the cryptographic library
+
+@acronym{GnuTLS} is not a low-level cryptographic library, i.e., 
+it does not provide access to basic cryptographic primitives. However
+it abstracts the internal cryptographic backend (see @ref{Cryptographic Backend}),
+providing symmetric crypto, hash and HMAC algorithms, as well access
+to the random number generation.
+
+@menu
+* Symmetric cryptography::
+* Hash and HMAC functions::
+* Random number generation::
+@end menu
+
+@node Symmetric cryptography
+@subsection Symmetric cryptography
+@cindex Symmetric cryptography
+
+The available functions to access symmetric crypto algorithms operations
+are shown below. The supported algorithms are the algorithms required by the TLS protocol.
+They are listed in @ref{tab:ciphers}.
+
+@showfuncE{gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit}
+
+In order to support authenticated encryption with associated data (AEAD) algoritms the following
+functions are provided to set the associated data and retrieve the authentication tag.
+
+@showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}
+
+@node Hash and HMAC functions
+@subsection Hash and HMAC functions
+@cindex Hash functions
+@cindex HMAC functions
+
+The available operations to access hash functions and hash-MAC (HMAC) algorithms
+are shown below. HMAC algorithms provided keyed hash functionality. They supported HMAC algorithms are listed in @ref{tab:macs}.
+
+@showfuncF{gnutls_hmac_init,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast}
+
+The available functions to access hash functions are shown below. The supported hash functions
+are the same as the HMAC algorithms.
+
+@showfuncF{gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
+
+@node Random number generation
+@subsection Random number generation
+@cindex Random numbers
+
+Access to the random number generator is provided using the @funcref{gnutls_rnd}
+function.
+
+@showfuncdesc{gnutls_rnd}
diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
index a889a04b9d..7f7a4148c9 100644
--- a/doc/cha-internals.texi
+++ b/doc/cha-internals.texi
@@ -77,7 +77,7 @@ structures@footnote{such as the
 such as certificates, usernames etc. to @code{auth_info_t} structures.
 
 @float Figure,fig:gnutls-mod-auth
-@image{gnutls-mod_auth_st,12cm}
+@image{gnutls-modauth,12cm}
 @caption{GnuTLS authentication method structure.}
 @end float
 
@@ -93,7 +93,7 @@ As with authentication methods, the TLS extensions handlers can be
 implemented using the interface shown in @ref{fig:gnutls-ext}.
 
 @float Figure,fig:gnutls-ext
-@image{gnutls-extensions_st,12cm}
+@image{gnutls-extensions,12cm}
 @caption{GnuTLS extensions structure.}
 @end float
 
@@ -114,9 +114,7 @@ follow if you wish to do this yourself.  For sake of discussion, let's
 consider adding support for the hypothetical TLS extension
 @code{foobar}.
 
-@enumerate
-
-@item Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}.
+@subsubsection Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}.
 
 This step is useful when the extension code is large and it might be desirable
 to disable the extension under some circumstances. Otherwise it can be safely
@@ -144,7 +142,7 @@ AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")
 
 These lines should go in @code{lib/m4/hooks.m4}.
 
-@item Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}.
+@subsubsection Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}.
 
 A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
 with @url{http://www.iana.org/assignments/tls-extensiontype-values}
@@ -154,7 +152,7 @@ version since it will lead to interoperability problems in the future
 when the IANA allocates that number to someone else, or when the
 foobar protocol is allocated another number.
 
-@item Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}.
+@subsubsection Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}.
 
 A typical entry would be:
 
@@ -198,7 +196,7 @@ will be called to deinitialize the extension's private parameters, if any.
 Note that the conditional @code{ENABLE_FOOBAR} definition should only be 
 used if step 1 with the @code{configure} options has taken place.
 
-@item Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implement the extension.
+@subsubsection Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implement the extension.
 
 The functions you are responsible to add are those mentioned in the
 previous step.  As a starter, you could add this:
@@ -247,15 +245,15 @@ The @code{_foobar_unpack} function is responsible for
 restoring session data from the session storage.
 
 If you receive length fields that doesn't match, return
-@code{GNUTLS_E_UNEXPECTED_PACKET_LENGTH}.  If you receive invalid
-data, return @code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER}.  You can use
+@code{GNUTLS_E_\-UNEXPECTED_\-PACKET_\-LENGTH}.  If you receive invalid
+data, return @code{GNUTLS_E_\-RECEIVED_\-ILLEGAL_\-PARAMETER}.  You can use
 other error codes too.  Return 0 on success.
 
 The function could store some information in the @code{session}
 variable for later usage. That can be done using the functions 
-@code{_gnutls_ext_set_session_data} and
-@code{_gnutls_ext_get_session_data}. You can check simple examples
-at @code{ext_max_record.c} and @code{ext_server_name.c} extensions.
+@code{_gnutls_ext_\-set_session_\-data} and
+@code{_gnutls_ext_\-get_session_\-data}. You can check simple examples
+at @code{ext_\-max_\-record.c} and @code{ext_\-server_\-name.c} extensions.
 
 Recall that both the client and server both send and receives
 parameters, and your code most likely will need to do different things
@@ -299,7 +297,7 @@ HFILES += ext_foobar.h
 endif
 @end example
 
-@item Add API functions to enable/disable the extension.
+@subsubsection Add API functions to enable/disable the extension.
 
 Normally the client will have one API to request use of the extension,
 and setting some extension specific data.  The server will have one
@@ -307,26 +305,25 @@ API to let the library know that it is willing to accept the
 extension, often this is implemented through a callback but it doesn't
 have to.
 
-The APIs need to be added to @code{includes/gnutls/gnutls.h} or
-@code{includes/gnutls/extra.h} as appropriate.  It is recommended that
-if you don't have a requirement to use the LGPLv2.1+ license for your
+The APIs need to be added to @code{includes/\-gnutls/\-gnutls.h} or
+@code{includes/\-gnutls/\-extra.h} as appropriate.  It is recommended that
+if you don't have a requirement to use the LGPLv3+ license for your
 extension, that you place your work under the GPLv3+ license and thus
 in the libgnutls-extra library.
 
 You can implement the API function in the @code{ext_foobar.c} file, or
 if that file ends up becoming rather larger, add a
-@code{gnutls_foobar.c} file.
+@code{gnutls_\-foobar.c} file.
 
 To make the API available in the shared library you need to add the
-symbol in @code{lib/libgnutls.map} or
-@code{libextra/libgnutls-extra.map} as appropriate, so that the symbol
+symbol in @code{lib/\-libgnutls.map} or
+@code{libextra/\-libgnutls-\-extra.map} as appropriate, so that the symbol
 is exported properly.
 
 When writing GTK-DOC style documentation for your new APIs, don't
 forget to add @code{Since:} tags to indicate the GnuTLS version the
 API was introduced in.
 
-@end enumerate
 
 @node Certificate Handling
 @section Certificate Handling
@@ -358,17 +355,10 @@ 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
 crypto provider, if available.
 
-@subsection Cryptographic Library layer
-The Cryptographic Library layer, can  currently be used either with
-libgcrypt or libnettle, each of one has its advantages and some 
-disadvantages. Libgcrypt is a self-contained library, pretty broad 
-in scope that supports many algorithms. In some processors like VIA, 
-it will also use the available crypto instruction set hence providing
-performance benefit comparing to plain software implementation.
-Libnettle provides only software implementation
-of the basic algorithms required in TLS, and is on average 30% faster
-that libgcrypt on almost all algorithms. For
-this reason libnettle is library used by default in GnuTLS.
+@subsection Cryptographic library layer
+The Cryptographic library layer, currently supports only
+libnettle. Other cryptographic libraries might be supported
+in the future.
 
 @subsection External cryptography provider
 Systems that include a cryptographic co-processor, typically come with
@@ -403,10 +393,10 @@ following functions can be used to register those algorithms.
 
 @itemize
 
-@item @refint{gnutls_crypto_single_cipher_register}
+@item @code{gnutls_crypto_single_cipher_register}
 To register a cipher algorithm.
 
-@refint{gnutls_crypto_single_digest_register}
+@item @code{gnutls_crypto_single_digest_register}
 To register a hash (digest) or MAC algorithm.
 
 @end itemize
@@ -421,23 +411,22 @@ them. For this reason the following functions are provided.
 
 @itemize
 
-@item @refint{gnutls_crypto_cipher_register}
+@item @code{gnutls_crypto_cipher_register}
 To override the cryptographic algorithms backend.
 
-@item @refint{gnutls_crypto_digest_register}
+@item @code{gnutls_crypto_digest_register}
 To override the digest algorithms backend.
 
-@item @refint{gnutls_crypto_rnd_register}
+@item @code{gnutls_crypto_rnd_register}
 To override the random number generator backend.
 
-@item @refint{gnutls_crypto_bigint_register}
+@item @code{gnutls_crypto_bigint_register}
 To override the big number number operations backend.
 
-@item @refint{gnutls_crypto_pk_register}
+@item @code{gnutls_crypto_pk_register}
 To override the public key encryption backend. This is tight to the
 big number operations so either both of them should be updated or care
 must be taken to use the same format.
 
 @end itemize
 
-If all of them are used then GnuTLS will no longer use libgcrypt.
diff --git a/doc/gnutls-extensions_st.dia b/doc/gnutls-extensions.dia
index c29e581261..c29e581261 100644
--- a/doc/gnutls-extensions_st.dia
+++ b/doc/gnutls-extensions.dia
diff --git a/doc/gnutls-extensions_st.eps b/doc/gnutls-extensions.eps
index dfbaa23fb0..dfbaa23fb0 100644
--- a/doc/gnutls-extensions_st.eps
+++ b/doc/gnutls-extensions.eps
diff --git a/doc/gnutls-extensions_st.pdf b/doc/gnutls-extensions.pdf
index 54fadc70e5..54fadc70e5 100644
--- a/doc/gnutls-extensions_st.pdf
+++ b/doc/gnutls-extensions.pdf
diff --git a/doc/gnutls-extensions_st.png b/doc/gnutls-extensions.png
index ffd59ec01d..ffd59ec01d 100644
--- a/doc/gnutls-extensions_st.png
+++ b/doc/gnutls-extensions.png
diff --git a/doc/gnutls-mod_auth_st.dia b/doc/gnutls-modauth.dia
index 8c122ebfbc..8c122ebfbc 100644
--- a/doc/gnutls-mod_auth_st.dia
+++ b/doc/gnutls-modauth.dia
diff --git a/doc/gnutls-mod_auth_st.eps b/doc/gnutls-modauth.eps
index f8caa665ce..f8caa665ce 100644
--- a/doc/gnutls-mod_auth_st.eps
+++ b/doc/gnutls-modauth.eps
diff --git a/doc/gnutls-mod_auth_st.pdf b/doc/gnutls-modauth.pdf
index 5a1882e53e..5a1882e53e 100644
--- a/doc/gnutls-mod_auth_st.pdf
+++ b/doc/gnutls-modauth.pdf
diff --git a/doc/gnutls-mod_auth_st.png b/doc/gnutls-modauth.png
index f3ef35c19e..f3ef35c19e 100644
--- a/doc/gnutls-mod_auth_st.png
+++ b/doc/gnutls-modauth.png
diff --git a/doc/latex/Makefile.am b/doc/latex/Makefile.am
index 2c01e887ed..a4c2d437c7 100644
--- a/doc/latex/Makefile.am
+++ b/doc/latex/Makefile.am
@@ -3,7 +3,7 @@ TEX_OBJECTS = gnutls.tex macros.tex fdl.tex cover.tex gnutls.bib
 GEN_TEX_OBJECTS = cha-preface.tex cha-library.tex cha-intro-tls.tex cha-auth.tex \
   cha-cert-auth.tex cha-gtls-app.tex cha-tls-app.tex cha-programs.tex cha-support.tex \
   cha-functions.tex error_codes.tex cha-ciphersuites.tex algorithms.tex \
-  cha-errors.tex alerts.tex
+  cha-errors.tex alerts.tex cha-internals.tex
 
 cha-preface.tex: ../cha-preface.texi
 	../scripts/mytexi2latex $< > $@
@@ -35,6 +35,9 @@ cha-support.tex: ../cha-support.texi
 cha-functions.tex: ../cha-functions.texi
 	../scripts/mytexi2latex $< > $@
 
+cha-internals.tex: ../cha-internals.texi
+	../scripts/mytexi2latex $< > $@
+
 cha-errors.tex: ../cha-errors.texi
 	../scripts/mytexi2latex $< > $@
 
diff --git a/doc/latex/gnutls.tex b/doc/latex/gnutls.tex
index 44a008f7cf..86173499bd 100644
--- a/doc/latex/gnutls.tex
+++ b/doc/latex/gnutls.tex
@@ -61,6 +61,8 @@
 
 \input{cha-programs}
 
+\input{cha-internals}
+
 \appendix
 
 \input{cha-support}
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index 7d842dff56..ad61af74c5 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -200,6 +200,12 @@ multitable:
 			}
 		}
 
+		if ($line =~ s/\@subsubsection (.+)/\\subsubsection{$1}/g) {
+			if ($label ne '') {
+				$line .= "\\label{$label}\n";
+			}
+		}
+
                 if ($line =~ s/\@section (.+)/\\section{$1}/g) {
 			if ($label ne '') {
 				$line .= "\\label{$label}\n";