Next: , Up: Using GnuTLS as a cryptographic library   [Contents][Index]


8.1 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 Figure 8.1. 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_UNKNOWN

Value to identify an unknown/unsupported algorithm.

GNUTLS_CIPHER_NULL

The NULL (identity) encryption algorithm.

GNUTLS_CIPHER_ARCFOUR_128

ARCFOUR stream cipher with 128-bit keys.

GNUTLS_CIPHER_3DES_CBC

3DES in CBC mode.

GNUTLS_CIPHER_AES_128_CBC

AES in CBC mode with 128-bit keys.

GNUTLS_CIPHER_AES_256_CBC

AES in CBC mode with 256-bit keys.

GNUTLS_CIPHER_ARCFOUR_40

ARCFOUR stream cipher with 40-bit keys.

GNUTLS_CIPHER_CAMELLIA_128_CBC

Camellia in CBC mode with 128-bit keys.

GNUTLS_CIPHER_CAMELLIA_256_CBC

Camellia in CBC mode with 256-bit keys.

GNUTLS_CIPHER_AES_192_CBC

AES in CBC mode with 192-bit keys.

GNUTLS_CIPHER_AES_128_GCM

AES in GCM mode with 128-bit keys.

GNUTLS_CIPHER_AES_256_GCM

AES in GCM mode with 256-bit keys.

GNUTLS_CIPHER_CAMELLIA_192_CBC

Camellia in CBC mode with 192-bit keys.

GNUTLS_CIPHER_SALSA20_256

Salsa20 with 256-bit keys.

GNUTLS_CIPHER_ESTREAM_SALSA20_256

Estream’s Salsa20 variant with 256-bit keys.

GNUTLS_CIPHER_CAMELLIA_128_GCM

CAMELLIA in GCM mode with 128-bit keys.

GNUTLS_CIPHER_CAMELLIA_256_GCM

CAMELLIA in GCM mode with 256-bit keys.

GNUTLS_CIPHER_RC2_40_CBC

RC2 in CBC mode with 40-bit keys.

GNUTLS_CIPHER_DES_CBC

DES in CBC mode (56-bit keys).

GNUTLS_CIPHER_AES_128_CCM

AES in CCM mode with 128-bit keys.

GNUTLS_CIPHER_AES_256_CCM

AES in CCM mode with 256-bit keys.

GNUTLS_CIPHER_AES_128_CCM_8

AES in CCM mode with 64-bit tag and 128-bit keys.

GNUTLS_CIPHER_AES_256_CCM_8

AES in CCM mode with 64-bit tag and 256-bit keys.

GNUTLS_CIPHER_CHACHA20_POLY1305

The Chacha20 cipher with the Poly1305 authenticator (AEAD).

GNUTLS_CIPHER_GOST28147_TC26Z_CFB

GOST 28147-89 (Magma) cipher in CFB mode with TC26 Z S-box.

GNUTLS_CIPHER_GOST28147_CPA_CFB

GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro A S-box.

GNUTLS_CIPHER_GOST28147_CPB_CFB

GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro B S-box.

GNUTLS_CIPHER_GOST28147_CPC_CFB

GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro C S-box.

GNUTLS_CIPHER_GOST28147_CPD_CFB

GOST 28147-89 (Magma) cipher in CFB mode with CryptoPro D S-box.

GNUTLS_CIPHER_IDEA_PGP_CFB

IDEA in CFB mode (placeholder - unsupported).

GNUTLS_CIPHER_3DES_PGP_CFB

3DES in CFB mode (placeholder - unsupported).

GNUTLS_CIPHER_CAST5_PGP_CFB

CAST5 in CFB mode (placeholder - unsupported).

GNUTLS_CIPHER_BLOWFISH_PGP_CFB

Blowfish in CFB mode (placeholder - unsupported).

GNUTLS_CIPHER_SAFER_SK128_PGP_CFB

Safer-SK in CFB mode with 128-bit keys (placeholder - unsupported).

GNUTLS_CIPHER_AES128_PGP_CFB

AES in CFB mode with 128-bit keys (placeholder - unsupported).

GNUTLS_CIPHER_AES192_PGP_CFB

AES in CFB mode with 192-bit keys (placeholder - unsupported).

GNUTLS_CIPHER_AES256_PGP_CFB

AES in CFB mode with 256-bit keys (placeholder - unsupported).

GNUTLS_CIPHER_TWOFISH_PGP_CFB

Twofish in CFB mode (placeholder - unsupported).

Figure 8.1: 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.

int gnutls_aead_cipher_init (gnutls_aead_cipher_hd_t * handle, gnutls_cipher_algorithm_t cipher, const gnutls_datum_t * key)
int gnutls_aead_cipher_encrypt (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const void * auth, size_t auth_len, size_t tag_size, const void * ptext, size_t ptext_len, void * ctext, size_t * ctext_len)
int gnutls_aead_cipher_decrypt (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const void * auth, size_t auth_len, size_t tag_size, const void * ctext, size_t ctext_len, void * ptext, size_t * ptext_len)
void gnutls_aead_cipher_deinit (gnutls_aead_cipher_hd_t handle)

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

Function: int gnutls_aead_cipher_encryptv (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const giovec_t * auth_iov, int auth_iovcnt, size_t tag_size, const giovec_t * iov, int iovcnt, void * ctext, size_t * ctext_len)

handle: is a gnutls_aead_cipher_hd_t type.

nonce: the nonce to set

nonce_len: The length of the nonce

auth_iov: the data to be authenticated

auth_iovcnt: The number of buffers in auth_iov

tag_size: The size of the tag to use (use zero for the default)

iov: the data to be encrypted

iovcnt: The number of buffers in iov

ctext: the encrypted data

ctext_len: the length of encrypted data (initially must hold the maximum available size, including space for tag)

This function will encrypt the provided data buffers using the algorithm specified by the context. The output data will contain the authentication tag.

Returns: Zero or a negative error code on error.

Since: 3.6.3

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 API23.

int gnutls_cipher_init (gnutls_cipher_hd_t * handle, gnutls_cipher_algorithm_t cipher, const gnutls_datum_t * key, const gnutls_datum_t * iv)
int gnutls_cipher_encrypt2 (gnutls_cipher_hd_t handle, const void * ptext, size_t ptext_len, void * ctext, size_t ctext_len)
int gnutls_cipher_decrypt2 (gnutls_cipher_hd_t handle, const void * ctext, size_t ctext_len, void * ptext, size_t ptext_len)
void gnutls_cipher_set_iv (gnutls_cipher_hd_t handle, void * iv, size_t ivlen)
void gnutls_cipher_deinit (gnutls_cipher_hd_t handle)
int gnutls_cipher_add_auth (gnutls_cipher_hd_t handle, const void * ptext, size_t ptext_size)
int gnutls_cipher_tag (gnutls_cipher_hd_t handle, void * tag, size_t tag_size)

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.


Footnotes

(23)

See the nettle manual https://www.lysator.liu.se/~nisse/nettle/nettle.html


Next: , Up: Using GnuTLS as a cryptographic library   [Contents][Index]