include/mbedtls/platform_util.h - mirror/mbed-tls.git - TrustedFirmware Git Browser

 /**
  * \file platform_util.h
  *
  * \brief Common and shared functions used by multiple modules in the Mbed TLS
  *        library.
  */
 /*
  *  Copyright The Mbed TLS Contributors
  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
  */
 #ifndef MBEDTLS_PLATFORM_UTIL_H
 #define MBEDTLS_PLATFORM_UTIL_H

 #include "mbedtls/build_info.h"

 #include <stddef.h>
 #if defined(MBEDTLS_HAVE_TIME_DATE)
 #include "mbedtls/platform_time.h"
 #include <time.h>
 #endif /* MBEDTLS_HAVE_TIME_DATE */

 #ifdef __cplusplus
 extern "C" {
 #endif

 /* Internal helper macros for deprecating API constants. */
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 #if defined(MBEDTLS_DEPRECATED_WARNING)
 #define MBEDTLS_DEPRECATED __attribute__((deprecated))
 MBEDTLS_DEPRECATED typedef char const *mbedtls_deprecated_string_constant_t;
 #define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)       \
     ((mbedtls_deprecated_string_constant_t) (VAL))
 MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
 #define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL)       \
     ((mbedtls_deprecated_numeric_constant_t) (VAL))
 #else /* MBEDTLS_DEPRECATED_WARNING */
 #define MBEDTLS_DEPRECATED
 #define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) VAL
 #define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL) VAL
 #endif /* MBEDTLS_DEPRECATED_WARNING */
 #endif /* MBEDTLS_DEPRECATED_REMOVED */

 /* Implementation of the check-return facility.
  * See the user documentation in mbedtls_config.h.
  *
  * 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__)
 #define MBEDTLS_CHECK_RETURN __attribute__((__warn_unused_result__))
 #elif defined(_MSC_VER) && _MSC_VER >= 1700
 #include <sal.h>
 #define MBEDTLS_CHECK_RETURN _Check_return_
 #else
 #define MBEDTLS_CHECK_RETURN
 #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 and
  * #MBEDTLS_CHECK_RETURN_WARNING is enabled in the compile-time configuration.
  *
  * You can use #MBEDTLS_IGNORE_RETURN to explicitly ignore the return value
  * of a function that is annotated with #MBEDTLS_CHECK_RETURN.
  *
  * \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).
  */
 #if defined(MBEDTLS_CHECK_RETURN_WARNING)
 #define MBEDTLS_CHECK_RETURN_TYPICAL MBEDTLS_CHECK_RETURN
 #else
 #define MBEDTLS_CHECK_RETURN_TYPICAL
 #endif

 /** 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 usefulness, 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

 /** \def MBEDTLS_IGNORE_RETURN
  *
  * Call this macro with one argument, a function call, to suppress a warning
  * from #MBEDTLS_CHECK_RETURN due to that function call.
  */
 #if !defined(MBEDTLS_IGNORE_RETURN)
 /* GCC doesn't silence the warning with just (void)(result).
  * (void)!(result) is known to work up at least up to GCC 10, as well
  * as with Clang and MSVC.
  *
  * https://gcc.gnu.org/onlinedocs/gcc-3.4.6/gcc/Non_002dbugs.html
  * https://stackoverflow.com/questions/40576003/ignoring-warning-wunused-result
  * https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425#c34
  */
 #define MBEDTLS_IGNORE_RETURN(result) ((void) !(result))
 #endif

 /* If the following macro is defined, the library is being built by the test
  * framework, and the framework is going to provide a replacement
  * mbedtls_platform_zeroize() using a preprocessor macro, so the function
  * declaration should be omitted.  */
 #if !defined(MBEDTLS_TEST_DEFINES_ZEROIZE) //no-check-names
 /**
  * \brief       Securely zeroize a buffer
  *
  *              The function is meant to wipe the data contained in a buffer so
  *              that it can no longer be recovered even if the program memory
  *              is later compromised. Call this function on sensitive data
  *              stored on the stack before returning from a function, and on
  *              sensitive data stored on the heap before freeing the heap
  *              object.
  *
  *              It is extremely difficult to guarantee that calls to
  *              mbedtls_platform_zeroize() are not removed by aggressive
  *              compiler optimizations in a portable way. For this reason, Mbed
  *              TLS provides the configuration option
  *              MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
  *              mbedtls_platform_zeroize() to use a suitable implementation for
  *              their platform and needs
  *
  * \param buf   Buffer to be zeroized
  * \param len   Length of the buffer in bytes
  *
  */
 void mbedtls_platform_zeroize(void *buf, size_t len);
 #endif

 /** \brief              The type of custom random generator (RNG) callbacks.
  *
  *                      Many Mbed TLS functions take two parameters
  *                      `mbedtls_f_rng_t *f_rng, void *p_rng`. The
  *                      library will call \c f_rng to generate
  *                      random values.
  *
  * \note                This is typically one of the following:
  *                      - mbedtls_ctr_drbg_random() with \c p_rng
  *                        pointing to a #mbedtls_ctr_drbg_context;
  *                      - mbedtls_hmac_drbg_random() with \c p_rng
  *                        pointing to a #mbedtls_hmac_drbg_context;
  *                      - mbedtls_psa_get_random() with
  *                        `prng = MBEDTLS_PSA_RANDOM_STATE`.
  *
  * \note                Generally, given a call
  *                      `mbedtls_foo(f_rng, p_rng, ....)`, the RNG callback
  *                      and the context only need to remain valid until
  *                      the call to `mbedtls_foo` returns. However, there
  *                      are a few exceptions where the callback is stored
  *                      in for future use. Check the documentation of
  *                      the calling function.
  *
  * \warning             In a multithreaded environment, calling the
  *                      function should be thread-safe. The standard
  *                      functions provided by the library are thread-safe
  *                      when #MBEDTLS_THREADING_C is enabled.
  *
  * \warning             This function must either provide as many
  *                      bytes as requested of **cryptographic quality**
  *                      random data, or return a negative error code.
  *
  * \param p_rng         The \c p_rng argument that was passed along \c f_rng.
  *                      The library always passes \c p_rng unchanged.
  *                      This is typically a pointer to the random generator
  *                      state, or \c NULL if the custom random generator
  *                      doesn't need a context-specific state.
  * \param[out] output   On success, this must be filled with \p output_size
  *                      bytes of cryptographic-quality random data.
  * \param output_size   The number of bytes to output.
  *
  * \return              \c 0 on success, or a negative error code on failure.
  *                      Library functions will generally propagate this
  *                      error code, so \c MBEDTLS_ERR_xxx values are
  *                      recommended. #MBEDTLS_ERR_ENTROPY_SOURCE_FAILED is
  *                      typically sensible for RNG failures.
  */
 typedef int mbedtls_f_rng_t(void *p_rng,
                             unsigned char *output, size_t output_size);

 #if defined(MBEDTLS_HAVE_TIME_DATE)
 /**
  * \brief      Platform-specific implementation of gmtime_r()
  *
  *             The function is a thread-safe abstraction that behaves
  *             similarly to the gmtime_r() function from Unix/POSIX.
  *
  *             Mbed TLS will try to identify the underlying platform and
  *             make use of an appropriate underlying implementation (e.g.
  *             gmtime_r() for POSIX and gmtime_s() for Windows). If this is
  *             not possible, then gmtime() will be used. In this case, calls
  *             from the library to gmtime() will be guarded by the mutex
  *             mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is
  *             enabled. It is recommended that calls from outside the library
  *             are also guarded by this mutex.
  *
  *             If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will
  *             unconditionally use the alternative implementation for
  *             mbedtls_platform_gmtime_r() supplied by the user at compile time.
  *
  * \param tt     Pointer to an object containing time (in seconds) since the
  *               epoch to be converted
  * \param tm_buf Pointer to an object where the results will be stored
  *
  * \return      Pointer to an object of type struct tm on success, otherwise
  *              NULL
  */
 struct tm *mbedtls_platform_gmtime_r(const mbedtls_time_t *tt,
                                      struct tm *tm_buf);
 #endif /* MBEDTLS_HAVE_TIME_DATE */

 #ifdef __cplusplus
 }
 #endif

 #endif /* MBEDTLS_PLATFORM_UTIL_H */
	/**
	* \file platform_util.h
	*
	* \brief Common and shared functions used by multiple modules in the Mbed TLS
	* library.
	*/
	/*
	* Copyright The Mbed TLS Contributors
	* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
	*/
	#ifndef MBEDTLS_PLATFORM_UTIL_H
	#define MBEDTLS_PLATFORM_UTIL_H

	#include "mbedtls/build_info.h"

	#include <stddef.h>
	#if defined(MBEDTLS_HAVE_TIME_DATE)
	#include "mbedtls/platform_time.h"
	#include <time.h>
	#endif /* MBEDTLS_HAVE_TIME_DATE */

	#ifdef __cplusplus
	extern "C" {
	#endif

	/* Internal helper macros for deprecating API constants. */
	#if !defined(MBEDTLS_DEPRECATED_REMOVED)
	#if defined(MBEDTLS_DEPRECATED_WARNING)
	#define MBEDTLS_DEPRECATED __attribute__((deprecated))
	MBEDTLS_DEPRECATED typedef char const *mbedtls_deprecated_string_constant_t;
	#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) \
	((mbedtls_deprecated_string_constant_t) (VAL))
	MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
	#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL) \
	((mbedtls_deprecated_numeric_constant_t) (VAL))
	#else /* MBEDTLS_DEPRECATED_WARNING */
	#define MBEDTLS_DEPRECATED
	#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) VAL
	#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL) VAL
	#endif /* MBEDTLS_DEPRECATED_WARNING */
	#endif /* MBEDTLS_DEPRECATED_REMOVED */

	/* Implementation of the check-return facility.
	* See the user documentation in mbedtls_config.h.
	*
	* 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__)
	#define MBEDTLS_CHECK_RETURN __attribute__((__warn_unused_result__))
	#elif defined(_MSC_VER) && _MSC_VER >= 1700
	#include <sal.h>
	#define MBEDTLS_CHECK_RETURN _Check_return_
	#else
	#define MBEDTLS_CHECK_RETURN
	#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 and
	* #MBEDTLS_CHECK_RETURN_WARNING is enabled in the compile-time configuration.
	*
	* You can use #MBEDTLS_IGNORE_RETURN to explicitly ignore the return value
	* of a function that is annotated with #MBEDTLS_CHECK_RETURN.
	*
	* \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).
	*/
	#if defined(MBEDTLS_CHECK_RETURN_WARNING)
	#define MBEDTLS_CHECK_RETURN_TYPICAL MBEDTLS_CHECK_RETURN
	#else
	#define MBEDTLS_CHECK_RETURN_TYPICAL
	#endif

	/** 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 usefulness, 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

	/** \def MBEDTLS_IGNORE_RETURN
	*
	* Call this macro with one argument, a function call, to suppress a warning
	* from #MBEDTLS_CHECK_RETURN due to that function call.
	*/
	#if !defined(MBEDTLS_IGNORE_RETURN)
	/* GCC doesn't silence the warning with just (void)(result).
	* (void)!(result) is known to work up at least up to GCC 10, as well
	* as with Clang and MSVC.
	*
	* https://gcc.gnu.org/onlinedocs/gcc-3.4.6/gcc/Non_002dbugs.html
	* https://stackoverflow.com/questions/40576003/ignoring-warning-wunused-result
	* https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425#c34
	*/
	#define MBEDTLS_IGNORE_RETURN(result) ((void) !(result))
	#endif

	/* If the following macro is defined, the library is being built by the test
	* framework, and the framework is going to provide a replacement
	* mbedtls_platform_zeroize() using a preprocessor macro, so the function
	* declaration should be omitted. */
	#if !defined(MBEDTLS_TEST_DEFINES_ZEROIZE) //no-check-names
	/**
	* \brief Securely zeroize a buffer
	*
	* The function is meant to wipe the data contained in a buffer so
	* that it can no longer be recovered even if the program memory
	* is later compromised. Call this function on sensitive data
	* stored on the stack before returning from a function, and on
	* sensitive data stored on the heap before freeing the heap
	* object.
	*
	* It is extremely difficult to guarantee that calls to
	* mbedtls_platform_zeroize() are not removed by aggressive
	* compiler optimizations in a portable way. For this reason, Mbed
	* TLS provides the configuration option
	* MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
	* mbedtls_platform_zeroize() to use a suitable implementation for
	* their platform and needs
	*
	* \param buf Buffer to be zeroized
	* \param len Length of the buffer in bytes
	*
	*/
	void mbedtls_platform_zeroize(void *buf, size_t len);
	#endif

	/** \brief The type of custom random generator (RNG) callbacks.
	*
	* Many Mbed TLS functions take two parameters
	* `mbedtls_f_rng_t f_rng, void p_rng`. The
	* library will call \c f_rng to generate
	* random values.
	*
	* \note This is typically one of the following:
	* - mbedtls_ctr_drbg_random() with \c p_rng
	* pointing to a #mbedtls_ctr_drbg_context;
	* - mbedtls_hmac_drbg_random() with \c p_rng
	* pointing to a #mbedtls_hmac_drbg_context;
	* - mbedtls_psa_get_random() with
	* `prng = MBEDTLS_PSA_RANDOM_STATE`.
	*
	* \note Generally, given a call
	* `mbedtls_foo(f_rng, p_rng, ....)`, the RNG callback
	* and the context only need to remain valid until
	* the call to `mbedtls_foo` returns. However, there
	* are a few exceptions where the callback is stored
	* in for future use. Check the documentation of
	* the calling function.
	*
	* \warning In a multithreaded environment, calling the
	* function should be thread-safe. The standard
	* functions provided by the library are thread-safe
	* when #MBEDTLS_THREADING_C is enabled.
	*
	* \warning This function must either provide as many
	* bytes as requested of cryptographic quality
	* random data, or return a negative error code.
	*
	* \param p_rng The \c p_rng argument that was passed along \c f_rng.
	* The library always passes \c p_rng unchanged.
	* This is typically a pointer to the random generator
	* state, or \c NULL if the custom random generator
	* doesn't need a context-specific state.
	* \param[out] output On success, this must be filled with \p output_size
	* bytes of cryptographic-quality random data.
	* \param output_size The number of bytes to output.
	*
	* \return \c 0 on success, or a negative error code on failure.
	* Library functions will generally propagate this
	* error code, so \c MBEDTLS_ERR_xxx values are
	* recommended. #MBEDTLS_ERR_ENTROPY_SOURCE_FAILED is
	* typically sensible for RNG failures.
	*/
	typedef int mbedtls_f_rng_t(void *p_rng,
	unsigned char *output, size_t output_size);

	#if defined(MBEDTLS_HAVE_TIME_DATE)
	/**
	* \brief Platform-specific implementation of gmtime_r()
	*
	* The function is a thread-safe abstraction that behaves
	* similarly to the gmtime_r() function from Unix/POSIX.
	*
	* Mbed TLS will try to identify the underlying platform and
	* make use of an appropriate underlying implementation (e.g.
	* gmtime_r() for POSIX and gmtime_s() for Windows). If this is
	* not possible, then gmtime() will be used. In this case, calls
	* from the library to gmtime() will be guarded by the mutex
	* mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is
	* enabled. It is recommended that calls from outside the library
	* are also guarded by this mutex.
	*
	* If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will
	* unconditionally use the alternative implementation for
	* mbedtls_platform_gmtime_r() supplied by the user at compile time.
	*
	* \param tt Pointer to an object containing time (in seconds) since the
	* epoch to be converted
	* \param tm_buf Pointer to an object where the results will be stored
	*
	* \return Pointer to an object of type struct tm on success, otherwise
	* NULL
	*/
	struct tm mbedtls_platform_gmtime_r(const mbedtls_time_t tt,
	struct tm *tm_buf);
	#endif /* MBEDTLS_HAVE_TIME_DATE */

	#ifdef __cplusplus
	}
	#endif

	#endif /* MBEDTLS_PLATFORM_UTIL_H */