From 12558db3f0e1186eb4184da61841060f7a71c54d Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Wed, 27 Feb 2019 09:29:04 +0100 Subject: Improve documentation for gnutls_cipher_get_iv_size This clarifies what is returned and what is to be expected on algorithms with variable IV sizes. Resolves: #717 Signed-off-by: Nikos Mavrogiannopoulos --- lib/algorithms/ciphers.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/algorithms/ciphers.c b/lib/algorithms/ciphers.c index 1a8704be25..e5bd7dfcd3 100644 --- a/lib/algorithms/ciphers.c +++ b/lib/algorithms/ciphers.c @@ -341,7 +341,9 @@ unsigned gnutls_cipher_get_tag_size(gnutls_cipher_algorithm_t algorithm) * gnutls_cipher_get_iv_size: * @algorithm: is an encryption algorithm * - * Get block size for encryption algorithm. + * This function returns the size of the initialization vector (IV) for the + * provided algorithm. For algorithms with variable size IV (e.g., AES-CCM), + * the returned size will be the one used by TLS. * * Returns: block size for encryption algorithm. * @@ -358,7 +360,7 @@ unsigned gnutls_cipher_get_iv_size(gnutls_cipher_algorithm_t algorithm) * gnutls_cipher_get_key_size: * @algorithm: is an encryption algorithm * - * Get key size for cipher. + * This function returns the key size of the provided algorithm. * * Returns: length (in bytes) of the given cipher's key size, or 0 if * the given cipher is invalid. -- cgit v1.2.1 From 1184ab2b3890d4de9f342636ec8d2977f460b06e Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Wed, 27 Feb 2019 10:01:47 +0100 Subject: Clarifications on AEAD ciphers Relates: #716 Signed-off-by: Nikos Mavrogiannopoulos --- lib/crypto-api.c | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/lib/crypto-api.c b/lib/crypto-api.c index cb7012fd12..2dd888997d 100644 --- a/lib/crypto-api.c +++ b/lib/crypto-api.c @@ -668,20 +668,22 @@ int gnutls_aead_cipher_init(gnutls_aead_cipher_hd_t *handle, * @handle: is a #gnutls_aead_cipher_hd_t type. * @nonce: the nonce to set * @nonce_len: The length of the nonce - * @auth: the data to be authenticated + * @auth: additional data to be authenticated * @auth_len: The length of the data * @tag_size: The size of the tag to use (use zero for the default) - * @ctext: the data to decrypt + * @ctext: the data to decrypt (including the authentication tag) * @ctext_len: the length of data to decrypt (includes tag size) * @ptext: the decrypted data * @ptext_len: the length of decrypted data (initially must hold the maximum available size) * * This function will decrypt the given data using the algorithm - * specified by the context. This function must be provided the whole - * data to be decrypted, including the tag, and will fail if the tag - * verification fails. + * specified by the context. This function must be provided the complete + * data to be decrypted, including the authentication tag. On several + * AEAD ciphers, the authentication tag is appended to the ciphertext, + * though this is not a general rule. This function will fail if + * the tag verification fails. * - * Returns: Zero or a negative error code on error. + * Returns: Zero or a negative error code on verification failure or other error. * * Since: 3.4.0 **/ @@ -725,12 +727,12 @@ gnutls_aead_cipher_decrypt(gnutls_aead_cipher_hd_t handle, * @handle: is a #gnutls_aead_cipher_hd_t type. * @nonce: the nonce to set * @nonce_len: The length of the nonce - * @auth: the data to be authenticated + * @auth: additional data to be authenticated * @auth_len: The length of the data * @tag_size: The size of the tag to use (use zero for the default) * @ptext: the data to encrypt * @ptext_len: The length of data to encrypt - * @ctext: the encrypted data + * @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 given data using the algorithm @@ -919,12 +921,12 @@ static int copy_iov(struct iov_store_st *dst, const giovec_t *iov, int iovcnt) * @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_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 + * @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 -- cgit v1.2.1