NCBI C++ ToolKit
Macros | Functions
platform_util.h File Reference

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

#include "mbedtls/config.h"
#include <stddef.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.

Go to the SVN repository for this file.

Macros

#define MBEDTLS_INTERNAL_VALIDATE_RET(cond, ret)   do { } while (0)
 
#define MBEDTLS_INTERNAL_VALIDATE(cond)   do { } while (0)
 
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL)   VAL
 
#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL)   VAL
 
#define MBEDTLS_CHECK_RETURN_CRITICAL   MBEDTLS_CHECK_RETURN
 Critical-failure function. More...
 
#define MBEDTLS_CHECK_RETURN_TYPICAL
 Ordinary-failure function. More...
 
#define MBEDTLS_CHECK_RETURN_OPTIONAL
 Benign-failure function. More...
 
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.

#define MBEDTLS_CHECK_RETURN
 This macro is invoked by the library when an invalid parameter is detected that is only checked with #MBEDTLS_CHECK_PARAMS (see the documentation of that option for context). More...
 
#define MBEDTLS_IGNORE_RETURN(result)   ((void) !(result))
 This macro requires one argument, which should be a C function call. More...
 

Functions

void mbedtls_platform_zeroize (void *buf, size_t len)
 Securely zeroize a buffer. 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

◆ MBEDTLS_CHECK_RETURN

#define MBEDTLS_CHECK_RETURN

This macro is invoked by the library when an invalid parameter is detected that is only checked with #MBEDTLS_CHECK_PARAMS (see the documentation of that option for context).

When you leave this undefined here, the library provides a default definition. If the macro #MBEDTLS_CHECK_PARAMS_ASSERT is defined, the default definition is `assert(cond)`, otherwise the default definition calls a function mbedtls_param_failed(). This function is declared in `platform_util.h` for the benefit of the library, but you need to define in your application.

When you define this here, this replaces the default definition in platform_util.h (which no longer declares the function mbedtls_param_failed()) and it is your responsibility to make sure this macro expands to something suitable (in particular, that all the necessary declarations are visible from within the library - you can ensure that by providing them in this file next to the macro definition). If you define this macro to call `assert`, also define #MBEDTLS_CHECK_PARAMS_ASSERT so that library source files include `<assert.h>`.

Note that you may define this macro to expand to nothing, in which case you don't have to worry about declarations or definitions. However, you will then be notified about invalid parameters only in non-void functions, and void function will just silently return early on invalid parameters, which partially negates the benefits of enabling #MBEDTLS_CHECK_PARAMS in the first place, so is discouraged.

Parameters
condThe expression that should evaluate to true, but doesn't.

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.

Definition at line 149 of file platform_util.h.

◆ MBEDTLS_CHECK_RETURN_CRITICAL

#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 169 of file platform_util.h.

◆ MBEDTLS_CHECK_RETURN_OPTIONAL

#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 205 of file platform_util.h.

◆ MBEDTLS_CHECK_RETURN_TYPICAL

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

Definition at line 191 of file platform_util.h.

◆ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT

#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT (   VAL)    VAL

Definition at line 131 of file platform_util.h.

◆ MBEDTLS_DEPRECATED_STRING_CONSTANT

#define MBEDTLS_DEPRECATED_STRING_CONSTANT (   VAL)    VAL

Definition at line 130 of file platform_util.h.

◆ MBEDTLS_IGNORE_RETURN

#define MBEDTLS_IGNORE_RETURN (   result)    ((void) !(result))

This macro requires one argument, which should be a C function call.

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

If that function call would cause a MBEDTLS_CHECK_RETURN warning, this warning is suppressed.

Definition at line 221 of file platform_util.h.

◆ MBEDTLS_INTERNAL_VALIDATE

#define MBEDTLS_INTERNAL_VALIDATE (   cond)    do { } while (0)

Definition at line 110 of file platform_util.h.

◆ MBEDTLS_INTERNAL_VALIDATE_RET

#define MBEDTLS_INTERNAL_VALIDATE_RET (   cond,
  ret 
)    do { } while (0)

Definition at line 109 of file platform_util.h.

Function Documentation

◆ mbedtls_platform_zeroize()

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

