Merge remote-tracking branch 'public/pr/927' into development
diff --git a/ChangeLog b/ChangeLog
index 5545e5d..54e1363 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -51,6 +51,9 @@
* Change the default behaviour of mbedtls_hkdf_extract() to return an error
when calling with a NULL salt and non-zero salt_len. Contributed by
Brian J Murray
+ * 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 3858559..2d511a8 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2746,7 +2746,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
@@ -2754,7 +2753,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()
*/
@@ -3032,6 +3042,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 );