Document the remaining constraints on ALT context types
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/ChangeLog.d/alt-context-relaxation.txt b/ChangeLog.d/alt-context-relaxation.txt
new file mode 100644
index 0000000..10fd476
--- /dev/null
+++ b/ChangeLog.d/alt-context-relaxation.txt
@@ -0,0 +1,6 @@
+Features
+ * Alternative implementations of the AES, DHM, ECJPAKE, ECP, RSA and timing
+ modules had undocumented constraints on their context types. These
+ constraints have been relaxed.
+ See docs/architecture/alternative-implementations.md for the remaining
+ constraints.
diff --git a/docs/architecture/alternative-implementations.md b/docs/architecture/alternative-implementations.md
index 7b8b65e..4c4a2ad 100644
--- a/docs/architecture/alternative-implementations.md
+++ b/docs/architecture/alternative-implementations.md
@@ -40,6 +40,17 @@
See https://tls.mbed.org/kb/development/hw_acc_guidelines for a more detailed guide.
+### Constraints on context types
+
+Generally, alternative implementations can define their context types to any C type except incomplete and array types (although they would normally be `struct` types). This section lists some known limitations where the context type needs to be a structure with certain fields.
+
+Where a context type needs to have a certain field, the field must have the same type and semantics as in the built-in implementation, but does not need to be at the same position in the structure. Furthermore, unless otherwise indicated, only read access is necessary: the field can be `const`, and modifications to it do not need to be supported. For example, if an alternative implementation of asymmetric cryptography uses a different representation of large integers, it is sufficient to provide a read-only copy of the fields listed here of type `mbedtls_mpi`.
+
+* AES: if `MBEDTLS_AESNI_C` or `MBEDTLS_PADLOCK_C` is enabled, `mbedtls_aes_context` must have the fields `nr` and `rk`.
+* DHM: if `MBEDTLS_DEBUG_C` is enabled, `mbedtls_dhm_context` must have the fields `P`, `Q`, `G`, `GX`, `GY` and `K`.
+* ECP: `mbedtls_ecp_group` must have the fields `id`, `P`, `A`, `B`, `G`, `N`, `pbits` and `nbits`.
+ * If `MBEDTLS_PK_PARSE_EC_EXTENDED` is enabled, those fields must be writable, and `mbedtls_ecp_point_read_binary()` must support a group structure where only `P`, `pbits`, `A` and `B` are set.
+
## Function alternative implementations
In some cases, it is possible to replace a single function or a small set of functions instead of [providing an alternative implementation of the whole module](#module-alternative-implementations).