Merge pull request #7354 from mpg/ecc-doc-update

Ecc doc update
This commit is contained in:
Manuel Pégourié-Gonnard 2023-03-30 15:38:47 +02:00 committed by GitHub
commit 0ab380a8ae
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 37 additions and 16 deletions

View file

@ -15,7 +15,7 @@ Restartable (aka interruptible) ECC operations
----------------------------------------------
Support for interruptible ECDSA sign/verify was added to PSA in Mbed TLS 3.4.
However support for interruptible ECDH is not present yet. Also, PK, X.509 and
However, support for interruptible ECDH is not present yet. Also, PK, X.509 and
TLS have not yet been adapted to take advantage of the new PSA APIs. See:
- <https://github.com/Mbed-TLS/mbedtls/issues/7292>;
- <https://github.com/Mbed-TLS/mbedtls/issues/7293>;

View file

@ -15,6 +15,13 @@ General considerations
`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
module.
**Why enable this option:** to fully take advantage of PSA drivers in PK,
X.509 and TLS. For example, enabling this option is what allows use of drivers
for ECDSA, ECDH and EC J-PAKE in those modules. However, note that even with
this option disabled, some code in PK, X.509, TLS or the crypto library might
still use PSA drivers, if it can determine it's safe to do so; currently
that's the case for hashes.
**Relationship with other options:** This option depends on
`MBEDTLS_PSA_CRYPTO_C`. These two options differ in the following way:
- `MBEDTLS_PSA_CRYPTO_C` enables the implementation of the PSA Crypto API.
@ -22,7 +29,7 @@ module.
`psa_crypto_init()` before you call any other `psa_xxx()` function. Other
modules in the library (non-PSA crypto APIs, X.509, TLS) may or may not use
PSA Crypto but you're not required to call `psa_crypto_init()` before calling
non-PSA functions, unless when explicitly documented (TLS 1.3).
non-PSA functions, unless explicitly documented (TLS 1.3).
- `MBEDTLS_USE_PSA_CRYPTO` means that X.509 and TLS will use PSA Crypto as
much as possible (that is, everywhere except for features that are not
supported by PSA Crypto, see "Internal Changes" below for a complete list of

View file

@ -798,14 +798,14 @@
#endif
#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
#if !( defined(MBEDTLS_PK_HAVE_ECDH) && defined(MBEDTLS_X509_CRT_PARSE_C) && \
#if !( defined(PSA_WANT_ALG_ECDH) && defined(MBEDTLS_X509_CRT_PARSE_C) && \
( defined(MBEDTLS_PK_HAVE_ECDSA) || defined(MBEDTLS_PKCS1_V21) ) )
#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED defined, but not all prerequisites"
#endif
#endif
#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
#if !( defined(MBEDTLS_PK_HAVE_ECDH) )
#if !( defined(PSA_WANT_ALG_ECDH) )
#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED defined, but not all prerequisites"
#endif
#endif

View file

@ -801,7 +801,7 @@
*
* Enable the ECDHE-PSK based ciphersuite modes in SSL / TLS.
*
* Requires: MBEDTLS_ECDH_C
* Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
*
* This enables the following ciphersuites (if other requisites are
* enabled as well):
@ -899,7 +899,9 @@
*
* Enable the ECDHE-RSA based ciphersuite modes in SSL / TLS.
*
* Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15,
* Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
* MBEDTLS_RSA_C
* MBEDTLS_PKCS1_V15
* MBEDTLS_X509_CRT_PARSE_C
*
* This enables the following ciphersuites (if other requisites are
@ -922,7 +924,9 @@
*
* Enable the ECDHE-ECDSA based ciphersuite modes in SSL / TLS.
*
* Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C,
* Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
* MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA)
* MBEDTLS_X509_CRT_PARSE_C
*
* This enables the following ciphersuites (if other requisites are
* enabled as well):
@ -944,7 +948,9 @@
*
* Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS.
*
* Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C
* Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
* MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA)
* MBEDTLS_X509_CRT_PARSE_C
*
* This enables the following ciphersuites (if other requisites are
* enabled as well):
@ -966,7 +972,9 @@
*
* Enable the ECDH-RSA based ciphersuite modes in SSL / TLS.
*
* Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_X509_CRT_PARSE_C
* Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
* MBEDTLS_RSA_C
* MBEDTLS_X509_CRT_PARSE_C
*
* This enables the following ciphersuites (if other requisites are
* enabled as well):
@ -992,7 +1000,7 @@
* Thread v1.0.0 specification; incompatible changes to the specification
* might still happen. For this reason, this is disabled by default.
*
* Requires: MBEDTLS_ECJPAKE_C
* Requires: MBEDTLS_ECJPAKE_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_JPAKE)
* SHA-256 (via MBEDTLS_SHA256_C or a PSA driver)
* MBEDTLS_ECP_DP_SECP256R1_ENABLED
*
@ -1645,8 +1653,11 @@
*
* Enable TLS 1.3 ephemeral key exchange mode.
*
* Requires: MBEDTLS_ECDH_C, MBEDTLS_X509_CRT_PARSE_C, MBEDTLS_ECDSA_C or
* MBEDTLS_PKCS1_V21
* Requires: PSA_WANT_ALG_ECDH
* MBEDTLS_X509_CRT_PARSE_C
* and at least one of:
* MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA)
* MBEDTLS_PKCS1_V21
*
* Comment to disable support for the ephemeral key exchange mode in TLS 1.3.
* If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any
@ -1660,7 +1671,7 @@
*
* Enable TLS 1.3 PSK ephemeral key exchange mode.
*
* Requires: MBEDTLS_ECDH_C
* Requires: PSA_WANT_ALG_ECDH
*
* Comment to disable support for the PSK ephemeral key exchange mode in
* TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not
@ -1933,9 +1944,12 @@
* \warning If you enable this option, you need to call `psa_crypto_init()`
* before calling any function from the SSL/TLS, X.509 or PK modules.
*
* \note Even with this option disabled, some code in PK, X.509, TLS or the
* crypto library might still use PSA drivers, if it can determine it's safe
* to do so.
* \note An important and desirable effect of this option is that it allows
* PK, X.509 and TLS to take advantage of PSA drivers. For example, enabling
* this option is what allows use of drivers for ECDSA, ECDH and EC J-PAKE in
* those modules. However, note that even with this option disabled, some code
* in PK, X.509, TLS or the crypto library might still use PSA drivers, if it
* can determine it's safe to do so; currently that's the case for hashes.
*
* \note See docs/use-psa-crypto.md for a complete description this option.
*