Merge pull request #6172 from gilles-peskine-arm/doc-tls13-psa_crypto_init
Document the need to call psa_crypto_init for TLS 1.3
diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h
index 4814d50..05f9d9d 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.
*/
@@ -1652,45 +1655,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
*
* Enable support for RFC 8446 TLS 1.3 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 0e4ee38..3de7a8f 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -796,6 +796,10 @@
/**
* \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 @@
/**
* \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 @@
/**
* \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 4b954bb..29ba85a 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1869,6 +1869,10 @@
* 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 @@
* 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 49bbf61..62694ae 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -107,6 +107,10 @@
/**
* \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 @@
*
* \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 @@
*
* \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 036282f..11e5951 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -341,6 +341,10 @@
* \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 @@
* \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 @@
* 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 @@
* 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 @@
* 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 0c204be..e376000 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -89,6 +89,10 @@
*
* \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 @@
*
* \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