Added documentation for the new crypto backend.

2 files changed, 93 insertions, 4 deletions

diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index e55e86ec2f..f0a5e47bec 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -198,7 +198,8 @@ development release.  For example, GnuTLS 1.6.3 denote a stable
 release since 6 is even, and GnuTLS 1.7.11 denote a development
 release since 7 is odd.
 
-GnuTLS depends on Libgcrypt, and you will need to install Libgcrypt
+GnuTLS depends on Libgcrypt,
+and you will need to install Libgcrypt
 before installing GnuTLS.  Libgcrypt is available from
 @url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
 library, libgpg-error, and you need to install libgpg-error before
@@ -388,7 +389,7 @@ widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
 to ease integration with existing applications.
 
 @acronym{GnuTLS} consists of three independent parts, namely the ``TLS
-protocol part'', the ``Certificate part'', and the ``Crypto backend''
+protocol part'', the ``Certificate part'', and the ``Cryptographic backend''
 part.  The `TLS protocol part' is the actual protocol implementation,
 and is entirely implemented within the @acronym{GnuTLS} library.  The
 `Certificate part' consists of the certificate parsing, and
@@ -400,9 +401,10 @@ for the @acronym{X.509} certificate parsing functions.  A smaller
 version of
 @acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}}
 is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
-The ``Crypto backend'' is provided by the
+The ``Cryptographic backend'' is provided by the
 @acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
-library.
+library@footnote{On current versions of GnuTLS it is possible
+to override the default crypto backend. Check @pxref{Cryptographic Backend} for details}.
 
 In order to ease integration in embedded systems, parts of the
 @acronym{GnuTLS} library can be disabled at compile time. That way a
@@ -3688,6 +3690,66 @@ is summarized in the following diagram.
 
 @image{gnutls-certificate-user-use-case,12cm}
 
+@node Cryptographic Backend
+@section Cryptographic Backend
+Several new systems provide hardware assisted cryptographic algorithm implementations
+that offer implementations some orders of magnitude faster than the software. For this
+reason in current releases of GnuTLS it is possible to override parts of the crypto
+backend or the whole. It is possible to override them both at runtime and compile time, however
+here we will discuss the runtime possibility. The API available for this functionality
+is in @code{gnutls/crypto.h} header file.
+
+@subsection Override specific algorithms
+When an optimized implementation of a single algorithm is available, say a
+hardware assisted version of @acronym{AES-CBC} then the following functions
+can be used to register those algorithms.
+
+@itemize
+
+@item @ref{gnutls_crypto_single_cipher_register2}
+To register a cipher algorithm.
+
+@item @ref{gnutls_crypto_single_mac_register2}
+To register a MAC algorithm.
+
+@ref{gnutls_crypto_single_digest_register2}
+To register a digest (hash) algorithm.
+
+@end itemize
+
+Those registration functions will only replace the specified algorithm and leave the
+rest of subsystem intact.
+
+@subsection Override parts of the backend
+In some systems, such as embedded ones, it might be desirable to override big parts
+of the cryptographic backend, or even all of them. For this reason the following
+functions are provided.
+
+@itemize
+
+@item @ref{gnutls_crypto_cipher_register2}
+To override the cryptographic algorithms backend.
+
+@item @ref{gnutls_crypto_mac_register2}
+To override the MAC algorithms backend.
+
+@item @ref{gnutls_crypto_digest_register2}
+To override the digest algorithms backend.
+
+@item @ref{gnutls_crypto_rnd_register2}
+To override the random number generator backend.
+
+@item @ref{gnutls_crypto_bigint_register2}
+To override the big number number operations backend.
+
+@item @ref{gnutls_crypto_pk_register2}
+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.
 
 @node Copying Information
 @appendix Copying Information
diff --git a/lib/crypto.c b/lib/crypto.c
index 4e5e7e85e2..ccc9a81093 100644
--- a/lib/crypto.c
+++ b/lib/crypto.c
@@ -143,6 +143,9 @@ void _gnutls_crypto_deregister(void)
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_single_cipher_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -175,6 +178,9 @@ gnutls_crypto_single_cipher_st *_gnutls_get_crypto_cipher( gnutls_cipher_algorit
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_rnd_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -209,6 +215,9 @@ int gnutls_crypto_rnd_register2( int priority, int version, gnutls_crypto_rnd_st
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_single_mac_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -243,6 +252,9 @@ gnutls_crypto_single_mac_st *_gnutls_get_crypto_mac( gnutls_mac_algorithm_t algo
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_single_digest_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -278,6 +290,9 @@ gnutls_crypto_single_digest_st *_gnutls_get_crypto_digest( gnutls_digest_algorit
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_bigint_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -314,6 +329,9 @@ int gnutls_crypto_bigint_register2( int priority, int version, gnutls_crypto_big
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_pk_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -346,6 +364,9 @@ int gnutls_crypto_pk_register2( int priority, int version, gnutls_crypto_pk_st*
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_cipher_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -379,6 +400,9 @@ int gnutls_crypto_cipher_register2( int priority, int version, gnutls_crypto_cip
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_mac_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/
@@ -412,6 +436,9 @@ int gnutls_crypto_mac_register2( int priority, int version, gnutls_crypto_mac_st
   *
   * This function should be called before gnutls_global_init().
   *
+  * For simplicity you can use the convenience gnutls_crypto_digest_register()
+  * macro.
+  *
   * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
   *
   **/