Define indirection macros MBEDTLS_CHECK_RETURN_xxx

Define macros MBEDTLS_CHECK_RETURN_CRITICAL, MBEDTLS_CHECK_RETURN_TYPICAL
and MBEDTLS_CHECK_RETURN_OPTIONAL so that we can indicate on a
function-by-function basis whether checking the function's return value is
almost always necessary (CRITICAL), typically necessary in portable
applications but unnecessary in some reasonable cases (TYPICAL), or
typically unnecessary (OPTIONAL).

Update the documentation of MBEDTLS_CHECK_RETURN accordingly. This is split
between the user documentation (Doxygen, in config.h) and the internal
documentation (non-Doxygen, in platform_util.h, of minor importance since
the macro isn't meant to be used directly).

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

include/mbedtls/config.h

@@ -3697,13 +3697,16 @@
 
 /** \def MBEDTLS_CHECK_RETURN
  *
- * This macro appearing at the beginning of the declaration of a function
- * indicates that its return value should be checked.
+ * This macro is used at the beginning of the declaration of a function
+ * to indicate that its return value should be checked. It should
+ * instruct the compiler to emit a warning or an error if the function
+ * is called without checking its return value.
  *
- * Default implementation resides in platform_util.h.
- * You can override default implementation by defining your own.
- * Custom implementation can be empty, which will disable checking
- * of functions' return values.
+ * There is a default implementation for popular compilers in platform_util.h.
+ * You can override the default implementation by defining your own here.
+ *
+ * If the implementation here is empty, this will effectively disable the
+ * checking of functions' return values.
  */
 //#define MBEDTLS_CHECK_RETURN
 

include/mbedtls/platform_util.h

@@ -132,14 +132,12 @@ MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
 #endif /* MBEDTLS_DEPRECATED_WARNING */
 #endif /* MBEDTLS_DEPRECATED_REMOVED */
 
-/** \def MBEDTLS_CHECK_RETURN
+/* Implementation of the check-return facility.
+ * See the user documentation in config.h.
  *
- * This macro appearing at the beginning of the declaration of a function
- * indicates that its return value should be checked.
- *
- * This should appear before most functions returning an error code
- * (as \c int in the \c mbedtls_xxx API or
- * as ::psa_status_t in the \c psa_xxx API).
+ * Do not use this macro directly to annotate function: instead,
+ * use one of MBEDTLS_CHECK_RETURN_CRITICAL or MBEDTLS_CHECK_RETURN_TYPICAL
+ * depending on how important it is to check the return value.
  */
 #if !defined(MBEDTLS_CHECK_RETURN)
 #if defined(__GNUC__)
@@ -152,6 +150,52 @@ MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
 #endif
 #endif
 
+/** Critical-failure function
+ *
+ * This macro appearing at the beginning of the declaration of a function
+ * indicates that its return value should be checked in all applications.
+ * Omitting the check is very likely to indicate a bug in the application
+ * and will result in a compile-time warning if #MBEDTLS_CHECK_RETURN
+ * is implemented for the compiler in use.
+ *
+ * \note  The use of this macro is a work in progress.
+ *        This macro may be added to more functions in the future.
+ *        Such an extension is not considered an API break, provided that
+ *        there are near-unavoidable circumstances under which the function
+ *        can fail. For example, signature/MAC/AEAD verification functions,
+ *        and functions that require a random generator, are considered
+ *        return-check-critical.
+ */
+#define MBEDTLS_CHECK_RETURN_CRITICAL MBEDTLS_CHECK_RETURN
+
+/** Ordinary-failure function
+ *
+ * This macro appearing at the beginning of the declaration of a function
+ * indicates that its return value should be generally be checked in portable
+ * applications. Omitting the check will result in a compile-time warning if
+ * #MBEDTLS_CHECK_RETURN is implemented for the compiler in use.
+ *
+ * \note  The use of this macro is a work in progress.
+ *        This macro will be added to more functions in the future.
+ *        Eventually this should appear before most functions returning
+ *        an error code (as \c int in the \c mbedtls_xxx API or
+ *        as ::psa_status_t in the \c psa_xxx API).
+ */
+#define MBEDTLS_CHECK_RETURN_TYPICAL MBEDTLS_CHECK_RETURN
+
+/** Benign-failure function
+ *
+ * This macro appearing at the beginning of the declaration of a function
+ * indicates that it is rarely useful to check its return value.
+ *
+ * This macro has an empty expansion. It exists for documentation purposes:
+ * a #MBEDTLS_CHECK_RETURN_OPTIONAL annotation indicates that the function
+ * has been analyzed for return-check usefuless, whereas the lack of
+ * an annotation indicates that the function has not been analyzed and its
+ * return-check usefulness is unknown.
+ */
+#define MBEDTLS_CHECK_RETURN_OPTIONAL
+
 /**
  * \brief       Securely zeroize a buffer
  *