Document all effects of MBEDTLS_ECP_RESTARTABLE

It might not be obvious that this option goes beyond adding new
functions, but also automagically modifies the behaviour of TLS
in some circumstances. Moreover, the exact modifications and
circumstances were not documented anywhere outside the ChangeLog.

Fix that.

While at it, adjust the test that checks no restartable behaviour with
other key exchanges, to use a key exchange that allows cert-based client
authentication so that we can check that this is not restartable either.

We don't have any automated test checking that the server is never
affected. That would require adding an ec_max_ops command-line option to
ssl_server2 that never has any effect, just to check that it indeed
doesn't. I'm not sure that's worth it. I tested manually and could
confirm that the server never has restartable behaviour, even for the
parts that are shared between client and server such as cert chain
verification.

Note (from re-reading the code): all restartable behaviour is controlled
by the flag ssl->handshake->ecrs_enabled which is only client-side with
the ECDHE-ECDSA key exchange (TLS 1.2).

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

include/mbedtls/mbedtls_config.h

@@ -690,11 +690,33 @@
  * This is useful in non-threaded environments if you want to avoid blocking
  * for too long on ECC (and, hence, X.509 or SSL/TLS) operations.
  *
- * Uncomment this macro to enable restartable ECC computations.
+ * This option:
+ * - Adds xxx_restartable() variants of existing operations in the
+ *   following modules, with corresponding restart context types:
+ *   - ECP: scalar multiplication (mult), linear combination (muladd);
+ *   - ECDSA: signature generation & verification;
+ *   - PK: signature generation & verification;
+ *   - X509: certificate chain verification.
+ * - Adds mbedtls_ecdh_enable_restart() in the ECDH module.
+ * - Changes the behaviour of TLS 1.2 clients (not servers) when using the
+ *   ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC
+ *   computations restartable:
+ *   - ECDH operations from the key exchange;
+ *   - verification of the server's key exchange signature;
+ *   - verification of the server's certificate chain;
+ *   - generation of our signature if client authentication is used, with an
+ *     ECC key/certificate.
+ *
+ * \note  In the cases above, the usual SSL/TLS functions, such as
+ *        mbedtls_ssl_handshake(), can now return
+ *        MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS.
  *
  * \note  This option only works with the default software implementation of
  *        elliptic curve functionality. It is incompatible with
- *        MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT.
+ *        MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT,
+ *        and MBEDTLS_USE_PSA_CRYPTO.
+ *
+ * Uncomment this macro to enable restartable ECC computations.
  */
 //#define MBEDTLS_ECP_RESTARTABLE
 

tests/ssl-opt.sh

@@ -8493,13 +8493,19 @@ run_test    "EC restart: TLS, max_ops=1000 no client auth" \
             -c "mbedtls_ecdh_make_public.*4b00" \
             -C "mbedtls_pk_sign.*4b00"
 
+
+# Restartable is only for ECDHE-ECDSA, with another ciphersuite we expect no
+# restartable behaviour at all (not even client auth).
+# This is the same as "EC restart: TLS, max_ops=1000" except with ECDHE-RSA,
+# and all 4 assertions negated.
 requires_config_enabled MBEDTLS_ECP_RESTARTABLE
 requires_config_enabled MBEDTLS_ECP_DP_SECP256R1_ENABLED
 requires_config_enabled MBEDTLS_SSL_PROTO_TLS1_2
-run_test    "EC restart: TLS, max_ops=1000, ECDHE-PSK" \
+run_test    "EC restart: TLS, max_ops=1000, ECDHE-RSA" \
-            "$P_SRV curves=secp256r1 psk=abc123" \
+            "$P_SRV curves=secp256r1 auth_mode=required" \
-            "$P_CLI force_ciphersuite=TLS-ECDHE-PSK-WITH-AES-128-CBC-SHA256 \
+            "$P_CLI force_ciphersuite=TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256 \
-             psk=abc123 debug_level=1 ec_max_ops=1000" \
+             key_file=data_files/server5.key crt_file=data_files/server5.crt  \
+             debug_level=1 ec_max_ops=1000" \
             0 \
             -C "x509_verify_cert.*4b00" \
             -C "mbedtls_pk_verify.*4b00" \