From 4a82c1ccb416288579b32269ed60c13e53ba94dc Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 5 Feb 2019 11:33:12 +0000 Subject: [PATCH] Improve documentation of mbedtls_ssl_get_peer_cert() --- include/mbedtls/ssl.h | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 46007a72b..c4d6605b5 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -2972,18 +2972,34 @@ int mbedtls_ssl_get_max_out_record_payload( const mbedtls_ssl_context *ssl ); #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 */