Mbed TLS v3.6.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
platform_util.h File Reference

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

#include "mbedtls/build_info.h"
#include <stddef.h>
#include "mbedtls/platform_time.h"
#include <time.h>
Include dependency graph for platform_util.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define MBEDTLS_CHECK_RETURN_CRITICAL   MBEDTLS_CHECK_RETURN
 
#define MBEDTLS_CHECK_RETURN_TYPICAL   MBEDTLS_CHECK_RETURN
 
#define MBEDTLS_CHECK_RETURN_OPTIONAL
 

Functions

void mbedtls_platform_zeroize (void *buf, size_t len)
 Securely zeroize a buffer. More...
 
struct tm * mbedtls_platform_gmtime_r (const mbedtls_time_t *tt, struct tm *tm_buf)
 Platform-specific implementation of gmtime_r() More...
 

Detailed Description

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

Definition in file platform_util.h.

Macro Definition Documentation

#define MBEDTLS_CHECK_RETURN_CRITICAL   MBEDTLS_CHECK_RETURN

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.

Definition at line 77 of file platform_util.h.

#define 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.

Definition at line 113 of file platform_util.h.

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

Definition at line 97 of file platform_util.h.

Function Documentation

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
ttPointer to an object containing time (in seconds) since the epoch to be converted
tm_bufPointer to an object where the results will be stored
Returns
Pointer to an object of type struct tm on success, otherwise NULL
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
bufBuffer to be zeroized
lenLength of the buffer in bytes