Referenced by block_cipher_df(), chacha20_block(), ctr_drbg_update_internal(), ecp_drbg_seed(), entropy_gather_internal(), entropy_update(), hmac_drbg_reseed_core(), load_file(), mbedtls_aes_free_ncbicxx_2_28_3(), mbedtls_arc4_free_ncbicxx_2_28_3(), mbedtls_asn1_free_named_data_ncbicxx_2_28_3(), mbedtls_asn1_get_alg_ncbicxx_2_28_3(), mbedtls_asn1_sequence_free_ncbicxx_2_28_3(), mbedtls_blowfish_free_ncbicxx_2_28_3(), mbedtls_camellia_free_ncbicxx_2_28_3(), mbedtls_ccm_free_ncbicxx_2_28_3(), mbedtls_ccm_star_auth_decrypt_ncbicxx_2_28_3(), mbedtls_chacha20_free_ncbicxx_2_28_3(), mbedtls_chacha20_init_ncbicxx_2_28_3(), mbedtls_chacha20_starts_ncbicxx_2_28_3(), mbedtls_chachapoly_auth_decrypt_ncbicxx_2_28_3(), mbedtls_chachapoly_starts_ncbicxx_2_28_3(), mbedtls_cipher_check_tag_ncbicxx_2_28_3(), mbedtls_cipher_free_ncbicxx_2_28_3(), mbedtls_ctr_drbg_free_ncbicxx_2_28_3(), mbedtls_ctr_drbg_random_with_add_ncbicxx_2_28_3(), mbedtls_ctr_drbg_reseed_internal(), mbedtls_ctr_drbg_update_ret_ncbicxx_2_28_3(), mbedtls_ctr_drbg_update_seed_file_ncbicxx_2_28_3(), mbedtls_ctr_drbg_write_seed_file_ncbicxx_2_28_3(), mbedtls_des3_free_ncbicxx_2_28_3(), mbedtls_des3_set2key_dec_ncbicxx_2_28_3(), mbedtls_des3_set2key_enc_ncbicxx_2_28_3(), mbedtls_des3_set3key_dec_ncbicxx_2_28_3(), mbedtls_des3_set3key_enc_ncbicxx_2_28_3(), mbedtls_des_free_ncbicxx_2_28_3(), mbedtls_dhm_free_ncbicxx_2_28_3(), mbedtls_dhm_parse_dhmfile_ncbicxx_2_28_3(), mbedtls_ecp_group_free_ncbicxx_2_28_3(), mbedtls_entropy_free_ncbicxx_2_28_3(), mbedtls_entropy_func_ncbicxx_2_28_3(), mbedtls_entropy_update_seed_file_ncbicxx_2_28_3(), mbedtls_entropy_write_seed_file_ncbicxx_2_28_3(), mbedtls_gcm_auth_decrypt_ncbicxx_2_28_3(), mbedtls_gcm_free_ncbicxx_2_28_3(), mbedtls_hkdf_expand_ncbicxx_2_28_3(), mbedtls_hkdf_ncbicxx_2_28_3(), mbedtls_hmac_drbg_free_ncbicxx_2_28_3(), mbedtls_hmac_drbg_update_ret_ncbicxx_2_28_3(), mbedtls_hmac_drbg_update_seed_file_ncbicxx_2_28_3(), mbedtls_hmac_drbg_write_seed_file_ncbicxx_2_28_3(), mbedtls_internal_aes_decrypt_ncbicxx_2_28_3(), mbedtls_internal_aes_encrypt_ncbicxx_2_28_3(), mbedtls_internal_md5_process_ncbicxx_2_28_3(), mbedtls_internal_ripemd160_process_ncbicxx_2_28_3(), mbedtls_internal_sha1_process_ncbicxx_2_28_3(), mbedtls_internal_sha256_process_ncbicxx_2_28_3(), mbedtls_internal_sha512_process_ncbicxx_2_28_3(), mbedtls_md5_free_ncbicxx_2_28_3(), mbedtls_md_file_ncbicxx_2_28_3(), mbedtls_md_free_ncbicxx_2_28_3(), mbedtls_md_hmac_starts_ncbicxx_2_28_3(), mbedtls_mpi_div_mpi_ncbicxx_2_28_3(), mbedtls_mpi_zeroize(), mbedtls_pem_free_ncbicxx_2_28_3(), mbedtls_pem_read_buffer_ncbicxx_2_28_3(), mbedtls_pk_free_ncbicxx_2_28_3(), mbedtls_pk_load_file_ncbicxx_2_28_3(), mbedtls_pk_parse_key_ncbicxx_2_28_3(), mbedtls_pk_parse_keyfile_ncbicxx_2_28_3(), mbedtls_pk_parse_public_keyfile_ncbicxx_2_28_3(), mbedtls_pkcs12_derivation_ncbicxx_2_28_3(), mbedtls_pkcs12_pbe_ncbicxx_2_28_3(), mbedtls_pkcs12_pbe_sha1_rc4_128_ncbicxx_2_28_3(), mbedtls_pkcs5_pbkdf2_hmac_ncbicxx_2_28_3(), mbedtls_poly1305_free_ncbicxx_2_28_3(), mbedtls_poly1305_init_ncbicxx_2_28_3(), mbedtls_poly1305_starts_ncbicxx_2_28_3(), mbedtls_psa_crypto_free_ncbicxx_2_28_3(), mbedtls_ripemd160_free_ncbicxx_2_28_3(), mbedtls_rsa_rsaes_oaep_decrypt_ncbicxx_2_28_3(), mbedtls_rsa_rsaes_pkcs1_v15_decrypt_ncbicxx_2_28_3(), mbedtls_rsa_rsassa_pkcs1_v15_sign_ncbicxx_2_28_3(), mbedtls_rsa_rsassa_pkcs1_v15_verify_ncbicxx_2_28_3(), mbedtls_sha1_free_ncbicxx_2_28_3(), mbedtls_sha256_free_ncbicxx_2_28_3(), mbedtls_sha512_free_ncbicxx_2_28_3(), mbedtls_ssl_check_record_ncbicxx_2_28_3(), mbedtls_ssl_config_free_ncbicxx_2_28_3(), mbedtls_ssl_cookie_check_ncbicxx_2_28_3(), mbedtls_ssl_cookie_free_ncbicxx_2_28_3(), mbedtls_ssl_cookie_setup_ncbicxx_2_28_3(), mbedtls_ssl_decrypt_buf_ncbicxx_2_28_3(), mbedtls_ssl_derive_keys_ncbicxx_2_28_3(), mbedtls_ssl_encrypt_buf_ncbicxx_2_28_3(), mbedtls_ssl_free_ncbicxx_2_28_3(), mbedtls_ssl_handshake_free_ncbicxx_2_28_3(), mbedtls_ssl_parse_finished_ncbicxx_2_28_3(), mbedtls_ssl_read_ncbicxx_2_28_3(), mbedtls_ssl_session_free_ncbicxx_2_28_3(), mbedtls_ssl_set_hostname_ncbicxx_2_28_3(), mbedtls_ssl_ticket_free_ncbicxx_2_28_3(), mbedtls_ssl_transform_free_ncbicxx_2_28_3(), mbedtls_x509_crl_free_ncbicxx_2_28_3(), mbedtls_x509_crl_parse_file_ncbicxx_2_28_3(), mbedtls_x509_crt_free_ncbicxx_2_28_3(), mbedtls_x509_crt_parse_file_ncbicxx_2_28_3(), mbedtls_x509_csr_free_ncbicxx_2_28_3(), mbedtls_x509_csr_parse_file_ncbicxx_2_28_3(), mbedtls_x509_get_name_ncbicxx_2_28_3(), mbedtls_x509write_crt_free_ncbicxx_2_28_3(), mbedtls_x509write_csr_free_ncbicxx_2_28_3(), mbedtls_xtea_free_ncbicxx_2_28_3(), mgf_mask(), pem_aes_decrypt(), pem_des3_decrypt(), pem_des_decrypt(), pem_pbkdf1(), pk_write_ec_private(), psa_driver_wrapper_cipher_abort_ncbicxx_2_28_3(), psa_free_persistent_key_data_ncbicxx_2_28_3(), psa_hash_compare_ncbicxx_2_28_3(), psa_hash_verify_ncbicxx_2_28_3(), psa_key_agreement_internal(), psa_key_derivation_abort_ncbicxx_2_28_3(), psa_load_persistent_key_ncbicxx_2_28_3(), psa_mac_verify_ncbicxx_2_28_3(), psa_remove_key_data_from_memory_ncbicxx_2_28_3(), psa_save_persistent_key_ncbicxx_2_28_3(), rsa_alt_free_wrap(), rsa_rsassa_pkcs1_v15_encode(), ssl_buffering_free_slot(), ssl_calc_finished_tls(), ssl_calc_finished_tls_sha256(), ssl_calc_finished_tls_sha384(), ssl_compute_master(), ssl_parse_new_session_ticket(), ssl_parse_session_ticket_ext(), ssl_populate_transform(), ssl_ticket_gen_key(), tls1_prf(), tls_prf_generic(), and x509_get_subject_alt_name().

Modified on Thu Feb 29 12:21:13 2024 by modify_doxy.py rev. 669887