1@node Using GnuTLS as a cryptographic library 2@chapter Using GnuTLS as a cryptographic library 3 4@acronym{GnuTLS} is not a low-level cryptographic library, i.e., 5it does not provide access to basic cryptographic primitives. However 6it abstracts the internal cryptographic back-end (see @ref{Cryptographic Backend}), 7providing symmetric crypto, hash and HMAC algorithms, as well access 8to the random number generation. For a low-level crypto API the usage of nettle 9@footnote{See @uref{https://www.lysator.liu.se/~nisse/nettle/}.} library is recommended. 10 11@menu 12* Symmetric algorithms:: 13* Public key algorithms:: 14* Cryptographic Message Syntax / PKCS7:: 15* Hash and MAC functions:: 16* Random number generation:: 17* Overriding algorithms:: 18@end menu 19 20@node Symmetric algorithms 21@section Symmetric algorithms 22@cindex symmetric algorithms 23@cindex symmetric cryptography 24 25The available functions to access symmetric crypto algorithms operations 26are listed in the sections below. The supported algorithms are the algorithms required by the TLS protocol. 27They are listed in @ref{gnutls_cipher_algorithm_t}. Note that there two 28types of ciphers, the ones providing an authenticated-encryption with 29associated data (AEAD), and the legacy ciphers which provide raw access 30to the ciphers. We recommend the use of the AEAD ciphers under the AEAD APIs 31for new applications as they are designed to minimize the misuse of 32cryptographic primitives. 33 34@showenumdesc{gnutls_cipher_algorithm_t,The supported ciphers.} 35 36@subheading Authenticated-encryption API 37 38The AEAD API provides access to all ciphers supported by GnuTLS which support 39authenticated encryption with associated data; these ciphers are marked with 40the AEAD keyword on the table above. The AEAD cipher API is 41particularly suitable for message or packet-encryption as it provides 42authentication and encryption on the same API. See @code{RFC5116} for more 43information on authenticated encryption. 44 45@showfuncD{gnutls_aead_cipher_init,gnutls_aead_cipher_encrypt,gnutls_aead_cipher_decrypt,gnutls_aead_cipher_deinit} 46 47Because the encryption function above may be difficult to use with 48scattered data, we provide the following API. 49 50@showfuncdesc{gnutls_aead_cipher_encryptv} 51 52@subheading Legacy API 53 54The legacy API provides low-level access to all legacy ciphers supported by GnuTLS, 55and some of the AEAD ciphers (e.g., AES-GCM and CHACHA20). The restrictions 56of the nettle library implementation of the ciphers apply verbatim to this 57API@footnote{See the nettle manual @url{https://www.lysator.liu.se/~nisse/nettle/nettle.html}}. 58 59@showfuncE{gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit} 60 61@showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag} 62While the latter two functions allow the same API can be used with authenticated encryption ciphers, 63it is recommended to use the following functions which are solely for AEAD ciphers. The latter 64API is designed to be simple to use and also hard to misuse, by handling the tag verification 65and addition in transparent way. 66 67@node Public key algorithms 68@section Public key algorithms 69@cindex public key algorithms 70 71Public key cryptography algorithms such as RSA, DSA and ECDSA, are 72accessed using the abstract key API in @ref{Abstract key types}. This 73is a high level API with the advantage of transparently handling keys 74stored in memory and keys present in smart cards. 75 76@showfuncF{gnutls_privkey_init,gnutls_privkey_import_url,gnutls_privkey_import_x509_raw,gnutls_privkey_sign_data,gnutls_privkey_sign_hash,gnutls_privkey_deinit} 77 78@showfuncF{gnutls_pubkey_init,gnutls_pubkey_import_url,gnutls_pubkey_import_x509,gnutls_pubkey_verify_data2,gnutls_pubkey_verify_hash2,gnutls_pubkey_deinit} 79 80Keys stored in memory can be imported using functions like 81@funcref{gnutls_privkey_import_x509_raw}, while keys on smart cards or HSMs 82should be imported using their PKCS#11 URL with 83@funcref{gnutls_privkey_import_url}. 84 85If any of the smart card operations require PIN, that should be provided 86either by setting the global PIN function 87(@funcref{gnutls_pkcs11_set_pin_function}), or better with the targeted to 88structures functions such as @funcref{gnutls_privkey_set_pin_function}. 89 90 91@subsection Key generation 92 93All supported key types (including RSA, DSA, ECDSA, Ed25519, Ed448) can be generated 94with GnuTLS. They can be generated with the simpler @funcref{gnutls_privkey_generate} 95or with the more advanced @funcref{gnutls_privkey_generate2}. 96 97@showfuncdesc{gnutls_privkey_generate2} 98 99@node Cryptographic Message Syntax / PKCS7 100@section Cryptographic Message Syntax / PKCS7 101@cindex public key algorithms 102@cindex cryptographic message syntax 103@cindex file signing 104@cindex CMS 105@cindex PKCS #7 106 107The CMS or PKCS #7 format is a commonly used format for digital signatures. 108PKCS #7 is the name of the original standard when published by RSA, though 109today the standard is adopted by IETF under the name CMS. 110 111The standards include multiple ways of signing a digital document, e.g., 112by embedding the data into the signature, or creating detached signatures of the data, 113including a timestamp, additional certificates etc. In certain cases the 114same format is also used to transport lists of certificates and CRLs. 115 116It is a relatively popular standard to sign structures, and is being used to 117sign in PDF files, as well as for signing kernel modules and other 118structures. 119 120In GnuTLS, the basic functions to initialize, deinitialize, import, export or print information 121about a PKCS #7 structure are listed below. 122@showfuncE{gnutls_pkcs7_init,gnutls_pkcs7_deinit,gnutls_pkcs7_export2,gnutls_pkcs7_import,gnutls_pkcs7_print} 123 124The following functions allow the verification of a structure using either a trust list, or 125individual certificates. The @funcref{gnutls_pkcs7_sign} function is the data signing function. 126 127@showfuncB{gnutls_pkcs7_verify_direct,gnutls_pkcs7_verify} 128 129@showfuncdesc{gnutls_pkcs7_sign} 130 131@showenumdesc{gnutls_pkcs7_sign_flags,Flags applicable to gnutls_pkcs7_sign()} 132 133Other helper functions which allow to access the signatures, or certificates attached 134in the structure are listed below. 135 136@showfuncF{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} 137 138To append certificates, or CRLs in the structure the following functions are provided. 139@showfuncD{gnutls_pkcs7_set_crt_raw,gnutls_pkcs7_set_crt,gnutls_pkcs7_set_crl_raw,gnutls_pkcs7_set_crl} 140 141@node Hash and MAC functions 142@section Hash and MAC functions 143@cindex hash functions 144@cindex HMAC functions 145@cindex MAC functions 146 147The available operations to access hash functions and hash-MAC (HMAC) algorithms 148are shown below. HMAC algorithms provided keyed hash functionality. The supported MAC and HMAC 149algorithms are listed in @ref{gnutls_mac_algorithm_t}. Note that, despite the @code{hmac} part 150in the name of the MAC functions listed below, they can be used either for HMAC or MAC operations. 151 152@showenumdesc{gnutls_mac_algorithm_t,The supported MAC and HMAC algorithms.} 153 154@showfuncF{gnutls_hmac_init,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast} 155 156The available functions to access hash functions are shown below. The supported hash functions 157are shown in @ref{gnutls_digest_algorithm_t}. 158 159@showfuncF{gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast} 160@showfuncA{gnutls_fingerprint} 161 162@showenumdesc{gnutls_digest_algorithm_t,The supported hash algorithms.} 163 164@node Random number generation 165@section Random number generation 166@cindex random numbers 167 168Access to the random number generator is provided using the @funcref{gnutls_rnd} 169function. It allows obtaining random data of various levels. 170 171@showenumdesc{gnutls_rnd_level_t,The random number levels.} 172@showfuncdesc{gnutls_rnd} 173 174See @ref{Random Number Generators-internals} for more information 175on the random number generator operation. 176 177@node Overriding algorithms 178@section Overriding algorithms 179@cindex overriding algorithms 180 181In systems which provide a hardware accelerated cipher implementation 182that is not directly supported by GnuTLS, it is possible to utilize it. 183There are functions which allow overriding the default cipher, digest and MAC 184implementations. Those are described below. 185 186To override public key operations see @ref{Abstract private keys}. 187 188@showfuncdesc{gnutls_crypto_register_cipher} 189@showfuncdesc{gnutls_crypto_register_aead_cipher} 190@showfuncdesc{gnutls_crypto_register_mac} 191@showfuncdesc{gnutls_crypto_register_digest} 192