From 683c58253073809aad026f4c0ab1bc5d8453efe5 Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Fri, 7 Dec 2018 12:09:25 +0000 Subject: [PATCH] Clarify alternative ECP calling conventions Function calls to alternative implementations have to follow certain rules in order to preserve correct functionality. To avoid accidentally breaking these rules we state them explicitly in the ECP module for ourselves and every contributor to see. --- library/ecp.c | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/library/ecp.c b/library/ecp.c index e3b9106db..d9a3ac2f7 100644 --- a/library/ecp.c +++ b/library/ecp.c @@ -47,6 +47,35 @@ #include MBEDTLS_CONFIG_FILE #endif +/** + * \brief Function level alternative implementation. + * + * The MBEDTLS_ECP_INTERNAL_ALT macro enables alternative implementations to + * replace certain functions in this module. The alternative implementations are + * typically hardware accelerators and need to activate the hardware before the + * computation starts and deactivate it after it finishes. The + * mbedtls_internal_ecp_init() and mbedtls_internal_ecp_free() functions serve + * this purpose. + * + * To preserve the correct functionality the following conditions must hold: + * + * - The alternative implementation must be activated by + * mbedtls_internal_ecp_init() before any of the replaceable functions is + * called. + * - mbedtls_internal_ecp_free() must \b only be called when the alternative + * implementation is activated. + * - mbedtls_internal_ecp_init() must \b not be called when the alternative + * implementation is activated. + * - Public functions must not return while the alternative implementation is + * activated. + * - Replaceable functions are guarded by \c MBEDTLS_ECP_XXX_ALT macros and + * before calling them an \code if( mbedtls_internal_ecp_grp_capable( grp ) ) + * \endcode ensures that the alternative implementation supports the current + * group. + */ +#if defined(MBEDTLS_ECP_INTERNAL_ALT) +#endif + #if defined(MBEDTLS_ECP_C) #include "mbedtls/ecp.h"