File platform_util.h

Common and shared functions used by multiple modules in the Mbed TLS library.

Defines

MBEDTLS_CHECK_RETURN_CRITICAL

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.

MBEDTLS_CHECK_RETURN_TYPICAL

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 int in the mbedtls_xxx API or as psa_status_t in the psa_xxx API).

MBEDTLS_CHECK_RETURN_OPTIONAL

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.

Functions

void mbedtls_platform_zeroize(void *buf, size_t len)

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
Parameters:

  • buf – Buffer to be zeroized

  • len – Length of the buffer in bytes

struct tm *mbedtls_platform_gmtime_r(const mbedtls_time_t *tt, struct tm *tm_buf)

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.
Parameters:

  • tt – Pointer to an object containing time (in seconds) since the epoch to be converted

  • tm_buf – Pointer to an object where the results will be stored

Returns:

Pointer to an object of type struct tm on success, otherwise NULL