yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-23 06:15:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation on parameter preconditions to ChaChaPoly modules

Browse source
This commit is contained in:
Hanno Becker 2018-12-11 14:52:01 +00:00
parent af0c6cb9e0
commit b3c10b348b
3 changed files with 55 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
include/mbedtls/chacha20.h
View file

@ -82,14 +82,15 @@ mbedtls_chacha20_context;
* to \c mbedtls_chacha20_update(), and finally to * to \c mbedtls_chacha20_update(), and finally to
* \c mbedtls_chacha20_free(). * \c mbedtls_chacha20_free().
* *
* \param ctx The ChaCha20 context to initialize. * \param ctx The ChaCha20 context to initialize. Must not be \c NULL.
*/ */
void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx ); void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
/** /**
* \brief This function releases and clears the specified ChaCha20 context. * \brief This function releases and clears the specified ChaCha20 context.
* *
* \param ctx The ChaCha20 context to clear. * \param ctx The ChaCha20 context to clear. May be \c NULL,
* in which case this function is a no-op.
*/ */
void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx ); void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
@ -102,6 +103,7 @@ void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
* \c mbedtls_chacha_update(). * \c mbedtls_chacha_update().
* *
* \param ctx The ChaCha20 context to which the key should be bound. * \param ctx The ChaCha20 context to which the key should be bound.
* Must be initialized.
* \param key The encryption/decryption key. Must be 32 bytes in length. * \param key The encryption/decryption key. Must be 32 bytes in length.
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -121,6 +123,7 @@ int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
* messages encrypted with the same nonce and key. * messages encrypted with the same nonce and key.
* *
* \param ctx The ChaCha20 context to which the nonce should be bound. * \param ctx The ChaCha20 context to which the nonce should be bound.
* Must be initialized.
* \param nonce The nonce. Must be 12 bytes in size. * \param nonce The nonce. Must be 12 bytes in size.
* \param counter The initial counter value. This is usually 0. * \param counter The initial counter value. This is usually 0.
* *
@ -150,16 +153,16 @@ int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
* key and nonce. * key and nonce.
* *
* \param ctx The ChaCha20 context to use for encryption or decryption. * \param ctx The ChaCha20 context to use for encryption or decryption.
* Must be initialized.
* \param size The length of the input data in bytes. * \param size The length of the input data in bytes.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* This pointer can be NULL if size == 0. * This pointer can be \c NULL if `size == 0`.
* \param output The buffer holding the output data. * \param output The buffer holding the output data.
* Must be able to hold \p size bytes. * Must be able to hold \p size bytes.
* This pointer can be NULL if size == 0. * This pointer can be \c NULL if `size == 0`.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or * \return A negative error code on failure.
* output pointers are NULL.
*/ */
int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx, int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
size_t size, size_t size,
@ -185,14 +188,13 @@ int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
* \param counter The initial counter value. This is usually 0. * \param counter The initial counter value. This is usually 0.
* \param size The length of the input data in bytes. * \param size The length of the input data in bytes.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* This pointer can be NULL if size == 0. * This pointer can be \c NULL if `size == 0`.
* \param output The buffer holding the output data. * \param output The buffer holding the output data.
* Must be able to hold \p size bytes. * Must be able to hold \p size bytes.
* This pointer can be NULL if size == 0. * This pointer can be \c NULL if `size == 0`.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input, * \return A negative error code on failure.
* or output is NULL.
*/ */
int mbedtls_chacha20_crypt( const unsigned char key[32], int mbedtls_chacha20_crypt( const unsigned char key[32],
const unsigned char nonce[12], const unsigned char nonce[12],

52
include/mbedtls/chachapoly.h
View file

@ -115,27 +115,29 @@ mbedtls_chachapoly_context;
* all previous outputs of \c mbedtls_chachapoly_update(), * all previous outputs of \c mbedtls_chachapoly_update(),
* otherwise you can now safely use the plaintext. * otherwise you can now safely use the plaintext.
* *
* \param ctx The ChachaPoly context to initialize. * \param ctx The ChachaPoly context to initialize. Must not be \c NULL.
*/ */
void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx ); void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
/** /**
* \brief This function releases and clears the specified ChaCha20-Poly1305 context. * \brief This function releases and clears the specified
* ChaCha20-Poly1305 context.
* *
* \param ctx The ChachaPoly context to clear. * \param ctx The ChachaPoly context to clear. May be \c NULL, in which
* case this function is a no-op.
*/ */
void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx ); void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
/** /**
* \brief This function sets the ChaCha20-Poly1305 symmetric encryption key. * \brief This function sets the ChaCha20-Poly1305
* symmetric encryption key.
* *
* \param ctx The ChaCha20-Poly1305 context to which the key should be * \param ctx The ChaCha20-Poly1305 context to which the key should be
* bound. * bound. Must be initialized.
* \param key The 256-bit (32 bytes) key. * \param key The 256-bit (32 bytes) key.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if \p ctx or \p key are NULL.
*/ */
int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
const unsigned char key[32] ); const unsigned char key[32] );
@ -155,14 +157,13 @@ int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
* \warning Decryption with the piecewise API is discouraged, see the * \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init(). * warning on \c mbedtls_chachapoly_init().
* *
* \param ctx The ChaCha20-Poly1305 context. * \param ctx The ChaCha20-Poly1305 context. Must be initialized.
* \param nonce The nonce/IV to use for the message. Must be 12 bytes. * \param nonce The nonce/IV to use for the message. Must be 12 bytes.
* \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or * \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
* #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning). * #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if \p ctx or \p mac are NULL.
*/ */
int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
const unsigned char nonce[12], const unsigned char nonce[12],
@ -227,20 +228,19 @@ int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx,
* \warning Decryption with the piecewise API is discouraged, see the * \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init(). * warning on \c mbedtls_chachapoly_init().
* *
* \param ctx The ChaCha20-Poly1305 context to use. * \param ctx The ChaCha20-Poly1305 context to use. Must be initialized.
* \param len The length (in bytes) of the data to encrypt or decrypt. * \param len The length (in bytes) of the data to encrypt or decrypt.
* \param input The buffer containing the data to encrypt or decrypt. * \param input The buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if len == 0. * This pointer can be \c NULL if `len == 0`.
* \param output The buffer to where the encrypted or decrypted data is written. * \param output The buffer to where the encrypted or decrypted data is
* Must be able to hold \p len bytes. * written. Must be able to hold \p len bytes.
* This pointer can be NULL if len == 0. * This pointer can be \c NULL if `len == 0`.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if \p ctx, \p input, or \p output are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been * if the operation has not been started or has been
* finished. * finished.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
size_t len, size_t len,
@ -251,18 +251,17 @@ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
* \brief This function finished the ChaCha20-Poly1305 operation and * \brief This function finished the ChaCha20-Poly1305 operation and
* generates the MAC (authentication tag). * generates the MAC (authentication tag).
* *
* \param ctx The ChaCha20-Poly1305 context to use. * \param ctx The ChaCha20-Poly1305 context to use. Must be initialized.
* \param mac The buffer to where the 128-bit (16 bytes) MAC is written. * \param mac The buffer to where the 128-bit (16 bytes) MAC is written.
* *
* \warning Decryption with the piecewise API is discouraged, see the * \warning Decryption with the piecewise API is discouraged, see the
* warning on \c mbedtls_chachapoly_init(). * warning on \c mbedtls_chachapoly_init().
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if \p ctx or \p mac are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
* if the operation has not been started or has been * if the operation has not been started or has been
* finished. * finished.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
unsigned char mac[16] ); unsigned char mac[16] );
@ -280,20 +279,20 @@ int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
* and key. * and key.
* *
* \param ctx The ChaCha20-Poly1305 context to use (holds the key). * \param ctx The ChaCha20-Poly1305 context to use (holds the key).
* Must be initialized.
* \param length The length (in bytes) of the data to encrypt or decrypt. * \param length The length (in bytes) of the data to encrypt or decrypt.
* \param nonce The 96-bit (12 bytes) nonce/IV to use. * \param nonce The 96-bit (12 bytes) nonce/IV to use.
* \param aad The buffer containing the additional authenticated data (AAD). * \param aad The buffer containing the additional authenticated data (AAD).
* This pointer can be NULL if aad_len == 0. * This pointer can be \c NULL if `aad_len == 0`.
* \param aad_len The length (in bytes) of the AAD data to process. * \param aad_len The length (in bytes) of the AAD data to process.
* \param input The buffer containing the data to encrypt or decrypt. * \param input The buffer containing the data to encrypt or decrypt.
* This pointer can be NULL if ilen == 0. * This pointer can be \c NULL if `ilen == 0`.
* \param output The buffer to where the encrypted or decrypted data is written. * \param output The buffer to where the encrypted or decrypted data is written.
* This pointer can be NULL if ilen == 0. * This pointer can be \c NULL if `ilen == 0`.
* \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written. * \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if one or more of the required parameters are NULL.
*/ */
int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx,
size_t length, size_t length,
@ -324,10 +323,9 @@ int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx,
* This pointer can be NULL if ilen == 0. * This pointer can be NULL if ilen == 0.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
* if one or more of the required parameters are NULL.
* \return #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED * \return #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
* if the data was not authentic. * if the data was not authentic.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx, int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
size_t length, size_t length,

