diff --git a/ChangeLog b/ChangeLog index cfcc4f19a..35c823633 100644 --- a/ChangeLog +++ b/ChangeLog @@ -35,6 +35,9 @@ Bugfix * 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 905ebedd9..c6e453274 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -2370,7 +2370,6 @@ const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ss * \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 @@ const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ss * \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 @@ void mbedtls_ssl_session_init( mbedtls_ssl_session *session ); * \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 );