From f35c42bdb9c1f4aced727d52534552a8f9f5ce68 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 31 May 2021 23:30:01 +0200 Subject: [PATCH] Document the remaining constraints on ALT context types Signed-off-by: Gilles Peskine --- ChangeLog.d/alt-context-relaxation.txt | 6 ++++++ docs/architecture/alternative-implementations.md | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 ChangeLog.d/alt-context-relaxation.txt diff --git a/ChangeLog.d/alt-context-relaxation.txt b/ChangeLog.d/alt-context-relaxation.txt new file mode 100644 index 000000000..10fd47619 --- /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 7b8b65ef3..4c4a2ad1b 100644 --- a/docs/architecture/alternative-implementations.md +++ b/docs/architecture/alternative-implementations.md @@ -40,6 +40,17 @@ The general principle of an alternative implementation is: 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).