driver-only-builds: enhancing cipher related sections

Signed-off-by: Valerio Setti <valerio.setti@nordicsemi.no>

docs/driver-only-builds.md

@@ -243,8 +243,8 @@ The same holds for the associated algorithm:
 `[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_FFDH` allow builds accelerating FFDH and
 removing builtin support (i.e. `MBEDTLS_DHM_C`).
 
-Ciphers and AEADs
+Ciphers (unauthenticated and AEAD)
------------------
+----------------------------------
 
 It is possible to have all ciphers and AEAD operations provided only by a
 driver. More precisely, for each desired combination of key type and
@@ -291,7 +291,7 @@ algorithm/mode you can:
 Once a key type and related algorithm are accelerated, all the PSA Crypto APIs
 will work, as well as X.509 and TLS (with `MBEDTLS_USE_PSA_CRYPTO` enabled) but
 some non-PSA APIs will be absent or have reduced functionality, see
-[Disabling CIPHER_C](#disabling-cipher_c) for details.
+[Restrictions](#restrictions) for details.
 
 ### Restrictions
 
@@ -302,6 +302,29 @@ some non-PSA APIs will be absent or have reduced functionality, see
 - If a key type is enabled but not accelerated, then all algorithms than can be
   used with it will need to be built-in.
 
+Some legacy modules can't take advantage of PSA drivers yet, and will either
+need to be disabled, or have reduced features when the built-in implementations
+of some ciphers are removed:
+- `MBEDTLS_NIST_KW_C` needs built-in AES: it must be disabled when
+  `MBEDTLS_AES_C` is disabled.
+- `MBEDTLS_CMAC_C` needs built-in AES/DES: it must be disabled when
+  `MBEDTLS_AES_C` and `MBEDTLS_DES_C` are both disabled. When only one of them
+  is enabled, then only the corresponding cipher will be available at runtime
+  for use with `mbedtls_cipher_cmac_xxx`. (Note: if there is driver support for
+  CMAC and all compatible key types, then `PSA_WANT_ALG_CMAC` can be enabled
+  without `MBEDTLS_CMAC_C` and CMAC will be usable with `psa_max_xxx` APIs.)
+- `MBEDTLS_CIPHER_C`: the `mbedtls_cipher_xxx()` APIs will only work with
+  ciphers that are built-in - that is, both the underlying cipher
+  (eg `MBEDTLS_AES_C`) and the mode (eg `MBEDTLS_CIPHER_MODE_CBC` or
+  `MBEDTLS_GCM_C`).
+- `MBEDTLS_PKCS5_C`: encryption/decryption (PBES2, PBE) will only work with
+  ciphers that are built-in.
+- PEM decryption will only work with ciphers that are built-in.
+- PK parse will only be able to parse encrypted keys using built-in ciphers.
+
+Note that if you also disable `MBEDTLS_CIPHER_C`, there will be additional
+restrictions, see [Disabling `MBEDTLS_CIPHER_C`](#disabling-mbedtls_cipher_c).
+
 ### Legacy <-> PSA matching
 
 Note that the relationship between legacy (i.e. `MBEDTLS_xxx_C`) and PSA
@@ -323,11 +346,12 @@ Note that the relationship between legacy (i.e. `MBEDTLS_xxx_C`) and PSA
 
 In case legacy CCM/GCM algorithms are enabled, it is still possible to benefit
 from PSA acceleration of the underlying block cipher by enabling support for
-ECB mode (`PSA_WANT_ALG_ECB_NO_PADDING`) together with desired key type(s)
+ECB mode (`PSA_WANT_ALG_ECB_NO_PADDING` + `MBEDTLS_PSA_ACCEL_ALG_ECB_NO_PADDING`)
-(`PSA_WANT_KEY_TYPE_[AES|ARIA|CAMELLIA]`). In such configurations it is possible
+together with desired key type(s) (`PSA_WANT_KEY_TYPE_[AES|ARIA|CAMELLIA]` +
-to:
+`MBEDTLS_PSA_ACCEL_KEY_TYPE_[AES|ARIA|CAMELLIA]`).
-- Still benefit from legacy functions belonging to CCM/GCM modules
+In such configurations it is possible to:
-  (`mbedtls_[ccm|gcm]_xxx()`).
+- Use CCM and GCM via the PSA Crypto APIs.
+- Use CCM and GCM via legacy functions (`mbedtls_[ccm|gcm]_xxx()`).
 - Disable legacy key types (`MBEDTLS_[AES|ARIA|CAMELLIA]_C`) if there is no
   other dependency requiring them.
 
@@ -342,7 +366,7 @@ from PSA acceleration if both of the following conditions are met:
 - AES is supported on the PSA side together with ECB mode, i.e.
   `PSA_WANT_KEY_TYPE_AES` + `PSA_WANT_ALG_ECB_NO_PADDING`.
 
-### Disabling CIPHER_C
+### Disabling `MBEDTLS_CIPHER_C`
 
 It is possible to save code size by disabling MBEDTLS_CIPHER_C when all of the 
 following conditions are met:
@@ -351,6 +375,8 @@ following conditions are met:
   fully accelerated (that is, all compatible key types are accelerated too).
 - Either TLS is disabled, or `MBEDTLS_USE_PSA_CRYPTO` is enabled.
 - `MBEDTLS_NIST_KW` is disabled.
+- `MBEDTLS_CMAC_C` is disabled. (Note: support for CMAC in PSA can be provided by
+  a driver.)
 
 In such a build, everything will work as usual except for the following:
 - Encryption/decryption functions from the PKCS5 and PKCS12 module will not be
@@ -360,5 +386,8 @@ In such a build, everything will work as usual except for the following:
 Note: AEAD ciphers (CCM, GCM, ChachaPoly) do not have a dependency on
 MBEDTLS_CIPHER_C even when using the built-in implementations.
 
+If you also have some ciphers fully accelerated and the built-ins removed, see
+[Restrictions](#restrictions) for restrictions related to removing the built-ins.
+