CodeScopeSTM32 Libraries and SamplesmbedTLSmbedtls_gcm_crypt_and_tag()

mbedtls_gcm_crypt_and_tag() function

This function performs GCM encryption or decryption of a buffer. \warning When this function performs a decryption, it outputs the authentication tag and does not verify that the data is authentic. You should use this function to perform encryption only. For decryption, use mbedtls_gcm_auth_decrypt() instead.

Syntax

from gcm.h:170

int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mode, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, size_t tag_len, unsigned char *tag );

Implemented in gcm.c:467

Arguments

ctx

The GCM context to use for encryption or decryption. This must be initialized.

mode

The operation to perform: - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption. The ciphertext is written to \p output and the authentication tag is written to \p tag. - #MBEDTLS_GCM_DECRYPT to perform decryption. The plaintext is written to \p output and the authentication tag is written to \p tag. Note that this mode is not recommended, because it does not verify the authenticity of the data. For this reason, you should use mbedtls_gcm_auth_decrypt() instead of calling this function in decryption mode.

length

The length of the input data, which is equal to the length of the output data.

iv

The initialization vector. This must be a readable buffer of at least \p iv_len Bytes.

iv_len

The length of the IV.

add

The buffer holding the additional data. This must be of at least that size in Bytes.

add_len

The length of the additional data.

input

The buffer holding the input data. If \p length is greater than zero, this must be a readable buffer of at least that size in Bytes.

output

The buffer for holding the output data. If \p length is greater than zero, this must be a writable buffer of at least that size in Bytes.

tag_len

The length of the tag to generate.

tag

The buffer for holding the tag. This must be a readable buffer of at least \p tag_len Bytes.

Return value

\c 0 if the encryption or decryption was performed successfully. Note that in #MBEDTLS_GCM_DECRYPT mode, this does not indicate that the data is authentic. #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are not valid or a cipher-specific error code if the encryption or decryption failed.

Notes

For encryption, the output buffer can be the same as the input buffer. For decryption, the output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 Bytes behind the input buffer.

References

Location	Referrer	Text
gcm.c:467		int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
gcm.h:170		int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
cipher.c:1054	mbedtls_cipher_auth_encrypt()	return( mbedtls_gcm_crypt_and_tag( ctx->cipher_ctx, MBEDTLS_GCM_ENCRYPT, ilen,
gcm.c:523	mbedtls_gcm_auth_decrypt()	if( ( ret = mbedtls_gcm_crypt_and_tag( ctx, MBEDTLS_GCM_DECRYPT, length,