This commit adds the header file mbedtls/psa_util.h which contains
static utility functions `mbedtls_psa_xxx()` used in the integration
of PSA Crypto into Mbed TLS.
Warning: These functions are internal only and may change at any time.
Allow use of persistent keys, including configuring them, importing and
exporting them, and destroying them.
When getting a slot using psa_get_key_slot, there are 3 scenarios that
can occur if the keys lifetime is persistent:
1. Key type is PSA_KEY_TYPE_NONE, no persistent storage entry:
- The key slot is treated as a standard empty key slot
2. Key type is PSA_KEY_TYPE_NONE, persistent storage entry exists:
- Attempt to load the key from persistent storage
3. Key type is not PSA_KEY_TYPE_NONE:
- As checking persistent storage on every use of the key could
be expensive, the persistent key is assumed to be saved in
persistent storage, the in-memory key is continued to be used.
Add new functions, psa_load_persistent_key(),
psa_free_persistent_key_data(), and psa_save_persistent_key(), for
managing persistent keys. These functions load to or save from our
internal representation of key slots. Serialization is a concern of the
storage backend implementation and doesn't abstraction-leak into the
lifetime management code.
An initial implementation for files is provided. Additional storage
backends can implement this interface for other storage types.
Mbed TLS version 2.14.0
Resolved conflicts in include/mbedtls/config.h,
tests/scripts/check-files.py, and yotta/create-module.sh by removing yotta.
Resolved conflicts in tests/.jenkins/Jenkinsfile by continuing to run
mbedtls-psa job.
Add missing checks for defined(MBEDTLS_MD_C) around types and
functions that require it (HMAC, HKDF, TLS12_PRF).
Add missing checks for defined(MBEDTLS_ECDSA_DETERMINISTIC) around
code that calls mbedtls_ecdsa_sign_det().
Add missing checks for defined(MBEDTLS_ECDH_C) around ECDH-specific
functions.
This commit adds KDF algorithm identifiers `PSA_ALG_TLS12_PRF(HASH)`
to the PSA crypto API. They represent the key derivation functions
used by TLS 1.2 for the PreMasterSecret->MasterSecret and
MasterSecret->KeyBlock conversions.
Use m for the bit size of the field order, not q which is
traditionally the field order.
Correct and clarify the private key representation format as has been
done for the private key and ECDH shared secret formats.
The endianness actually depends on the curve type.
Correct the terminology around "curve size" and "order of the curve".
I tried to find a formulation that is comprehensible to programmers
who do not know the underlying mathematics, but nonetheless correct
and precise.
Use similar terminology in other places that were using "order of the
curve" to describe the bit size associated with the curve.
psa_key_derivation requires the caller to specify a maximum capacity.
This commit adds a special value that indicates that the maximum
capacity should be the maximum supported by the algorithm. This is
currently meant only for selection algorithms used on the shared
secret produced by a key agreement.
A key selection algorithm is similar to a key derivation algorithm in
that it takes a secret input and produces a secret output stream.
However, unlike key derivation algorithms, there is no expectation
that the input cannot be reconstructed from the output. Key selection
algorithms are exclusively meant to be used on the output of a key
agreement algorithm to select chunks of the shared secret.
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`.
Change the import/export format of private elliptic curve keys from
RFC 5915 to the raw secret value. This commit updates the format
specification and the import code, but not the export code.
Context:
The macro `MBEDTLS_ECP_BUDGET()` is called before performing a
number of potentially time-consuming ECC operations. If restartable
ECC is enabled, it wraps a call to `mbedtls_ecp_check_budget()`
which in turn checks if the requested number of operations can be
performed without exceeding the maximum number of consecutive ECC
operations.
Issue:
The function `mbedtls_ecp_check_budget()` expects a the number
of requested operations to be given as a value of type `unsigned`,
while some calls of the wrapper macro `MBEDTLS_ECP_BUDGET()` use
expressions of type `size_t`.
This rightfully leads to warnings about implicit truncation
from `size_t` to `unsigned` on some compilers.
Fix:
This commit makes the truncation explicit by adding an explicit cast
to `unsigned` in the expansion of the `MBEDTLS_ECP_BUDGET()` macro.
Justification:
Functionally, the new version is equivalent to the previous code.
The warning about truncation can be discarded because, as can be
inferred from `ecp.h`, the number of requested operations is never
larger than 1000.
Add extern "C" wrappers around type and function declarations to enable C++
interoperability of the driver header. This is done so that the driver
functions and types can be used or implmented by C++ code.
Convert PSA Crypto driver model structs to typedefs so that the `struct`
name doesn't need to be used and for consistent style with other PSA
structures.
The file crypto_driver.h was not using the header guard style as other PSA
Crypto header files. Remove the `__` prefix and suffix. Use C-style
comments for the end-of-guard comment.
The driver model's "encrypt or decrypt" type, encrypt_or_decrypt_t, is
publicly exposed and needs to have a `psa_` prefix in order to properly
communicate that it is part of the PSA driver model.
The `pcd_` prefix is ambiguous and does not make it clear that the types
and symbols are standardized by PSA. Replace `pcd_` with a prefix that can
be shared with all PSA drivers, `psa_drv_`.
"Driver APIs" can be interpreted to mean APIs used when you want to write a
driver, not the set of functions you implement to make a driver. See
https://www.kernel.org/doc/html/latest/driver-api/index.html "The kernel
offers a wide variety of interfaces to support the development of device
drivers."
As such, we are renaming "Driver API" to "Driver Model" and updating our
work so far to reflect this change.
Add comments noting that the maximum length of a MAC must fit in
PSA_ALG_MAC_TRUNCATION_MASK. Add a unit test that verifies that the
maximum MAC size fits.
Rename the PLATFORM HW error, to avoid ABI breakage with Mbed OS.
The value changed as well, as previous value was not in the range of
Mbed TLS low level error codes.
The previous comment in ecp.h that only functions that take a "restart
context" argument can restart was wrong due to ECDH and SSL functions.
Changing that criterion to "document says if can return IN PROGRESS".
This requires updating the documentation of the SSL functions to mention this
explicitly, but it's something we really ought to do anyway, a bit
embarrassing that this wasn't done already - callers need to know what
`MBEDTLS_ERR_SSL_xxx` error codes to special-case. Note that the documentation
of the relevant functions was in a suboptimal state, so it was improved in the
process - it could use some more improvement, but only the changes that helped
cleanly insert the info about the IN_PROGRESS part were done here.
Also, while updating the ecp.h comment, I noticed several functions in the
ECDH module were wrongfully documented as restartable, which is probably a
left-over from the days before `mbedtls_ecdh_enable_restart()` was introduced.
Fixing that as well, to make the criterion used in ecp.h correct.
When using a primality testing function the tolerable error rate depends
on the scheme in question, the required security strength and wether it
is used for key generation or parameter validation. To support all use
cases we need more flexibility than what the old API provides.
The FIPS 186-4 RSA key generation prescribes lower failure probability
in primality testing and this makes key generation slower. We enable the
caller to decide between compliance/security and performance.
This python script calculates the base two logarithm of the formulas in
HAC Fact 4.48 and was used to determine the breakpoints and number of
rounds:
def mrpkt_log_2(k, t):
if t <= k/9.0:
return 3*math.log(k,2)/2+t-math.log(t,2)/2+4-2*math.sqrt(t*k)
elif t <= k/4.0:
c1 = math.log(7.0*k/20,2)-5*t
c2 = math.log(1/7.0,2)+15*math.log(k,2)/4.0-k/2.0-2*t
c3 = math.log(12*k,2)-k/4.0-3*t
return max(c1, c2, c3)
else:
return math.log(1/7.0)+15*math.log(k,2)/4.0-k/2.0-2*t
