Improve documentation of mbedtls_ssl_get_peer_cert()
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 6e1bb3a..5915eae 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -3230,18 +3230,34 @@
#if defined(MBEDTLS_X509_CRT_PARSE_C)
/**
- * \brief Return the peer certificate from the current connection
+ * \brief Return the peer certificate from the current connection.
*
- * Note: Can be NULL in case no certificate was sent during
- * the handshake. Different calls for the same connection can
- * return the same or different pointers for the same
- * certificate and even a different certificate altogether.
- * The peer cert CAN change in a single connection if
- * renegotiation is performed.
+ * For ciphersuites not using certificate-based peer
+ * authentication (such as PSK-based ciphersuites), no
+ * peer certificate is available, and this function returns
+ * \c NULL.
*
- * \param ssl SSL context
+ * \param ssl The SSL context to use. This must be initialized and setup.
*
- * \return the current peer certificate
+ * \return The current peer certificate, or \c NULL if
+ * none is available. It is owned by the SSL context
+ * and valid only until the next call to the SSL API.
+ *
+ * \note For one-time inspection of the peer's certificate during
+ * the handshake, consider registering an X.509 CRT verification
+ * callback through mbedtls_ssl_conf_verify() instead of calling
+ * this function. Using mbedtls_ssl_conf_verify() also comes at
+ * the benefit of allowing you to influence the verification
+ * process, for example by masking expected and tolerated
+ * verification failures.
+ *
+ * \warning You must not use the pointer returned by this function
+ * after any further call to the SSL API, including
+ * mbedtls_ssl_read() and mbedtls_ssl_write(); this is
+ * because the pointer might change during renegotiation,
+ * which happens transparently to the user.
+ * If you want to use the certificate across API calls,
+ * you must make a copy.
*/
const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
#endif /* MBEDTLS_X509_CRT_PARSE_C */