yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-30 07:04:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update gcm.h

Browse Source 
Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*Suggest to specify issue for each return code, where multiple failure return codes are listed.
This commit is contained in:
Rose Zadik 2018-03-27 11:43:04 +01:00 committed by GitHub
parent f65379bc40
commit d8c4f61d26
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
include/mbedtls/gcm.h
View File

@ -1,7 +1,9 @@
/** /**
* \file gcm.h * \file gcm.h
* *
* \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined * \brief This file contains GCM definitions and functions.
*
* The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
* in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
* (GCM), Natl. Inst. Stand. Technol.</em> * (GCM), Natl. Inst. Stand. Technol.</em>
* *
@ -91,7 +93,8 @@ void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
* <li>192 bits</li> * <li>192 bits</li>
* <li>256 bits</li></ul> * <li>256 bits</li></ul>
* *
* \return \c 0 on success, or a cipher specific error code. * \return \c 0 on success.
* \return A cipher-specific error code on failure.
*/ */
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher, mbedtls_cipher_id_t cipher,
@ -101,15 +104,16 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
/** /**
* \brief This function performs GCM encryption or decryption of a buffer. * \brief This function performs GCM encryption or decryption of a buffer.
* *
* \note For encryption, the output buffer can be the same as the input buffer. * \note For encryption, the output buffer can be the same as the
* For decryption, the output buffer cannot be the same as input buffer. * input buffer. For decryption, the output buffer cannot be
* If the buffers overlap, the output buffer must trail at least 8 Bytes * the same as input buffer. If the buffers overlap, the output
* behind the input buffer. * buffer must trail at least 8 Bytes behind the input buffer.
* *
* \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.
* \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 input data. This must be a multiple of
* 16 except in the last call before mbedtls_gcm_finish().
* \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.
@ -137,12 +141,13 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
* \brief This function performs a GCM authenticated decryption of a * \brief This function performs a GCM authenticated decryption of a
* buffer. * buffer.
* *
* \note For decryption, the output buffer cannot be the same as input buffer. * \note For decryption, the output buffer cannot be the same as
* If the buffers overlap, the output buffer must trail at least 8 Bytes * input buffer. If the buffers overlap, the output buffer
* behind the input buffer. * must trail at least 8 Bytes 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 input data. This must be a multiple
* of 16 except in the last call before mbedtls_gcm_finish().
* \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.
@ -152,8 +157,8 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* \param output The buffer for holding the output data. * \param output The buffer for holding the output data.
* *
* \return 0 if successful and authenticated, or * \return 0 if successful and authenticated.
* #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
*/ */
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -175,8 +180,10 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
* #MBEDTLS_GCM_DECRYPT. * #MBEDTLS_GCM_DECRYPT.
* \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, or NULL if \p add_len is 0. * \param add The buffer holding the additional data, or NULL
* \param add_len The length of the additional data. If 0, \p add is NULL. * if \p add_len is 0.
* \param add_len The length of the additional data. If 0,
* \p add is NULL.
* *
* \return \c 0 on success. * \return \c 0 on success.
*/ */
@ -195,16 +202,18 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
* Bytes. Only the last call before calling * Bytes. Only the last call before calling
* mbedtls_gcm_finish() can be less than 16 Bytes. * mbedtls_gcm_finish() can be less than 16 Bytes.
* *
* \note For decryption, the output buffer cannot be the same as input buffer. * \note For decryption, the output buffer cannot be the same as
* If the buffers overlap, the output buffer must trail at least 8 Bytes * input buffer. If the buffers overlap, the output buffer
* behind the input buffer. * must trail at least 8 Bytes 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 input data. This must be a multiple of
* 16 except in the last call before mbedtls_gcm_finish().
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* \param output The buffer for holding the output data. * \param output The buffer for holding the output data.
* *
* \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure. * \return \c 0 on success.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_update( mbedtls_gcm_context *ctx, int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -222,7 +231,8 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
* \param tag The buffer for holding the tag. * \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four. * \param tag_len The length of the tag to generate. Must be at least four.
* *
* \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure. * \return \c 0 on success.
* \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag, unsigned char *tag,
@ -251,7 +261,8 @@ extern "C" {
/** /**
* \brief The GCM checkup routine. * \brief The GCM checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure. * \return \c 0 on success.
* \return \c 1 on failure.
*/ */
int mbedtls_gcm_self_test( int verbose ); int mbedtls_gcm_self_test( int verbose );