platform_util.h
mbedtls/build_info.h
stddef.h
mbedtls/platform_time.h
time.h
aes.h
aria.h
asn1.h
camellia.h
cipher.h
des.h
ecp.h
md.h
pkcs5.h
ssl.h
mbedtls/build_info.h
mbedtls/check_config.h
mbedtls/config_adjust_legacy_crypto.h
mbedtls/config_adjust_psa_from_legacy.h
mbedtls/config_adjust_psa_superset_legacy.h
mbedtls/config_adjust_ssl.h
mbedtls/config_adjust_x509.h
mbedtls/config_psa.h
mbedtls/mbedtls_config.h
mbedtls/platform_time.h
platform_util.h
psa/crypto_adjust_auto_enabled.h
psa/crypto_adjust_config_dependencies.h
psa/crypto_adjust_config_key_pair_types.h
psa/crypto_adjust_config_synonyms.h
psa/crypto_legacy.h
inttypes.h
limits.h
stddef.h
stdint.h
time.h
aes.h
aria.h
asn1.h
asn1write.h
block_cipher.h
camellia.h
ccm.h
cipher.h
cmac.h
ctr_drbg.h
debug.h
des.h
ecdh.h
ecdsa.h
ecjpake.h
ecp.h
entropy.h
gcm.h
hkdf.h
hmac_drbg.h
md.h
net_sockets.h
nist_kw.h
oid.h
pk.h
pkcs12.h
pkcs5.h
pkcs7.h
platform_util.h
psa_util.h
rsa.h
ssl.h
ssl_cache.h
ssl_ciphersuites.h
ssl_cookie.h
ssl_ticket.h
x509.h
x509_crl.h
x509_crt.h
x509_csr.h
crypto.h
crypto_builtin_composites.h
crypto_builtin_primitives.h
crypto_driver_contexts_composites.h
crypto_driver_contexts_primitives.h
crypto_struct.h
SECTION: Module configuration options

This section allows for the setting of module specific sizes and configuration options. The default values are already present in the relevant header files and should suffice for the regular use cases.

Our advice is to enable options and change their values here only if you have a good reason and know the consequences.

MBEDTLS_CHECK_RETURN

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.

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.

MBEDTLS_IGNORE_RETURN
result
((void) !(result))

This macro requires one argument, which should be a C function call. If that function call would cause a MBEDTLS_CHECK_RETURN warning, this warning is suppressed.

Call this macro with one argument, a function call, to suppress a warning from MBEDTLS_CHECK_RETURN due to that function call.

MBEDTLS_DEPRECATED
__attribute__((deprecated))
MBEDTLS_DEPRECATED_STRING_CONSTANT
VAL
((mbedtls_deprecated_string_constant_t) (VAL))
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT
VAL
((mbedtls_deprecated_numeric_constant_t) (VAL))
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.

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.

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.

MBEDTLS_DEPRECATED typedef char const * MBEDTLS_DEPRECATED typedef char const* mbedtls_deprecated_string_constant_t mbedtls_deprecated_string_constant_t
MBEDTLS_DEPRECATED typedef int MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t mbedtls_deprecated_numeric_constant_t
void void mbedtls_platform_zeroize (void *buf, size_t len) 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 buf

Buffer to be zeroized

len

Length of the buffer in bytes

struct tm * struct tm * mbedtls_platform_gmtime_r (const mbedtls_time_t *tt, struct tm *tm_buf) 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. 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

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

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

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */
    #ifndefMBEDTLS_PLATFORM_UTIL_H
    #defineMBEDTLS_PLATFORM_UTIL_H

    #include"mbedtls/build_info.h"

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

    #ifdef__cplusplus
    extern"C"{
    #endif

    /*InternalhelpermacrosfordeprecatingAPIconstants.*/
    #if!defined(MBEDTLS_DEPRECATED_REMOVED)
    #ifdefined(MBEDTLS_DEPRECATED_WARNING)
    #defineMBEDTLS_DEPRECATED__attribute__((deprecated))
    MBEDTLS_DEPRECATEDtypedefcharconst*mbedtls_deprecated_string_constant_t;
    #defineMBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)\
    ((mbedtls_deprecated_string_constant_t)(VAL))
    MBEDTLS_DEPRECATEDtypedefintmbedtls_deprecated_numeric_constant_t;
    #defineMBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL)\
    ((mbedtls_deprecated_numeric_constant_t)(VAL))
    #else/*MBEDTLS_DEPRECATED_WARNING*/
    #defineMBEDTLS_DEPRECATED
    #defineMBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)VAL
    #defineMBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL)VAL
    #endif/*MBEDTLS_DEPRECATED_WARNING*/
    #endif/*MBEDTLS_DEPRECATED_REMOVED*/

    /*Implementationofthecheck-returnfacility.
    *Seetheuserdocumentationinmbedtls_config.h.
    *
    *Donotusethismacrodirectlytoannotatefunction:instead,
    *useoneofMBEDTLS_CHECK_RETURN_CRITICALorMBEDTLS_CHECK_RETURN_TYPICAL
    *dependingonhowimportantitistocheckthereturnvalue.
    */
    #if!defined(MBEDTLS_CHECK_RETURN)
    #ifdefined(__GNUC__)
    #defineMBEDTLS_CHECK_RETURN__attribute__((__warn_unused_result__))
    #elifdefined(_MSC_VER)&&_MSC_VER>=1700
    #include<sal.h>
    #defineMBEDTLS_CHECK_RETURN_Check_return_
    #else
    #defineMBEDTLS_CHECK_RETURN
    #endif
    #endif

    #defineMBEDTLS_CHECK_RETURN_CRITICALMBEDTLS_CHECK_RETURN

    #ifdefined(MBEDTLS_CHECK_RETURN_WARNING)
    #defineMBEDTLS_CHECK_RETURN_TYPICALMBEDTLS_CHECK_RETURN
    #else
    #defineMBEDTLS_CHECK_RETURN_TYPICAL
    #endif

    #defineMBEDTLS_CHECK_RETURN_OPTIONAL

    #if!defined(MBEDTLS_IGNORE_RETURN)
    /*GCCdoesn'tsilencethewarningwithjust(void)(result).
    *(void)!(result)isknowntoworkupatleastuptoGCC10,aswell
    *aswithClangandMSVC.
    *
    *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
    */
    #defineMBEDTLS_IGNORE_RETURN(result)((void)!(result))
    #endif

    /*Ifthefollowingmacroisdefined,thelibraryisbeingbuiltbythetest
    *framework,andtheframeworkisgoingtoprovideareplacement
    *mbedtls_platform_zeroize()usingapreprocessormacro,sothefunction
    *declarationshouldbeomitted.*/
    #if!defined(MBEDTLS_TEST_DEFINES_ZEROIZE)//no-check-names
    voidmbedtls_platform_zeroize(void*buf,size_tlen);
    #endif

    #ifdefined(MBEDTLS_HAVE_TIME_DATE)
    structtm*mbedtls_platform_gmtime_r(constmbedtls_time_t*tt,
    structtm*tm_buf);
    #endif/*MBEDTLS_HAVE_TIME_DATE*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*MBEDTLS_PLATFORM_UTIL_H*/