From 31c3b14e371ed24988f0125bc473c2d9fe59f3a5 Mon Sep 17 00:00:00 2001 From: Jarno Lamsa Date: Wed, 14 Aug 2019 10:39:32 +0300 Subject: [PATCH] Documentation fixes according to review Improve grammar and replace the word 'fresh' with an explanation what is going to be verified. --- include/mbedtls/config.h | 7 ++++--- include/mbedtls/ssl.h | 18 ++++++++++-------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 6e841c7e6..87d0c6e98 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -1353,9 +1353,10 @@ /** * \def MBEDTLS_SSL_RECORD_CHECKING * - * Enable the API mbedtls_ssl_check_record() which allows to check the - * validity, freshness and authenticity of an incoming record without - * modifying the externally visible state of the SSL context. + * Enable the function mbedtls_ssl_check_record() which can be used to check + * the validity and authenticity of an incoming record, to verify that it has + * not been seen before. These checks are performed without modifying the + * externally visible state of the SSL context. * * See mbedtls_ssl_check_record() for more information. * diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 955104af1..2c7f050b5 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1758,8 +1758,8 @@ void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout ) #if defined(MBEDTLS_SSL_RECORD_CHECKING) /** - * \brief Check whether a buffer contains a valid, fresh - * and authentic record (DTLS only). + * \brief Check whether a buffer contains a valid and authentic record + * that has not been seen before. (DTLS only). * * This function does not change the user-visible state * of the SSL context. Its sole purpose is to provide @@ -1774,19 +1774,21 @@ void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout ) * * \param ssl The SSL context to use. * \param buf The address of the buffer holding the record to be checked. - * This must be an R/W buffer of length \p buflen Bytes. + * This must be a read/write buffer of length \p buflen Bytes. * \param buflen The length of \p buf in Bytes. * * \note This routine only checks whether the provided buffer begins - * with a valid, fresh and authentic record, but does not check - * potential data following the initial record. In particular, - * it is possible to pass DTLS datagrams containing multiple - * records, in which case only the first record is checked. + * with a valid and authentic record that has not been seen + * before, but does not check potential data following the + * initial record. In particular, it is possible to pass DTLS + * datagrams containing multiple records, in which case only + * the first record is checked. * * \note This function modifies the input buffer \p buf. If you need * to preserve the original record, you have to maintain a copy. * - * \return \c 0 if the record is valid, fresh and authentic. + * \return \c 0 if the record is valid and authentic and has not been + * seen before. * \return MBEDTLS_ERR_SSL_INVALID_MAC if the check completed * successfully but the record was found to be not authentic. * \return MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed