Document when a context must be initialized or not, when it must be
set up or not, and whether it needs a private key or a public key will
do.
The implementation is sometimes more liberal than the documentation,
accepting a non-set-up context as a context that can't perform the
requested information. This preserves backward compatibility.
For mbedtls_pk_parse_key and mbedtls_pk_parse_keyfile, the password is
optional. Clarify what this means: NULL is ok and means no password.
Validate parameters and test accordingly.
A 0-length buffer for the key is a legitimate edge case. Ensure that
it works, even with buf=NULL. Document the key and keylen parameters.
There are already test cases for parsing an empty buffer. A subsequent
commit will add tests for writing to an empty buffer.
- Be specific about the constraints: be a readable/writable buffer of length
X, be an initialized context, be a context initialized and bound to a key...
- Always use full sentences with all the required pronouns.
It's better if the macro receives the condition as an expression rather than a
string - that way it can choose to use it as is or stringify it. Also, the
documentation states that the parameter is an expression, not a string.
The test framework for validation of parameters depends on the macro
MBEDTLS_PARAM_FAILED() being set to its default value when building the
library. So far the test framework attempted to define this macro but this was
the wrong place - this definition wouldn't be picked by the library.
Instead, a different approach is taken: skip those tests when the macro is
defined in config.h, as in that case we have no way to know if it will indeed
end up calling mbedtls_param_failed() as we need it to.
This commit was tested by manually ensuring that aes_invalid_params:
- passes (and is not skipped) in the default configuration
- is skipped when MBEDTLS_PARAM_FAILED() is defined in config.h
The previous prototype gave warnings are the strings produced by #cond and
__FILE__ are const, so we shouldn't implicitly cast them to non-const.
While at it modifying most example programs:
- include the header that has the function declaration, so that the definition
can be checked to match by the compiler
- fix whitespace
- make it work even if PLATFORM_C is not defined:
- CHECK_PARAMS is not documented as depending on PLATFORM_C and there is
no reason why it should
- so, remove the corresponding #if defined in each program...
- and add missing #defines for mbedtls_exit when needed
The result has been tested (make all test with -Werror) with the following
configurations:
- full with CHECK_PARAMS with PLATFORM_C
- full with CHECK_PARAMS without PLATFORM_C
- full without CHECK_PARAMS without PLATFORM_C
- full without CHECK_PARAMS with PLATFORM_C
Additionally, it has been manually tested that adding
mbedtls_aes_init( NULL );
near the normal call to mbedtls_aes_init() in programs/aes/aescrypt2.c has the
expected effect when running the program.
It was inconsistent between files: sometimes 3 arguments, sometimes one.
Align to 1 argument for the macro and 3 for the function, because:
- we don't need 3 arguments for the macro, it can add __FILE__ and __LINE__
in its expansion, while the function needs them as parameters to be correct;
- people who re-defined the macro should have flexibility, and 3 arguments
can give the impression they they don't have as much as they actually do;
- the design document has the macro with 1 argument, so let's stick to that.
The function called through the macro MBEDTLS_PARAM_FAILED() must be supplied by
users and makes no sense as a library function, apart from debug and test.
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.
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.
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.
Deprecate the module-specific XXX_HW_ACCEL_FAILED and
XXX_FEATURE_UNAVAILABLE errors, as alternative implementations should now
return `MBEDTLS_ERR_PLATFORM_HW_FAILED` and
`MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED`.
