diff --git a/ChangeLog b/ChangeLog index 5545e5d132..54e1363c04 100644 --- a/ChangeLog +++ b/ChangeLog @@ -51,6 +51,9 @@ Bugfix * 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 38585591d6..2d511a8ea1 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -2746,7 +2746,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 @@ -2754,7 +2753,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() */ @@ -3032,6 +3042,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 );