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


9.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 9.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 ciphers under the AEAD APIs for new applications as they are designed to minimize the misuse of cryptographic primitives.

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 (AEAD).

GNUTLS_CIPHER_AES_256_GCM

AES in GCM mode with 256-bit keys (AEAD).

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 (AEAD).

GNUTLS_CIPHER_CAMELLIA_256_GCM

CAMELLIA in GCM mode with 256-bit keys (AEAD).

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 (AEAD).

GNUTLS_CIPHER_AES_256_CCM

AES in CCM mode with 256-bit keys (AEAD).

GNUTLS_CIPHER_AES_128_CCM_8

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

GNUTLS_CIPHER_AES_256_CCM_8

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

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_AES_128_CFB8

AES in CFB8 mode with 128-bit keys.

GNUTLS_CIPHER_AES_192_CFB8

AES in CFB8 mode with 192-bit keys.

GNUTLS_CIPHER_AES_256_CFB8

AES in CFB8 mode with 256-bit keys.

GNUTLS_CIPHER_AES_128_XTS

AES in XTS mode with 128-bit key + 128bit tweak key.

GNUTLS_CIPHER_AES_256_XTS

AES in XTS mode with 256-bit key + 256bit tweak key. Note that the XTS ciphers are message oriented. The whole message needs to be provided with a single call, because cipher-stealing requires to know where the message actually terminates in order to be able to compute where the stealing occurs.

GNUTLS_CIPHER_GOST28147_TC26Z_CNT

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

GNUTLS_CIPHER_CHACHA20_64

Chacha20 cipher with 64-bit nonces and 64-bit block counters.

GNUTLS_CIPHER_CHACHA20_32

Chacha20 cipher with 96-bit nonces and 32-bit block counters.

GNUTLS_CIPHER_AES_128_SIV

AES in SIV mode with 128-bit key.

GNUTLS_CIPHER_AES_256_SIV

AES in SIV mode with 256-bit key. Note that the SIV ciphers can only be used with the AEAD interface, and the IV plays a role as the authentication tag while it is prepended to the cipher text.

GNUTLS_CIPHER_AES_192_GCM

AES in GCM mode with 192-bit keys (AEAD).

GNUTLS_CIPHER_MAGMA_CTR_ACPKM

GOST R 34.12-2015 (Magma) cipher in CTR-ACPKM mode.

GNUTLS_CIPHER_KUZNYECHIK_CTR_ACPKM

GOST R 34.12-2015 (Kuznyechik) cipher in CTR-ACPKM mode.

GNUTLS_CIPHER_AES_128_SIV_GCM

AES in SIV-GCM mode with 128-bit key.

GNUTLS_CIPHER_AES_256_SIV_GCM

AES in SIV-GCM mode with 256-bit key.

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 9.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; these ciphers are marked with the AEAD keyword on the table above. The AEAD cipher API 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: additional 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 including authentication tag

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

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

(22)

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


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