The sanity checking script tests/scripts/check-names.sh uses a
simple state machine paired with a sequence of `sed` commands to
extract enumeration constants from the code. This code, however,
doesn't work properly when using multiline comments in enumerations
such as recently done in the constants MBEDTLS_CIPHER_PSA_KEY_XXX.
This commit doesn't attempt to make check-names.sh more robust
but instead uses /* ... */ comment indicators in each comment line,
while silences check-names.sh.
Increasing the robustness of check-names.sh is instead tracked
in #2210.
mbedtls_cipher_setup_psa() should return
MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE when the requested
cipher is not supported by PSA, so that the caller can
try the original mbedtls_cipher_setup() instead.
The previous version of mbedtls_cipher_setup_psa(), however,
only attempted to translate the cipher mode (GCM, CCM, CBC,
ChaChaPoly, Stream), but didn't consider the underlying
cipher primitive. Hence, it wouldn't fail when attempting
to setup a cipher context for, say, 3DES-CBC, where CBC
is currently supported by PSA but 3DES isn't.
This commit adds a check to mbedtls_cipher_setup_psa()
for whether the requested cipher primitive is available
in the underlying PSA Crypto implementation, and fails
cleanly with MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE if
it is isn't.
For AEAD ciphers, the information contained in mbedtls_cipher_info
is not enough to deduce a PSA algorithm value of type psa_algorithm_t.
This is because mbedtls_cipher_info doesn't contain the AEAD tag
length, while values of type psa_algorithm_t do.
This commit adds the AEAD tag length as a separate parameter
to mbedtls_cipher_setup_psa(). For Non-AEAD ciphers, the value
must be 0.
This approach is preferred over passing psa_algorithm_t directly
in order to keep the changes in existing code using the cipher layer
small.
Mbed TLS cipher layer allows usage of keys for other purposes
than indicated in the `operation` parameter of `mbedtls_cipher_setkey()`.
The semantics of the PSA Crypto API, in contrast, checks key
usage against the key policy.
As a remedy, this commit modifies the PSA key slot setup to
always allow both encryption and decryption.
This commit implements the internal key slot management performed
by PSA-based cipher contexts. Specifically, `mbedtls_cipher_setkey()`
wraps the provided raw key material into a key slot, and
`mbedtls_cipher_free()` destroys that key slot.
This field determines whether a cipher context should
use an external implementation of the PSA Crypto API for
cryptographic operations, or Mbed TLS' own crypto library.
The commit also adds dummy implementations for the cipher API.
Otherwise, if `mbedtls_psa_get_free_key_slot()` fails to find a fresh
key slot, the slot value will be undefined, and the call to
`psa_destroy_key()` at the end of `main()` is undefined behavior.
Previously, command line arguments `psk_slot` and `psk_list_slot`
could be used to indicate the PSA key slots that the example
applications should use to store the PSK(s) provided.
This commit changes this approach to use the utility function
`mbedtls_psa_get_free_key_slot()` to obtain free key slots from
the PSA Crypto implementation automatically, so that users only
need to pass boolean flags `psk_opaque` and `psk_list_opaque`
on the command line to enable / disable PSA-based opaque PSKs.
The code maintains the invariant that raw and opaque PSKs are never
configured simultaneously, so strictly speaking `ssl_conf_remove_psk()`
need not consider clearing the raw PSK if it has already cleared an
opaque one - and previously, it didn't. However, it doesn't come at
any cost to keep this check as a safe-guard to future unforeseen
situations where opaque and raw PSKs _are_ both present.
In multiple places, it occurrs as the fixed length of
the master secret, so use a constant with a descriptive
name instead. This is reinforced by the fact the some
further occurrences of '48' are semantically different.
This commit adds command line parameters `psk_slot` and `psk_list_slot`
to the example application `programs/ssl/ssl_server2`. These have the
following semantics:
- `psk_slot`: The same semantics as for the `ssl_client2` example
application. That is, if a PSK is configured through the use
of the command line parameters `psk` and `psk_identity`, then
`psk_slot=X` can be used to import the PSK into PSA key slot X
and registering it statically with the SSL configuration through
the new API call mbedtls_ssl_conf_hs_opaque().
- `psk_list_slot`: In addition to the static PSK registered in the
the SSL configuration, servers can register a callback for picking
the PSK corresponding to the PSK identity that the client chose.
The `ssl_server2` example application uses such a callback to select
the PSK from a list of PSKs + Identities provided through the
command line parameter `psk_list`, and to register the selected
PSK via `mbedtls_ssl_set_hs_psk()`. In this case, the new parameter
`psk_list_slot=X` has the effect of registering all PSKs provided in
in `psk_list` as PSA keys in the key slots starting from slot `X`,
and having the PSK selection callback register the chosen PSK
through the new API function `mbedtls_ssl_set_hs_psk_opaque()`.
This commit adds support for the use of PSA-based opaque PSKs
in the TLS client example application programs/ssl/ssl_client2.
Specifically, a numerical command line option `psk_slot` with
the following constraints and semantics is added:
- It can only be used alongside the provisioning of a raw PSK
through the preexisting `psk` command line option.
- It can only be used if both TLS 1.2 and a PSK-only ciphersuite
are enforced through the appropriate use of the `min_version`
and `force_ciphersuite` command line options.
- If the previous conditions are met, setting `psk_slot=d` will
result in the PSA key slot with identifier `d` being populated
with the raw PSK data specified through the `psk` parameter
and passed to Mbed TLS via `mbedtls_ssl_conf_psk_opaque()`
prior to the handshake.
Enforcing the TLS version and ciphersuite is necessary to determine
the exact KDF algorithm the PSK will be used for. This is required
as it is currently not possible to set up a key without specifying
exactly one algorithm the key may be used with.
This commit adds a field `psk_opaque` to the handshake parameter
struct `mbedtls_ssl_handshake_params` which indicates if the user
has configured the use of an opaque PSK.
This commit adds two public API functions
mbedtls_ssl_conf_psk_opaque()
mbedtls_ssl_set_hs_psk_opaque()
which allow to configure the use of opaque, PSA-maintained PSKs
at configuration time or run time.
