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.

Typedefs

typedef int mbedtls_f_rng_t(void *p_rng, unsigned char *output, size_t output_size)

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:

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 p_rng argument that was passed along f_rng. The library always passes p_rng unchanged. This is typically a pointer to the random generator state, or NULL if the custom random generator doesn’t need a context-specific state.

Param output:

[out] On success, this must be filled with output_size bytes of cryptographic-quality random data.

Param output_size:

The number of bytes to output.

Return:

0 on success, or a negative error code on failure. Library functions will generally propagate this error code, so MBEDTLS_ERR_xxx values are recommended. MBEDTLS_ERR_ENTROPY_SOURCE_FAILED is typically sensible for RNG failures.

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