34
include/mbedtls/poly1305.h
View file

@ -84,14 +84,15 @@ mbedtls_poly1305_context;
* \c mbedtls_poly1305_finish(), then finally * \c mbedtls_poly1305_finish(), then finally
* \c mbedtls_poly1305_free(). * \c mbedtls_poly1305_free().
* *
* \param ctx The Poly1305 context to initialize. * \param ctx The Poly1305 context to initialize. Must not be \c NULL.
*/ */
void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx ); void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
/** /**
* \brief This function releases and clears the specified Poly1305 context. * \brief This function releases and clears the specified Poly1305 context.
* *
* \param ctx The Poly1305 context to clear. * \param ctx The Poly1305 context to clear. May be \c NULL, in which
* case this function is a no-op.
*/ */
void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
@ -102,11 +103,11 @@ void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
* invocation of Poly1305. * invocation of Poly1305.
* *
* \param ctx The Poly1305 context to which the key should be bound. * \param ctx The Poly1305 context to which the key should be bound.
* \param key The buffer containing the 256-bit key. * Must be initialized.
* \param key The buffer containing the 32-byte (256-bit) key.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if ctx or key are NULL.
*/ */
int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx, int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
const unsigned char key[32] ); const unsigned char key[32] );
@ -120,13 +121,14 @@ int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
* It can be called repeatedly to process a stream of data. * It can be called repeatedly to process a stream of data.
* *
* \param ctx The Poly1305 context to use for the Poly1305 operation. * \param ctx The Poly1305 context to use for the Poly1305 operation.
* \param ilen The length of the input data (in bytes). Any value is accepted. * Must be initialized.
* \param ilen The length of the input data (in bytes).
* Any value is accepted.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* This pointer can be NULL if ilen == 0. * This pointer can be \c NULL if `ilen == 0`.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if ctx or input are NULL.
*/ */
int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx, int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
const unsigned char *input, const unsigned char *input,
@ -137,12 +139,12 @@ int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
* Authentication Code (MAC). * Authentication Code (MAC).
* *
* \param ctx The Poly1305 context to use for the Poly1305 operation. * \param ctx The Poly1305 context to use for the Poly1305 operation.
* Must be initialized.
* \param mac The buffer to where the MAC is written. Must be big enough * \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC. * to hold the 16-byte MAC.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if ctx or mac are NULL.
*/ */
int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx, int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
unsigned char mac[16] ); unsigned char mac[16] );
@ -154,16 +156,16 @@ int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
* \warning The key must be unique and unpredictable for each * \warning The key must be unique and unpredictable for each
* invocation of Poly1305. * invocation of Poly1305.
* *
* \param key The buffer containing the 256-bit key. * \param key The buffer containing the 32-byte (256-bit) key.
* \param ilen The length of the input data (in bytes). Any value is accepted. * \param ilen The length of the input data (in bytes).
* Any value is accepted.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* This pointer can be NULL if ilen == 0. * This pointer can be \c NULL if `ilen == 0`.
* \param mac The buffer to where the MAC is written. Must be big enough * \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC. * to hold the 16-byte MAC.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA * \return A negative error code on failure.
* if key, input, or mac are NULL.
*/ */
int mbedtls_poly1305_mac( const unsigned char key[32], int mbedtls_poly1305_mac( const unsigned char key[32],
const unsigned char *input, const unsigned char *input,