From 2b7ad6472bb9f6c5e4df300ae8482936dbc11c34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 6 Dec 2022 10:42:44 +0100 Subject: [PATCH] Document all effects of MBEDTLS_ECP_RESTARTABLE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- include/mbedtls/mbedtls_config.h | 26 ++++++++++++++++++++++++-- tests/ssl-opt.sh | 14 ++++++++++---- 2 files changed, 34 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 826ab6459..b5f0bf2b4 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/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 diff --git a/tests/ssl-opt.sh b/tests/ssl-opt.sh index 1fe8baeb6..154ba348e 100755 --- a/tests/ssl-opt.sh +++ b/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" \ - "$P_SRV curves=secp256r1 psk=abc123" \ - "$P_CLI force_ciphersuite=TLS-ECDHE-PSK-WITH-AES-128-CBC-SHA256 \ - psk=abc123 debug_level=1 ec_max_ops=1000" \ +run_test "EC restart: TLS, max_ops=1000, ECDHE-RSA" \ + "$P_SRV curves=secp256r1 auth_mode=required" \ + "$P_CLI force_ciphersuite=TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256 \ + 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" \