From 8c2830a06a70c62b4e0dd4a4a029390623ceef8f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 4 Aug 2022 23:37:51 +0200 Subject: [PATCH 1/3] Document what "TLS 1.3 depends on PSA" entails Explicitly document that when using TLS 1.3, you must initialize PSA crypto before starting a handshake. Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 13 ++++++++----- include/mbedtls/ssl.h | 5 +++++ 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 5aff9c5b60..2dd370601c 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1578,11 +1578,14 @@ * Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE * Requires: MBEDTLS_PSA_CRYPTO_C * - * Note: even though TLS 1.3 depends on PSA Crypto, and uses it unconditionally - * for most operations, if you want it to only use PSA for all crypto - * operations, you need to also enable MBEDTLS_USE_PSA_CRYPTO; otherwise X.509 - * operations, and functions that are common with TLS 1.2 (record protection, - * running handshake hash) will still use non-PSA crypto. + * \note TLS 1.3 uses PSA crypto for cryptographic operations that are + * directly performed by TLS 1.3 code. As a consequence, you must + * call psa_crypto_init() before the first TLS 1.3 handshake. + * + * \note Cryptographic operations performed indirectly via another module + * (X.509, PK) or by code shared with TLS 1.2 (record protection, + * running handshake hash) only use PSA crypto if + * #MBEDTLS_USE_PSA_CRYPTO is enabled. * * Uncomment this macro to enable the support for TLS 1.3. */ diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 4b954bb458..2594964e15 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -4684,6 +4684,11 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, * in which case the datagram of the underlying transport that is * currently being processed might or might not contain further * DTLS records. + * + * \note If the context is configured to allow TLS 1.3, or if + * #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. */ int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl); From a8d7e438e6b1cdc08160d312433e4d587ec5f375 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 4 Aug 2022 23:39:41 +0200 Subject: [PATCH 2/3] Move non-boolean config options to the proper section Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 78 ++++++++++++++++---------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 2dd370601c..677670a18b 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1654,45 +1654,6 @@ */ #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED -/** - * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE - * - * Maximum time difference in milliseconds tolerated between the age of a - * ticket from the server and client point of view. - * From the client point of view, the age of a ticket is the time difference - * between the time when the client proposes to the server to use the ticket - * (time of writing of the Pre-Shared Key Extension including the ticket) and - * the time the client received the ticket from the server. - * From the server point of view, the age of a ticket is the time difference - * between the time when the server receives a proposition from the client - * to use the ticket and the time when the ticket was created by the server. - * The server age is expected to be always greater than the client one and - * MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE defines the - * maximum difference tolerated for the server to accept the ticket. - * This is not used in TLS 1.2. - * - */ -#define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000 - -/** - * \def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH - * - * Size in bytes of a ticket nonce. This is not used in TLS 1.2. - * - * This must be less than 256. - */ -#define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32 - -/** - * \def MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS - * - * Default number of NewSessionTicket messages to be sent by a TLS 1.3 server - * after handshake completion. This is not used in TLS 1.2 and relevant only if - * the MBEDTLS_SSL_SESSION_TICKETS option is enabled. - * - */ -#define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1 - /** * \def MBEDTLS_SSL_EARLY_DATA * @@ -3809,6 +3770,45 @@ */ //#define MBEDTLS_SSL_CIPHERSUITES MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 +/** + * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE + * + * Maximum time difference in milliseconds tolerated between the age of a + * ticket from the server and client point of view. + * From the client point of view, the age of a ticket is the time difference + * between the time when the client proposes to the server to use the ticket + * (time of writing of the Pre-Shared Key Extension including the ticket) and + * the time the client received the ticket from the server. + * From the server point of view, the age of a ticket is the time difference + * between the time when the server receives a proposition from the client + * to use the ticket and the time when the ticket was created by the server. + * The server age is expected to be always greater than the client one and + * MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE defines the + * maximum difference tolerated for the server to accept the ticket. + * This is not used in TLS 1.2. + * + */ +#define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000 + +/** + * \def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH + * + * Size in bytes of a ticket nonce. This is not used in TLS 1.2. + * + * This must be less than 256. + */ +#define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32 + +/** + * \def MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS + * + * Default number of NewSessionTicket messages to be sent by a TLS 1.3 server + * after handshake completion. This is not used in TLS 1.2 and relevant only if + * the MBEDTLS_SSL_SESSION_TICKETS option is enabled. + * + */ +#define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1 + /* X509 options */ //#define MBEDTLS_X509_MAX_INTERMEDIATE_CA 8 /**< Maximum number of intermediate CAs in a verification chain. */ //#define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 /**< Maximum length of a path/filename string in bytes including the null terminator character ('\0'). */ From 5b7e1644a7100468b7313ff3054c8bed7980f861 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 4 Aug 2022 23:44:59 +0200 Subject: [PATCH 3/3] Document the need to call psa_crypto_init() with USE_PSA_CRYPTO When MBEDTLS_USE_PSA_CRYPTO is enabled, the application must call psa_crypto_init() before directly or indirectly calling cipher or PK code that will use PSA under the hood. Document this explicitly for some functions. To avoid clutter, this commit only documents the need to call psa_crypto_init() in common, non-obvious cases: parsing a public key directly or via X.509, or setting up an SSL context. Functions that are normally only called after such a function (for example, using an already constructed PK object), or where the need for PSA is obvious because they take a key ID as argument, do not need more explicit documentaion. Signed-off-by: Gilles Peskine --- include/mbedtls/pk.h | 12 ++++++++++++ include/mbedtls/ssl.h | 4 ++++ include/mbedtls/x509_crl.h | 12 ++++++++++++ include/mbedtls/x509_crt.h | 20 ++++++++++++++++++++ include/mbedtls/x509_csr.h | 8 ++++++++ 5 files changed, 56 insertions(+) diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 0e4ee38440..3de7a8fa04 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -796,6 +796,10 @@ static inline mbedtls_ecp_keypair *mbedtls_pk_ec(const mbedtls_pk_context pk) /** * \brief Parse a private key in PEM or DER format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param ctx The PK context to fill. It must have been initialized * but not set up. * \param key Input buffer to parse. @@ -832,6 +836,10 @@ int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, /** * \brief Parse a public key in PEM or DER format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param ctx The PK context to fill. It must have been initialized * but not set up. * \param key Input buffer to parse. @@ -861,6 +869,10 @@ int mbedtls_pk_parse_public_key(mbedtls_pk_context *ctx, /** * \brief Load and parse a private key * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param ctx The PK context to fill. It must have been initialized * but not set up. * \param path filename to read the private key from diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 2594964e15..29ba85a397 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1869,6 +1869,10 @@ void mbedtls_ssl_init(mbedtls_ssl_context *ssl); * Calling mbedtls_ssl_setup again is not supported, even * if no session is active. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param ssl SSL context * \param conf SSL configuration to use * diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h index 49bbf61647..62694ae7fb 100644 --- a/include/mbedtls/x509_crl.h +++ b/include/mbedtls/x509_crl.h @@ -107,6 +107,10 @@ mbedtls_x509_crl; /** * \brief Parse a DER-encoded CRL and append it to the chained list * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param buf buffer holding the CRL data in DER format * \param buflen size of the buffer @@ -121,6 +125,10 @@ int mbedtls_x509_crl_parse_der(mbedtls_x509_crl *chain, * * \note Multiple CRLs are accepted only if using PEM format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param buf buffer holding the CRL data in PEM or DER format * \param buflen size of the buffer @@ -136,6 +144,10 @@ int mbedtls_x509_crl_parse(mbedtls_x509_crl *chain, const unsigned char *buf, si * * \note Multiple CRLs are accepted only if using PEM format * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param path filename to read the CRLs from (in PEM or DER encoding) * diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 036282f7c9..11e5951f60 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -341,6 +341,10 @@ extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_none; * \brief Parse a single DER formatted certificate and add it * to the end of the provided chained list. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -402,6 +406,10 @@ typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx, * \brief Parse a single DER formatted certificate and add it * to the end of the provided chained list. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -452,6 +460,10 @@ int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain, * temporary ownership of the CRT buffer until the CRT * is destroyed. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The pointer to the start of the CRT chain to attach to. * When parsing the first CRT in a chain, this should point * to an instance of ::mbedtls_x509_crt initialized through @@ -492,6 +504,10 @@ int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain, * long as the certificates are enclosed in the PEM specific * '-----{BEGIN/END} CERTIFICATE-----' delimiters. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain The chain to which to add the parsed certificates. * \param buf The buffer holding the certificate data in PEM or DER format. * For certificates in PEM encoding, this may be a concatenation @@ -516,6 +532,10 @@ int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, si * of failed certificates it encountered. If none complete * correctly, the first error is returned. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param chain points to the start of the chain * \param path filename to read the certificates from * diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h index 0c204be067..e376000a40 100644 --- a/include/mbedtls/x509_csr.h +++ b/include/mbedtls/x509_csr.h @@ -89,6 +89,10 @@ mbedtls_x509write_csr; * * \note CSR attributes (if any) are currently silently ignored. * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param csr CSR context to fill * \param buf buffer holding the CRL data * \param buflen size of the buffer @@ -103,6 +107,10 @@ int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr, * * \note See notes for \c mbedtls_x509_csr_parse_der() * + * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto + * subsystem must have been initialized by calling + * psa_crypto_init() before calling this function. + * * \param csr CSR context to fill * \param buf buffer holding the CRL data * \param buflen size of the buffer