yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-01-26 00:41:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Correct and clarify the documentation of GCM whole-message functions

Browse source 
Clarify the roles of the buffer parameter and their sizes.

Remove a statement about input size restrictions that only applies to
mbedtls_gcm_update, not to the whole-message functions.

Document the possible error codes.

Warn that mbedtls_gcm_crypt_and_tag in decrypt mode does not
authenticate the data and recommend using mbedtls_gcm_auth_decrypt
instead.
This commit is contained in:
Gilles Peskine 2018-06-01 17:55:41 +02:00
parent 32605dc830
commit 282bd24a44
1 changed files with 32 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
include/mbedtls/gcm.h
View file

@ -106,20 +106,35 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
* If the buffers overlap, the output buffer must trail at least 8 Bytes * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input 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.
*
* \param ctx The GCM context to use for encryption or decryption. * \param ctx The GCM context to use for encryption or decryption.
* \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* #MBEDTLS_GCM_DECRYPT. * #MBEDTLS_GCM_DECRYPT. Note that during decryption, the
* \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). * tag is not verified. You should use this function only
* to encrypt data, and use mbedtls_gcm_auth_decrypt()
* to decrypt.
* \param length The length of the input data, which is equal to the length
* of the output data.
* \param iv The initialization vector. * \param iv The initialization vector.
* \param iv_len The length of the IV. * \param iv_len The length of the IV.
* \param add The buffer holding the additional data. * \param add The buffer holding the additional data.
* \param add_len The length of the additional data. * \param add_len The length of the additional data.
* \param input The buffer holding the input data. * \param input The buffer holding the input data. Its size is \b length.
* \param output The buffer for holding the output data. * \param output The buffer for holding the output data. It must have room
* for \b length bytes.
* \param tag_len The length of the tag to generate. * \param tag_len The length of the tag to generate.
* \param tag The buffer for holding the tag. * \param tag The buffer for holding the tag.
* *
* \return \c 0 on success. * \return \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.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
* \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
* error code if the encryption or decryption failed.
*/ */
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
int mode, int mode,
@ -142,18 +157,23 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
* behind the input buffer. * behind the input buffer.
* *
* \param ctx The GCM context. * \param ctx The GCM context.
* \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). * \param length The length of the ciphertext to decrypt, which is also
* the length of the decrypted plaintext.
* \param iv The initialization vector. * \param iv The initialization vector.
* \param iv_len The length of the IV. * \param iv_len The length of the IV.
* \param add The buffer holding the additional data. * \param add The buffer holding the additional data.
* \param add_len The length of the additional data. * \param add_len The length of the additional data.
* \param tag The buffer holding the tag. * \param tag The buffer holding the tag to verify.
* \param tag_len The length of the tag. * \param tag_len The length of the tag to verify.
* \param input The buffer holding the input data. * \param input The buffer holding the ciphertext. Its size is \b length.
* \param output The buffer for holding the output data. * \param output The buffer for holding the decrypted plaintext. It must
* have room for \b length bytes.
* *
* \return 0 if successful and authenticated, or * \return \c 0 if successful and authenticated.
* #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
* \return #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
* error code if the decryption failed.
*/ */
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length, size_t length,