Rename and document new configuration option for packing AES tables
This commit renames the new AES table packing option introduced in the
previous MBEDTLS_AES_PACK_TABLES and documents its use and memory vs.
speed tradeoff. It also enhances the documentation of the other
AES-related option MBEDTLS_AES_ROM_TABLES.
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 44def95..37a9d07 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -381,20 +381,41 @@
/**
* \def MBEDTLS_AES_ROM_TABLES
*
- * Store the AES tables in ROM.
+ * Use precomputed AES tables stored in ROM.
*
- * Uncomment this macro to store the AES tables in ROM.
+ * Uncomment this macro to use precomputed AES tables stored in ROM.
+ * Comment this macro to generate AES tables in RAM at runtime.
+ *
+ * Tradeoff: Using precomputed ROM tables reduces the time to setup
+ * an AES context but comes at the cost of additional 8192b ROM use
+ * (resp. 2048b if \c MBEDTLS_AES_FEWER_TABLES below is used).
+ *
+ * This option is independent of \c MBEDTLS_AES_FEWER_TABLES.
+ *
*/
//#define MBEDTLS_AES_ROM_TABLES
/**
- * \def MBEDTLS_AES_SMALL_TABLES
+ * \def MBEDTLS_AES_FEWER_TABLES
*
- * Use less ROM/RAM for the AES implementation (saves about 6144 bytes).
+ * Use less ROM/RAM for AES tables.
*
- * Uncomment this macro to use less memory for AES.
+ * Uncommenting this macro omits 75% of the AES tables from
+ * ROM / RAM (depending on the value of \c MBEDTLS_AES_ROM_TABLES)
+ * by computing their values on the fly during operations
+ * (the tables are entry-wise rotations of one another).
+ *
+ * Tradeoff: Uncommenting this reduces the RAM / ROM footprint
+ * by 6144b but at the cost of more arithmetic operations during
+ * runtime. Specifically, one has to compare 4 accesses within
+ * different tables to 4 accesses with additional arithmetic
+ * operations within the same table. The performance gain/loss
+ * depends on the system and memory details.
+ *
+ * This option is independent of \c MBEDTLS_AES_ROM_TABLES.
+ *
*/
-//#define MBEDTLS_AES_SMALL_TABLES
+//#define MBEDTLS_AES_FEWER_TABLES
/**
* \def MBEDTLS_CAMELLIA_SMALL_MEMORY
diff --git a/library/aes.c b/library/aes.c
index aabacf9..de43306 100644
--- a/library/aes.c
+++ b/library/aes.c
@@ -201,7 +201,7 @@
static const uint32_t FT0[256] = { FT };
#undef V
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
#define V(a,b,c,d) 0x##b##c##d##a
static const uint32_t FT1[256] = { FT };
@@ -215,7 +215,7 @@
static const uint32_t FT3[256] = { FT };
#undef V
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
#undef FT
@@ -332,7 +332,7 @@
static const uint32_t RT0[256] = { RT };
#undef V
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
#define V(a,b,c,d) 0x##b##c##d##a
static const uint32_t RT1[256] = { RT };
@@ -346,7 +346,7 @@
static const uint32_t RT3[256] = { RT };
#undef V
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
#undef RT
@@ -367,22 +367,22 @@
*/
static unsigned char FSb[256];
static uint32_t FT0[256];
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
static uint32_t FT1[256];
static uint32_t FT2[256];
static uint32_t FT3[256];
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
/*
* Reverse S-box & tables
*/
static unsigned char RSb[256];
static uint32_t RT0[256];
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
static uint32_t RT1[256];
static uint32_t RT2[256];
static uint32_t RT3[256];
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
/*
* Round constants
@@ -457,11 +457,11 @@
( (uint32_t) x << 16 ) ^
( (uint32_t) z << 24 );
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
FT1[i] = ROTL8( FT0[i] );
FT2[i] = ROTL8( FT1[i] );
FT3[i] = ROTL8( FT2[i] );
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
x = RSb[i];
@@ -470,11 +470,11 @@
( (uint32_t) MUL( 0x0D, x ) << 16 ) ^
( (uint32_t) MUL( 0x0B, x ) << 24 );
-#ifndef MBEDTLS_AES_SMALL_TABLES
+#ifndef MBEDTLS_AES_FEWER_TABLES
RT1[i] = ROTL8( RT0[i] );
RT2[i] = ROTL8( RT1[i] );
RT3[i] = ROTL8( RT2[i] );
-#endif /* !MBEDTLS_AES_SMALL_TABLES */
+#endif /* !MBEDTLS_AES_FEWER_TABLES */
}
}
@@ -482,7 +482,7 @@
#endif /* MBEDTLS_AES_ROM_TABLES */
-#ifdef MBEDTLS_AES_SMALL_TABLES
+#ifdef MBEDTLS_AES_FEWER_TABLES
#define ROTL8(x) ( (uint32_t)( ( x ) << 8 ) + (uint32_t)( ( x ) >> 24 ) )
#define ROTL16(x) ( (uint32_t)( ( x ) << 16 ) + (uint32_t)( ( x ) >> 16 ) )
@@ -498,7 +498,7 @@
#define AES_FT2(idx) ROTL16( FT0[idx] )
#define AES_FT3(idx) ROTL24( FT0[idx] )
-#else /* MBEDTLS_AES_SMALL_TABLES */
+#else /* MBEDTLS_AES_FEWER_TABLES */
#define AES_RT0(idx) RT0[idx]
#define AES_RT1(idx) RT1[idx]
@@ -510,7 +510,7 @@
#define AES_FT2(idx) FT2[idx]
#define AES_FT3(idx) FT3[idx]
-#endif /* MBEDTLS_AES_SMALL_TABLES */
+#endif /* MBEDTLS_AES_FEWER_TABLES */
void mbedtls_aes_init( mbedtls_aes_context *ctx )
{
diff --git a/library/version_features.c b/library/version_features.c
index 2b65199..549f40d 100644
--- a/library/version_features.c
+++ b/library/version_features.c
@@ -198,9 +198,9 @@
#if defined(MBEDTLS_AES_ROM_TABLES)
"MBEDTLS_AES_ROM_TABLES",
#endif /* MBEDTLS_AES_ROM_TABLES */
-#if defined(MBEDTLS_AES_SMALL_TABLES)
- "MBEDTLS_AES_SMALL_TABLES",
-#endif /* MBEDTLS_AES_SMALL_TABLES */
+#if defined(MBEDTLS_AES_FEWER_TABLES)
+ "MBEDTLS_AES_FEWER_TABLES",
+#endif /* MBEDTLS_AES_FEWER_TABLES */
#if defined(MBEDTLS_CAMELLIA_SMALL_MEMORY)
"MBEDTLS_CAMELLIA_SMALL_MEMORY",
#endif /* MBEDTLS_CAMELLIA_SMALL_MEMORY */