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.
We've changed the behavior of "-v" to no longer output test summary
statuses. Update basic-build-test.sh to use the test runner's verbosity
option "-v 2", so that the basic-build-test.sh script can get the summary
statuses it needs.
We initialized the ECC hardware before calling
mbedtls_ecp_mul_shortcuts(). This in turn calls
mbedtls_ecp_mul_restartable(), which initializes and frees the hardware
too. This issue has been introduced by recent changes and caused some
accelerators to hang.
We move the initialization after the mbedtle_ecp_mul_shortcuts() calls
to avoid double initialization.
The tests for the ECDH key exchange that use the context accessed it
directly. This can't work with the new context, where we can't make any
assumptions about the implementation of the context. This commit works
around this problem and comes with the cost of allocating an extra
structures on the stack when executing the test.
One of the tests is testing an older interface for the sake of backward
compatibility. The new ECDH context is not backward compatible and this
test doesn't make any sense for it, therefore we skip this test in
non-legacy mode.
The SSL module accesses ECDH context members directly. This can't work
with the new context, where we can't make any assumption about the
implementation of the context.
This commit makes use of the new functions to avoid accessing ECDH
members directly. The only members that are still accessed directly are
the group ID and the point format and they are independent from the
implementation.
The SSL module accesses ECDH context members directly to print debug
information. This can't work with the new context, where we can't make
assumptions about the implementation of the context. This commit adds
new debug functions to complete the encapsulation of the ECDH context
and work around the problem.
The functionality from public API functions are moved to
`xxx_internal()` functions. The public API functions are modified to do
basic parameter validation and dispatch the call to the right
implementation.
There is no intended change in behaviour when
`MBEDTLS_ECDH_LEGACY_CONTEXT` is enabled.
Programs must not include mbedtls/platform.h if MBEDTLS_PLATFORM_C is
not defined. Test suites don't need to include mbedtls/platform.h
because helpers.function takes care of it.
This commit also removes a stray `;` which is technically not standard C.
Some sample programs access structure fields directly. Making these work is
desirable in the long term, but these are not essential for the core
functionality in non-legacy mode.
We want to support alternative software implementations and we extend
the ECDH context to enable this. The actual functional change that makes
use of the new context is out of scope for this commit.
Changing the context breaks the API and therefore it has to be
excluded from the default configuration by a compile time flag.
We add the compile time flag to the module header instead of
`config.h`, because this is not a standalone feature, it only
enables adding new implementations in the future.
The new context features a union of the individual implementations
and a selector that chooses the implementation in use. An alternative
is to use an opaque context and function pointers, like for example the
PK module does it, but it is more dangerous, error prone and tedious to
implement.
We leave the group ID and the point format at the top level of the
structure, because they are very simple and adding an abstraction
layer around them away does not come with any obvious benefit.
Other alternatives considered:
- Using the module level replacement mechanism in the ECP module. This
would have made the use of the replacement feature more difficult and
the benefit limited.
- Replacing our Montgomery implementations with a new one directly. This
would have prevented using Montgomery curves across implementations.
(For example use implementation A for Curve448 and implementation B for
Curve22519.) Also it would have been inflexible and limited to
Montgomery curves.
- Encoding the implementation selector and the alternative context in
`mbedtls_ecp_point` somehow and rewriting `mbedtls_ecp_mul()` to
dispatch between implementations. This would have been a dangerous and
ugly hack, and very likely to break legacy applications.
- Same as above just with hardcoding the selector and using a compile
time option to make the selection. Rejected for the same reasons as
above.
- Using the PK module to provide to provide an entry point for
alternative implementations. Like most of the above options this
wouldn't have come with a new compile time option, but conceptually
would have been very out of place and would have meant much more work to
complete the abstraction around the context.
In retrospect:
- We could have used the group ID as the selector, but this would have
made the code less flexible and only marginally simpler. On the other
hand it would have allowed to get rid of the compile time option if a
tight integration of the alternative is possible. (It does not seem
possible at this point.)
- We could have used the same approach we do in this commit to the
`mbedtls_ecp_point` structure. Completing the abstraction around this
structure would have been a much bigger and much riskier code change
with increase in memory footprint, potential decrease in performance
and no immediate benefit.
The recently added `mbedtls_ecdh_setup()` function is not used in the
tests yet. This commit adapts the tests to the new workflow.
Having done that, the old lifecycle is not tested anymore, so we add a
new test to ensure backward compatibility.
In the future we want to support alternative ECDH implementations. We
can't make assumptions about the structure of the context they might
use, and therefore shouldn't access the members of
`mbedtls_ecdh_context`.
Currently the lifecycle of the context can't be done without direct
manipulation. This commit adds `mbedtls_ecdh_setup()` to complete
covering the context lifecycle with functions.
`mbedtls_ecp_tls_read_group()` both parses the group ID and loads the
group into the structure provided. We want to support alternative
implementations of ECDH in the future and for that we need to parse the
group ID without populating an `mbedtls_ecp_group` structure (because
alternative implementations might not use that).
This commit moves the part that parses the group ID to a new function.
There is no need to test the new function directly, because the tests
for `mbedtls_ecp_tls_read_group()` are already implicitly testing it.
There is no intended change in behaviour in this commit.
