Merge development commit 8e76332 into development-psa
Additional changes to temporarily enable running tests:
ssl_srv.c and test_suite_ecdh use mbedtls_ecp_group_load instead of
mbedtls_ecdh_setup
test_suite_ctr_drbg uses mbedtls_ctr_drbg_update instead of
mbedtls_ctr_drbg_update_ret
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index cfb20c4..94e7282 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -121,7 +121,7 @@
* It must be the first API called before using
* the context.
*
- * \param ctx The AES context to initialize.
+ * \param ctx The AES context to initialize. This must not be \c NULL.
*/
void mbedtls_aes_init( mbedtls_aes_context *ctx );
@@ -129,6 +129,8 @@
* \brief This function releases and clears the specified AES context.
*
* \param ctx The AES context to clear.
+ * If this is \c NULL, this function does nothing.
+ * Otherwise, the context must have been at least initialized.
*/
void mbedtls_aes_free( mbedtls_aes_context *ctx );
@@ -139,7 +141,7 @@
* It must be the first API called before using
* the context.
*
- * \param ctx The AES XTS context to initialize.
+ * \param ctx The AES XTS context to initialize. This must not be \c NULL.
*/
void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
@@ -147,6 +149,8 @@
* \brief This function releases and clears the specified AES XTS context.
*
* \param ctx The AES XTS context to clear.
+ * If this is \c NULL, this function does nothing.
+ * Otherwise, the context must have been at least initialized.
*/
void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
#endif /* MBEDTLS_CIPHER_MODE_XTS */
@@ -155,7 +159,9 @@
* \brief This function sets the encryption key.
*
* \param ctx The AES context to which the key should be bound.
+ * It must be initialized.
* \param key The encryption key.
+ * This 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>
@@ -171,7 +177,9 @@
* \brief This function sets the decryption key.
*
* \param ctx The AES context to which the key should be bound.
+ * It must be initialized.
* \param key The decryption key.
+ * This 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>
@@ -189,8 +197,10 @@
* sets the encryption key.
*
* \param ctx The AES XTS context to which the key should be bound.
+ * It must be initialized.
* \param key The encryption key. This is comprised of the XTS key1
* concatenated with the XTS key2.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of \p key passed in bits. Valid options are:
* <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
* <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -207,8 +217,10 @@
* sets the decryption key.
*
* \param ctx The AES XTS context to which the key should be bound.
+ * It must be initialized.
* \param key The decryption key. This is comprised of the XTS key1
* concatenated with the XTS key2.
+ * This must be a readable buffer of size \p keybits bits.
* \param keybits The size of \p key passed in bits. Valid options are:
* <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
* <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -234,10 +246,13 @@
* call to this API with the same context.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param input The 16-Byte buffer holding the input data.
- * \param output The 16-Byte buffer holding the output data.
+ * \param input The buffer holding the input data.
+ * It must be readable and at least \c 16 Bytes long.
+ * \param output The buffer where the output data will be written.
+ * It must be writeable and at least \c 16 Bytes long.
* \return \c 0 on success.
*/
@@ -260,8 +275,8 @@
* mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
* before the first call to this API with the same context.
*
- * \note This function operates on aligned blocks, that is, the input size
- * must be a multiple of the AES block size of 16 Bytes.
+ * \note This function operates on full blocks, that is, the input size
+ * must be a multiple of the AES block size of \c 16 Bytes.
*
* \note Upon exit, the content of the IV is updated so that you can
* call the same function again on the next
@@ -272,13 +287,17 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data in Bytes. This must be a
- * multiple of the block size (16 Bytes).
+ * multiple of the block size (\c 16 Bytes).
* \param iv Initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
@@ -306,9 +325,10 @@
* returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.
*
* \param ctx The AES XTS context to use for AES XTS operations.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param length The length of a data unit in bytes. This can be any
+ * \param length The length of a data unit in Bytes. This can be any
* length between 16 bytes and 2^24 bytes inclusive
* (between 1 and 2^20 block cipher blocks).
* \param data_unit The address of the data unit encoded as an array of 16
@@ -316,15 +336,15 @@
* is typically the index of the block device sector that
* contains the data.
* \param input The buffer holding the input data (which is an entire
- * data unit). This function reads \p length bytes from \p
+ * data unit). This function reads \p length Bytes from \p
* input.
* \param output The buffer holding the output data (which is an entire
- * data unit). This function writes \p length bytes to \p
+ * data unit). This function writes \p length Bytes to \p
* output.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is
- * smaller than an AES block in size (16 bytes) or if \p
+ * smaller than an AES block in size (16 Bytes) or if \p
* length is larger than 2^20 blocks (16 MiB).
*/
int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,
@@ -360,13 +380,18 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
- * \param length The length of the input data.
+ * \param length The length of the input data in Bytes.
* \param iv_off The offset in IV (updated after use).
+ * It must point to a valid \c size_t.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -401,12 +426,16 @@
*
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT
* \param length The length of the input data.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -451,11 +480,16 @@
* will compromise security.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \param length The length of the input data.
* \param iv_off The offset in IV (updated after use).
+ * It must point to a valid \c size_t.
* \param iv The initialization vector (updated after use).
+ * It must be a readable and writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -527,15 +561,21 @@
* securely discarded as soon as it's no longer needed.
*
* \param ctx The AES context to use for encryption or decryption.
+ * It must be initialized and bound to a key.
* \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.
+ * It must point to a valid \c size_t.
* \param nonce_counter The 128-bit nonce and counter.
+ * It must be a readable-writeable buffer of \c 16 Bytes.
* \param stream_block The saved stream block for resuming. This is
* overwritten by the function.
+ * It must be a readable-writeable buffer of \c 16 Bytes.
* \param input The buffer holding the input data.
+ * It must be readable and of size \p length Bytes.
* \param output The buffer holding the output data.
+ * It must be writeable and of size \p length Bytes.
*
* \return \c 0 on success.
*/
@@ -588,7 +628,7 @@
* \brief Deprecated internal AES block encryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_encrypt()
*
* \param ctx The AES context to use for encryption.
* \param input Plaintext block.
@@ -602,7 +642,7 @@
* \brief Deprecated internal AES block decryption function
* without return value.
*
- * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
+ * \deprecated Superseded by mbedtls_internal_aes_decrypt()
*
* \param ctx The AES context to use for decryption.
* \param input Ciphertext block.
@@ -615,6 +655,8 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+#if defined(MBEDTLS_SELF_TEST)
/**
* \brief Checkup routine.
*
@@ -623,6 +665,8 @@
*/
int mbedtls_aes_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
+
#ifdef __cplusplus
}
#endif