Using GnuTLS as a cryptographic library
***************************************

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 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 (See https://www.lysator.liu.se/~nisse/nettle/.) library is recommended.

Symmetric algorithms
====================

The available functions to access symmetric crypto algorithms operations are listed in the sections below. The supported algorithms are the algorithms required by the TLS protocol. They are listed in gnutls_cipher_algorithm_t. Note that there two types of ciphers, the ones providing an authenticated-encryption with associated data (AEAD), and the legacy ciphers which provide raw access to the ciphers. We recommend the use of the AEAD APIs for new applications as it is designed to minimize misuse of cryptography.

gnutls_cipher_algorithm_t,The supported ciphers.

Authenticated-encryption API
----------------------------

The AEAD API provides access to all ciphers supported by GnuTLS which support authenticated encryption with associated data. That is particularly suitable for message or packet-encryption as it provides authentication and encryption on the same API. See RFC5116 for more information on authenticated encryption.

gnutls_aead_cipher_init,gnutls_aead_cipher_encrypt,gnutls_aead_cipher_decrypt,gnutls_aead_cipher_deinit

Because the encryption function above may be difficult to use with scattered data, we provide the following API.

gnutls_aead_cipher_encryptv

Legacy API
----------

The legacy API provides low-level access to all legacy ciphers supported by GnuTLS, and some of the AEAD ciphers (e.g., AES-GCM and CHACHA20). The restrictions of the nettle library implementation of the ciphers apply verbatim to this API (See the nettle manual https://www.lysator.liu.se/~nisse/nettle/nettle.html).

gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit

gnutls_cipher_add_auth,gnutls_cipher_tag While the latter two functions allow the same API can be used with authenticated encryption ciphers, it is recommended to use the following functions which are solely for AEAD ciphers. The latter API is designed to be simple to use and also hard to misuse, by handling the tag verification and addition in transparent way.

Public key algorithms
=====================

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

gnutls_privkey_init,gnutls_privkey_import_url,gnutls_privkey_import_x509_raw,gnutls_privkey_sign_data,gnutls_privkey_sign_hash,gnutls_privkey_deinit

gnutls_pubkey_init,gnutls_pubkey_import_url,gnutls_pubkey_import_x509,gnutls_pubkey_verify_data2,gnutls_pubkey_verify_hash2,gnutls_pubkey_deinit

Keys stored in memory can be imported using functions like gnutls_privkey_import_x509_raw, while keys on smart cards or HSMs should be imported using their PKCS#11 URL with gnutls_privkey_import_url.

If any of the smart card operations require PIN, that should be provided either by setting the global PIN function (gnutls_pkcs11_set_pin_function), or better with the targeted to structures functions such as gnutls_privkey_set_pin_function.

Key generation
--------------

All supported key types (including RSA, DSA, ECDSA, Ed25519) can be generated with GnuTLS. They can be generated with the simpler gnutls_privkey_generate or with the more advanced gnutls_privkey_generate2.

gnutls_privkey_generate2

Cryptographic Message Syntax / PKCS7
====================================

The CMS or PKCS #7 format is a commonly used format for digital signatures. PKCS #7 is the name of the original standard when published by RSA, though today the standard is adopted by IETF under the name CMS.

The standards include multiple ways of signing a digital document, e.g., by embedding the data into the signature, or creating detached signatures of the data, including a timestamp, additional certificates etc. In certain cases the same format is also used to transport lists of certificates and CRLs.

It is a relatively popular standard to sign structures, and is being used to sign in PDF files, as well as for signing kernel modules and other structures.

In GnuTLS, the basic functions to initialize, deinitialize, import, export or print information about a PKCS #7 structure are listed below. gnutls_pkcs7_init,gnutls_pkcs7_deinit,gnutls_pkcs7_export2,gnutls_pkcs7_import,gnutls_pkcs7_print

The following functions allow the verification of a structure using either a trust list, or individual certificates. The gnutls_pkcs7_sign function is the data signing function.

gnutls_pkcs7_verify_direct,gnutls_pkcs7_verify

gnutls_pkcs7_sign

gnutls_pkcs7_sign_flags,Flags applicable to gnutls_pkcs7_sign()

Other helper functions which allow to access the signatures, or certificates attached in the structure are listed below.

gnutls_pkcs7_get_signature_count,gnutls_pkcs7_get_signature_info,gnutls_pkcs7_get_crt_count,gnutls_pkcs7_get_crt_raw2,gnutls_pkcs7_get_crl_count,gnutls_pkcs7_get_crl_raw2

To append certificates, or CRLs in the structure the following functions are provided. gnutls_pkcs7_set_crt_raw,gnutls_pkcs7_set_crt,gnutls_pkcs7_set_crl_raw,gnutls_pkcs7_set_crl

Hash and MAC functions
======================

The available operations to access hash functions and hash-MAC (HMAC) algorithms are shown below. HMAC algorithms provided keyed hash functionality. The supported MAC and HMAC algorithms are listed in gnutls_mac_algorithm_t. Note that, despite the hmac part in the name of the MAC functions listed below, they can be used either for HMAC or MAC operations.

gnutls_mac_algorithm_t,The supported MAC and HMAC algorithms.

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 shown in gnutls_digest_algorithm_t.

gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast gnutls_fingerprint

gnutls_digest_algorithm_t,The supported hash algorithms.

Random number generation
========================

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

gnutls_rnd_level_t,The random number levels. gnutls_rnd

See Random Number Generators-internals for more information on the random number generator operation.

Overriding algorithms
=====================

In systems which provide a hardware accelerated cipher implementation that is not directly supported by GnuTLS, it is possible to utilize it. There are functions which allow overriding the default cipher, digest and MAC implementations. Those are described below.

To override public key operations see Abstract private keys.

gnutls_crypto_register_cipher gnutls_crypto_register_aead_cipher gnutls_crypto_register_mac gnutls_crypto_register_digest