@node Using GnuTLS as a cryptographic library
@chapter Using GnuTLS as a 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 back-end (see @ref{Cryptographic Backend}),
providing symmetric crypto, hash and HMAC algorithms, as well access
to the random number generation. For a low-level crypto API the usage of nettle
@footnote{See @uref{http://www.lysator.liu.se/~nisse/nettle/}.} library is recommended.

@menu
* Symmetric algorithms::
* Public key algorithms::
* Hash and HMAC functions::
* Random number generation::
@end menu

@node Symmetric algorithms
@section Symmetric algorithms
@cindex symmetric algorithms
@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) algorithms the following
functions are provided to set the associated data and retrieve the authentication tag.

@showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}

@node Public key algorithms
@section Public key algorithms
@cindex public key algorithms

Public key cryptography algorithms such as RSA, DSA and ECDSA, can be
accessed using the abstract key API in @ref{Abstract key types}. This
is a high level API with the advantage of transparently handling keys
in memory and keys present in smart cards.

@node Hash and HMAC functions
@section 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}
@showfuncA{gnutls_fingerprint}

@node Random number generation
@section Random number generation
@cindex random numbers

Access to the random number generator is provided using the @funcref{gnutls_rnd}
function. It allows obtaining random data of various levels.

@showenumdesc{gnutls_rnd_level_t,The random number levels.}
@showfuncdesc{gnutls_rnd}