mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-12-24 17:41:01 +03:00
Manuel Pégourié-Gonnard
GitHub
@@ -55,7 +55,15 @@ For now, only the following (families of) mechanisms are supported:
|
||||
- hashes: SHA-3, SHA-2, SHA-1, MD5, etc.
|
||||
- elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types.
|
||||
- finite-field Diffie-Hellman: FFDH algorithm, DH key types.
|
||||
- AEADs: GCM, CCM and ChachaPoly
|
||||
- AEADs:
|
||||
- GCM and CCM with AES, ARIA and Camellia key types
|
||||
- ChachaPoly with ChaCha20 Key type
|
||||
- Unauthenticated ciphers:
|
||||
- key types: AES, ARIA, Camellia, DES
|
||||
- modes: ECB, CBC, CTR, CFB, OFB, XTS
|
||||
|
||||
For each family listed above, all the mentioned alorithms/key types are also
|
||||
all the mechanisms that exist in PSA API.
|
||||
|
||||
Supported means that when those are provided only by drivers, everything
|
||||
(including PK, X.509 and TLS if `MBEDTLS_USE_PSA_CRYPTO` is enabled) should
|
||||
@@ -63,9 +71,6 @@ work in the same way as if the mechanisms where built-in, except as documented
|
||||
in the "Limitations" sub-sections of the sections dedicated to each family
|
||||
below.
|
||||
|
||||
In the near future (end of 2023), we are planning to also add support for
|
||||
ciphers (AES, ARIA, Camellia).
|
||||
|
||||
Currently (mid-2023) we don't have plans to extend this to RSA. If
|
||||
you're interested in driver-only support for RSA, please let us know.
|
||||
|
||||
@@ -238,37 +243,151 @@ The same holds for the associated algorithm:
|
||||
`[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_FFDH` allow builds accelerating FFDH and
|
||||
removing builtin support (i.e. `MBEDTLS_DHM_C`).
|
||||
|
||||
### Limitations
|
||||
Support for deterministic derivation of a DH keypair
|
||||
(i.e. `PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_DERIVE`) is not supported.
|
||||
Ciphers (unauthenticated and AEAD)
|
||||
----------------------------------
|
||||
|
||||
AEADs
|
||||
-----
|
||||
It is possible to have all ciphers and AEAD operations provided only by a
|
||||
driver. More precisely, for each desired combination of key type and
|
||||
algorithm/mode you can:
|
||||
- Enable desired PSA key type(s):
|
||||
- `PSA_WANT_KEY_TYPE_AES`,
|
||||
- `PSA_WANT_KEY_TYPE_ARIA`,
|
||||
- `PSA_WANT_KEY_TYPE_CAMELLIA`,
|
||||
- `PSA_WANT_KEY_TYPE_CHACHA20`,
|
||||
- `PSA_WANT_KEY_TYPE_DES`.
|
||||
- Enable desired PSA algorithm(s):
|
||||
- Unauthenticated ciphers modes:
|
||||
- `PSA_WANT_ALG_CBC_NO_PADDING`,
|
||||
- `PSA_WANT_ALG_CBC_PKCS7`,
|
||||
- `PSA_WANT_ALG_CCM_STAR_NO_TAG`,
|
||||
- `PSA_WANT_ALG_CFB`,
|
||||
- `PSA_WANT_ALG_CTR`,
|
||||
- `PSA_WANT_ALG_ECB_NO_PADDING`,
|
||||
- `PSA_WANT_ALG_OFB`,
|
||||
- `PSA_WANT_ALG_STREAM_CIPHER`.
|
||||
- AEADs:
|
||||
- `PSA_WANT_ALG_CCM`,
|
||||
- `PSA_WANT_ALG_GCM`,
|
||||
- `PSA_WANT_ALG_CHACHA20_POLY1305`.
|
||||
- Enable `MBEDTLS_PSA_ACCEL_[KEY_TYPE_xxx|ALG_yyy]` symbol(s) which correspond
|
||||
to the `PSA_WANT_KEY_TYPE_xxx` and `PSA_WANT_ALG_yyy` of the previous steps.
|
||||
- Disable builtin support of key types:
|
||||
- `MBEDTLS_AES_C`,
|
||||
- `MBEDTLS_ARIA_C`,
|
||||
- `MBEDTLS_CAMELLIA_C`,
|
||||
- `MBEDTLS_DES_C`,
|
||||
- `MBEDTLS_CHACHA20_C`.
|
||||
and algorithms/modes:
|
||||
- `MBEDTLS_CBC_C`,
|
||||
- `MBEDTLS_CFB_C`,
|
||||
- `MBEDTLS_CTR_C`,
|
||||
- `MBEDTLS_OFB_C`,
|
||||
- `MBEDTLS_XTS_C`,
|
||||
- `MBEDTLS_CCM_C`,
|
||||
- `MBEDTLS_GCM_C`,
|
||||
- `MBEDTLS_CHACHAPOLY_C`,
|
||||
- `MBEDTLS_NULL_CIPHER`.
|
||||
|
||||
[This section might contain incomplete data and it is going to be updated in
|
||||
#8358, i.e. the wrap-up task for accelerated ciphers and AEADs.]
|
||||
Once a key type and related algorithm are accelerated, all the PSA Crypto APIs
|
||||
will work, as well as X.509 and TLS (with `MBEDTLS_USE_PSA_CRYPTO` enabled) but
|
||||
some non-PSA APIs will be absent or have reduced functionality, see
|
||||
[Restrictions](#restrictions) for details.
|
||||
|
||||
It is possible to have all AEADs operations provided only by a driver.
|
||||
### Restrictions
|
||||
|
||||
- If an algorithm other than CCM and GCM (see
|
||||
["Partial acceleration for CCM/GCM"](#partial-acceleration-for-ccmgcm) below)
|
||||
is enabled but not accelerated, then all key types that can be used with it
|
||||
will need to be built-in.
|
||||
- If a key type is enabled but not accelerated, then all algorithms that can be
|
||||
used with it will need to be built-in.
|
||||
|
||||
Some legacy modules can't take advantage of PSA drivers yet, and will either
|
||||
need to be disabled, or have reduced features when the built-in implementations
|
||||
of some ciphers are removed:
|
||||
- `MBEDTLS_NIST_KW_C` needs built-in AES: it must be disabled when
|
||||
`MBEDTLS_AES_C` is disabled.
|
||||
- `MBEDTLS_CMAC_C` needs built-in AES/DES: it must be disabled when
|
||||
`MBEDTLS_AES_C` and `MBEDTLS_DES_C` are both disabled. When only one of them
|
||||
is enabled, then only the corresponding cipher will be available at runtime
|
||||
for use with `mbedtls_cipher_cmac_xxx`. (Note: if there is driver support for
|
||||
CMAC and all compatible key types, then `PSA_WANT_ALG_CMAC` can be enabled
|
||||
without `MBEDTLS_CMAC_C` and CMAC will be usable with `psa_max_xxx` APIs.)
|
||||
- `MBEDTLS_CIPHER_C`: the `mbedtls_cipher_xxx()` APIs will only work with
|
||||
ciphers that are built-in - that is, both the underlying cipher
|
||||
(eg `MBEDTLS_AES_C`) and the mode (eg `MBEDTLS_CIPHER_MODE_CBC` or
|
||||
`MBEDTLS_GCM_C`).
|
||||
- `MBEDTLS_PKCS5_C`: encryption/decryption (PBES2, PBE) will only work with
|
||||
ciphers that are built-in.
|
||||
- PEM decryption will only work with ciphers that are built-in.
|
||||
- PK parse will only be able to parse encrypted keys using built-in ciphers.
|
||||
|
||||
Note that if you also disable `MBEDTLS_CIPHER_C`, there will be additional
|
||||
restrictions, see [Disabling `MBEDTLS_CIPHER_C`](#disabling-mbedtls_cipher_c).
|
||||
|
||||
### Legacy <-> PSA matching
|
||||
|
||||
Note that the relationship between legacy (i.e. `MBEDTLS_xxx_C`) and PSA
|
||||
(i.e. `PSA_WANT_xxx`) symbols is not always 1:1. For example:
|
||||
- ECB mode is always enabled in the legacy configuration for each key type that
|
||||
allows it (AES, ARIA, Camellia, DES), whereas it must be explicitly enabled
|
||||
in PSA with `PSA_WANT_ALG_ECB_NO_PADDING`.
|
||||
- In the legacy API, `MBEDTLS_CHACHA20_C` enables the ChaCha20 stream cipher, and
|
||||
enabling `MBEDTLS_CHACHAPOLY_C` also enables the ChaCha20-Poly1305 AEAD. In the
|
||||
PSA API, you need to enable `PSA_KEY_TYPE_CHACHA20` for both, plus
|
||||
`PSA_ALG_STREAM_CIPHER` or `PSA_ALG_CHACHA20_POLY1305` as desired.
|
||||
- The legacy symbol `MBEDTLS_CCM_C` adds support for both cipher and AEAD,
|
||||
whereas in PSA there are 2 different symbols: `PSA_WANT_ALG_CCM_STAR_NO_TAG`
|
||||
and `PSA_WANT_ALG_CCM`, respectively.
|
||||
|
||||
### Partial acceleration for CCM/GCM
|
||||
|
||||
[This section depends on #8598 so it might be updated while that PR progresses.]
|
||||
|
||||
In case legacy CCM/GCM algorithms are enabled, it is still possible to benefit
|
||||
from PSA acceleration of the underlying block cipher by enabling support for
|
||||
ECB mode (`PSA_WANT_ALG_ECB_NO_PADDING` + `MBEDTLS_PSA_ACCEL_ALG_ECB_NO_PADDING`)
|
||||
together with desired key type(s) (`PSA_WANT_KEY_TYPE_[AES|ARIA|CAMELLIA]` +
|
||||
`MBEDTLS_PSA_ACCEL_KEY_TYPE_[AES|ARIA|CAMELLIA]`).
|
||||
In such configurations it is possible to:
|
||||
- Use CCM and GCM via the PSA Crypto APIs.
|
||||
- Use CCM and GCM via legacy functions (`mbedtls_[ccm|gcm]_xxx()`).
|
||||
- Disable legacy key types (`MBEDTLS_[AES|ARIA|CAMELLIA]_C`) if there is no
|
||||
other dependency requiring them.
|
||||
|
||||
ChaChaPoly has no such feature, so it requires full acceleration (key type +
|
||||
algorithm) in order to work with a driver.
|
||||
|
||||
### CTR-DRBG
|
||||
|
||||
The legacy CTR-DRBG module (enabled by `MBEDTLS_CTR_DRBG_C`) can also benefit
|
||||
from PSA acceleration if both of the following conditions are met:
|
||||
- The legacy AES module (`MBEDTLS_AES_C`) is not enabled and
|
||||
- AES is supported on the PSA side together with ECB mode, i.e.
|
||||
`PSA_WANT_KEY_TYPE_AES` + `PSA_WANT_ALG_ECB_NO_PADDING`.
|
||||
|
||||
### Disabling `MBEDTLS_CIPHER_C`
|
||||
|
||||
It is possible to save code size by disabling MBEDTLS_CIPHER_C when all of the
|
||||
following conditions are met:
|
||||
- The application is not using the `mbedtls_cipher_` API.
|
||||
- In PSA, all unauthenticated (that is, non-AEAD) ciphers are either disabled or
|
||||
fully accelerated (that is, all compatible key types are accelerated too).
|
||||
- Either TLS is disabled, or `MBEDTLS_USE_PSA_CRYPTO` is enabled.
|
||||
- `MBEDTLS_NIST_KW` is disabled.
|
||||
- `MBEDTLS_CMAC_C` is disabled. (Note: support for CMAC in PSA can be provided by
|
||||
a driver.)
|
||||
|
||||
In such a build, everything will work as usual except for the following:
|
||||
- Encryption/decryption functions from the PKCS5 and PKCS12 module will not be
|
||||
available (only key derivation functions).
|
||||
- Parsing of PKCS5- or PKCS12-encrypted keys in PK parse will fail.
|
||||
|
||||
Note: AEAD ciphers (CCM, GCM, ChachaPoly) do not have a dependency on
|
||||
MBEDTLS_CIPHER_C even when using the built-in implementations.
|
||||
|
||||
If you also have some ciphers fully accelerated and the built-ins removed, see
|
||||
[Restrictions](#restrictions) for restrictions related to removing the built-ins.
|
||||
|
||||
More precisely you can:
|
||||
- enable desired PSA algorithm(s) and key type(s):
|
||||
- `PSA_WANT_ALG_[CCM|GCM]` with `PSA_WANT_KEY_TYPE_[AES|ARIA|CAMELLIA]`
|
||||
- `PSA_WANT_ALG_CHACHA20_POLY1305` with `PSA_WANT_KEY_TYPE_CHACHA20`;
|
||||
- enable `MBEDTLS_PSA_ACCEL_xxx` symbol(s) which correspond to the
|
||||
`PSA_WANT_xxx` of the previous step (both for algorithms and key types);
|
||||
- disable builtin support of `MBEDTLS_[CCM|GCM|CHACHAPOLY|POLY1305]_C`
|
||||
algorithms and key types `MBEDTLS_[AES|ARIA|CAMELLIA|CHACHA20]_C` for AEADs
|
||||
which are accelerated.
|
||||
|
||||
In a build in which all AEADs algorithms and related key types are accelerated
|
||||
all AEADs operations requested through the PSA Crypto API (including those in
|
||||
TLS and X.509) will be performed by the driver.
|
||||
Moreover if no unauthenticated cipher is required, it is also possible to
|
||||
disable all built-in block cipher's key types
|
||||
(i.e. `MBEDTLS_[AES|ARIA|CAMELLIA|CHACHA20]_C`) and `MBEDTLS_CIPHER_C`. This
|
||||
helps in further reducing code's footprint, but unfortunately it makes the
|
||||
following modules unavailable:
|
||||
- `MBEDTLS_PKCS[5|12]_C`
|
||||
- `MBEDTLS_CTR_DRBG_C`
|
||||
- `MBEDTLS_NIST_KW_C`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user