Merge remote-tracking branch 'public/pr/1805' into mbedtls-2.7
diff --git a/ChangeLog b/ChangeLog
index cfcc4f1..35c8236 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -35,6 +35,9 @@
* Fix ssl_client2 example to send application data with 0-length content
when the request_size argument is set to 0 as stated in the documentation.
Fixes #1833.
+ * Correct the documentation for `mbedtls_ssl_get_session()`.
+ This API has deep copy of the session, and the peer
+ certificate is not lost. Fixes #926.
Changes
* Change the shebang line in Perl scripts to look up perl in the PATH.
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 905ebed..c6e4532 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2370,7 +2370,6 @@
* \brief Save session in order to resume it later (client-side only)
* Session data is copied to presented session structure.
*
- * \warning Currently, peer certificate is lost in the operation.
*
* \param ssl SSL context
* \param session session context
@@ -2378,7 +2377,18 @@
* \return 0 if successful,
* MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
* MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
- * arguments are otherwise invalid
+ * arguments are otherwise invalid.
+ *
+ * \note Only the server certificate is copied, and not the full chain,
+ * so you should not attempt to validate the certificate again
+ * by calling \c mbedtls_x509_crt_verify() on it.
+ * Instead, you should use the results from the verification
+ * in the original handshake by calling \c mbedtls_ssl_get_verify_result()
+ * after loading the session again into a new SSL context
+ * using \c mbedtls_ssl_set_session().
+ *
+ * \note Once the session object is not needed anymore, you should
+ * free it by calling \c mbedtls_ssl_session_free().
*
* \sa mbedtls_ssl_set_session()
*/
@@ -2620,6 +2630,9 @@
* \brief Free referenced items in an SSL session including the
* peer certificate and clear memory
*
+ * \note A session object can be freed even if the SSL context
+ * that was used to retrieve the session is still in use.
+ *
* \param session SSL session
*/
void mbedtls_ssl_session_free( mbedtls_ssl_session *session );