From 139d8313d904a27d7d1d60cbb32faf1b487ee954 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 11 Dec 2018 21:29:27 +0000 Subject: [PATCH] Document parameter preconditions for the ARIA module --- include/mbedtls/aria.h | 51 +++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h index c80c9fd26..54db1a637 100644 --- a/include/mbedtls/aria.h +++ b/include/mbedtls/aria.h @@ -91,14 +91,15 @@ mbedtls_aria_context; * It must be the first API called before using * the context. * - * \param ctx The ARIA context to initialize. + * \param ctx The ARIA context to initialize. Must not be \c NULL. */ void mbedtls_aria_init( mbedtls_aria_context *ctx ); /** * \brief This function releases and clears the specified ARIA context. * - * \param ctx The ARIA context to clear. + * \param ctx The ARIA context to clear. May be \c NULL, in which + * case this function is a no-op. */ void mbedtls_aria_free( mbedtls_aria_context *ctx ); @@ -106,14 +107,16 @@ void mbedtls_aria_free( mbedtls_aria_context *ctx ); * \brief This function sets the encryption key. * * \param ctx The ARIA context to which the key should be bound. - * \param key The encryption key. + * Must be initialized. + * \param key The encryption key. Must be a readable buffer + * of size \p keybits bits. * \param keybits The size of data passed in bits. Valid options are: * * - * \return \c 0 on success or #MBEDTLS_ERR_ARIA_BAD_INPUT_DATA - * on failure. + * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx, const unsigned char *key, @@ -123,13 +126,16 @@ int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx, * \brief This function sets the decryption key. * * \param ctx The ARIA context to which the key should be bound. - * \param key The decryption key. + * Must be initialized. + * \param key The decryption key. Must be a readable buffer + * of size \p keybits bits. * \param keybits The size of data passed. Valid options are: * * - * \return \c 0 on success, or #MBEDTLS_ERR_ARIA_BAD_INPUT_DATA on failure. + * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx, const unsigned char *key, @@ -148,10 +154,12 @@ int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx, * call to this API with the same context. * * \param ctx The ARIA context to use for encryption or decryption. + * Must be initialized. * \param input The 16-Byte buffer holding the input data. * \param output The 16-Byte buffer holding the output data. * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx, const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE], @@ -183,16 +191,20 @@ int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx, * * * \param ctx The ARIA context to use for encryption or decryption. + * Must be initialized. * \param mode The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or * #MBEDTLS_ARIA_DECRYPT. * \param length The length of the input data in Bytes. This must be a * multiple of the block size (16 Bytes). * \param iv Initialization vector (updated after use). + * Must be a readable buffer of size 16 Bytes. * \param input The buffer holding the input data. + * May be \c NULL if `length == 0`. * \param output The buffer holding the output data. + * May be \c NULL if `length == 0`. * - * \return \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH - * on failure. + * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx, int mode, @@ -227,15 +239,21 @@ int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx, * * * \param ctx The ARIA context to use for encryption or decryption. + * Must be initialized. * \param mode The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or * #MBEDTLS_ARIA_DECRYPT. * \param length The length of the input data. * \param iv_off The offset in IV (updated after use). + * Must not be larger than 15. * \param iv The initialization vector (updated after use). + * Must be a readable buffer of size 16 Bytes. * \param input The buffer holding the input data. + * May be \c NULL if `length == 0`. * \param output The buffer holding the output data. + * May be \c NULL if `length == 0`. * * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx, int mode, @@ -305,17 +323,24 @@ int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx, * securely discarded as soon as it's no longer needed. * * \param ctx The ARIA context to use for encryption or decryption. + * Must be initialized. * \param length The length of the input data. * \param nc_off The offset in the current \p stream_block, for * resuming within the current cipher stream. The * offset pointer should be 0 at the start of a stream. - * \param nonce_counter The 128-bit nonce and counter. - * \param stream_block The saved stream block for resuming. This is - * overwritten by the function. + * Must not be larger than 15. + * \param nonce_counter The 128-bit nonce and counter. Must point to + * an RW-buffer of length 16 bytes. + * \param stream_block The saved stream block for resuming. Must point to + * an RW-buffer of length 16 bytes. + * This is overwritten by the function. * \param input The buffer holding the input data. + * May be \c NULL if `length == 0`. * \param output The buffer holding the output data. + * May be \c NULL if `length == 0`. * - * \return \c 0 on success. + * \return \c 0 on success. + * \return A negative error code on failure. */ int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx, size_t length,