diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 4814d50f89..05f9d9de42 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. */ @@ -1651,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 * @@ -3843,6 +3807,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'). */ 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 4b954bb458..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 * @@ -4684,6 +4688,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); 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