mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-11-26 21:35:39 +01:00
Update gcm.h
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
GitHub
parent
f65379bc40
commit
d8c4f61d26
@ -1,9 +1,11 @@
|
|||||||
/**
|
/**
|
||||||
* \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.
|
||||||
* in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
|
*
|
||||||
* (GCM), Natl. Inst. Stand. Technol.</em>
|
* The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
|
||||||
|
* in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
|
||||||
|
* (GCM), Natl. Inst. Stand. Technol.</em>
|
||||||
*
|
*
|
||||||
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
|
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
|
||||||
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
|
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</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,10 +180,12 @@ 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.
|
||||||
*/
|
*/
|
||||||
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
|
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
|
||||||
int mode,
|
int mode,
|
||||||
@ -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 );
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user