From 6d84ae7e5786398b2d88c38b7b1c0d3f9e55c8bd Mon Sep 17 00:00:00 2001
From: Hanno Becker <hanno.becker@arm.com>
Date: Mon, 26 Jun 2017 12:46:19 +0100
Subject: [PATCH] Clarify documentation for alternative AES implementations

The functions mbedtls_aes_decrypt and mbedtls_aes_encrypt have been
superseded by mbedtls_aes_internal_decrypt and
mbedtls_aes_internal_encrypt, respectively. Alternative
implementations should now only replace the latter, and leave the
maintenance wrapper definitions of the former untouched.

This commit clarifies this in the documentation of the respective
configuration options MBEDTLS_AES_DECRYPT_ALT and
MBEDTLS_AES_ENCRYPT_ALT.
---
 include/mbedtls/aes.h    |  8 ++------
 include/mbedtls/config.h | 12 +++++++++---
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index b5560cc81..6044a51aa 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -287,9 +287,7 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief           Internal AES block encryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_ENCRYPT_ALT)
+ * \brief           Old AES block encryption function without return value.
  *
  * \deprecated      Superseded by mbedtls_aes_encrypt_ext() in 2.5.0
  *
@@ -306,9 +304,7 @@ MBEDTLS_DEPRECATED static inline void mbedtls_aes_encrypt(
 }
 
 /**
- * \brief           Internal AES block decryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_DECRYPT_ALT)
+ * \brief           Old AES block decryption function without return value.
  *
  * \deprecated      Superseded by mbedtls_aes_decrypt_ext() in 2.5.0
  *
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index c4b8995c1..2a2209a35 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -273,9 +273,15 @@
  * of mbedtls_sha1_context, so your implementation of mbedtls_sha1_process must be compatible
  * with this definition.
  *
- * Note: if you use the AES_xxx_ALT macros, then is is recommended to also set
- * MBEDTLS_AES_ROM_TABLES in order to help the linker garbage-collect the AES
- * tables.
+ * \note Because of a signature change, the core AES encryption and decryption routines are
+ *       currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt,
+ *       respectively. When setting up alternative implementations, these functions should
+ *       be overriden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
+ *       have to stay untouched.
+ *
+ * \note If you use the AES_xxx_ALT macros, then is is recommended to also set
+ *       MBEDTLS_AES_ROM_TABLES in order to help the linker garbage-collect the AES
+ *       tables.
  *
  * Uncomment a macro to enable alternate implementation of the corresponding
  * function.