Document parameter preconditions for the ARIA module
diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index c80c9fd..54db1a6 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -91,14 +91,15 @@
* 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 @@
* \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:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \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 @@
* \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:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
*
- * \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 @@
* 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 @@
*
*
* \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 @@
*
*
* \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 @@
* 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,