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

This file contains the definitions and functions of the Mbed TLS platform abstraction layer. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/platform_time.h"
#include <stddef.h>
#include <stdio.h>
#include <stdarg.h>
#include "platform_alt.h"
Include dependency graph for platform.h:

Go to the source code of this file.

Macros

#define MBEDTLS_EXIT_SUCCESS   0
 
#define MBEDTLS_EXIT_FAILURE   1
 
SECTION: Module settings

The configuration options you can set for this module are in this section. Either change them in mbedtls_config.h or define them on the compiler command line.

#define MBEDTLS_PLATFORM_STD_CALLOC
 
#define MBEDTLS_PLATFORM_STD_FREE
 

Functions

void * mbedtls_calloc (size_t n, size_t size)
 
void mbedtls_free (void *ptr)
 
int mbedtls_platform_set_calloc_free (void *(*calloc_func)(size_t, size_t), void(*free_func)(void *))
 This function dynamically sets the memory-management functions used by the library, during runtime. More...
 
int mbedtls_platform_set_fprintf (int(*fprintf_func)(FILE *stream, const char *,...))
 This function dynamically configures the fprintf function that is called when the mbedtls_fprintf() function is invoked by the library. More...
 
int mbedtls_platform_set_printf (int(*printf_func)(const char *,...))
 This function dynamically configures the snprintf function that is called when the mbedtls_snprintf() function is invoked by the library. More...
 
int mbedtls_platform_set_snprintf (int(*snprintf_func)(char *s, size_t n, const char *format,...))
 This function allows configuring a custom snprintf function pointer. More...
 
int mbedtls_platform_set_vsnprintf (int(*vsnprintf_func)(char *s, size_t n, const char *format, va_list arg))
 Set your own snprintf function pointer. More...
 
int mbedtls_platform_set_setbuf (void(*setbuf_func)(FILE *stream, char *buf))
 Dynamically configure the function that is called when the mbedtls_setbuf() function is called by the library. More...
 
int mbedtls_platform_set_exit (void(*exit_func)(int status))
 This function dynamically configures the exit function that is called when the mbedtls_exit() function is invoked by the library. More...
 
int mbedtls_platform_set_nv_seed (int(*nv_seed_read_func)(unsigned char *buf, size_t buf_len), int(*nv_seed_write_func)(unsigned char *buf, size_t buf_len))
 This function allows configuring custom seed file writing and reading functions. More...
 
int mbedtls_platform_setup (mbedtls_platform_context *ctx)
 This function performs any platform-specific initialization operations. More...
 
void mbedtls_platform_teardown (mbedtls_platform_context *ctx)
 This function performs any platform teardown operations. More...
 

Variables

int(* mbedtls_fprintf )(FILE *stream, const char *format,...)
 
int(* mbedtls_printf )(const char *format,...)
 
int(* mbedtls_snprintf )(char *s, size_t n, const char *format,...)
 
int(* mbedtls_vsnprintf )(char *s, size_t n, const char *format, va_list arg)
 
void(* mbedtls_setbuf )(FILE *stream, char *buf)
 Function pointer to call for setbuf() functionality (changing the internal buffering on stdio calls). More...
 
void(* mbedtls_exit )(int status)
 
int(* mbedtls_nv_seed_read )(unsigned char *buf, size_t buf_len)
 
int(* mbedtls_nv_seed_write )(unsigned char *buf, size_t buf_len)
 

Detailed Description

This file contains the definitions and functions of the Mbed TLS platform abstraction layer.

The platform abstraction layer removes the need for the library to directly link to standard C library functions or operating system services, making the library easier to port and embed. Application developers and users of the library can provide their own implementations of these functions, or implementations specific to their platform, which can be statically linked to the library or dynamically configured at runtime.

When all compilation options related to platform abstraction are disabled, this header just defines mbedtls_xxx function names as aliases to the standard xxx function.

Most modules in the library and example programs are expected to include this header.

Definition in file platform.h.

Macro Definition Documentation

#define MBEDTLS_EXIT_FAILURE   1

Definition at line 385 of file platform.h.

#define MBEDTLS_EXIT_SUCCESS   0

Definition at line 380 of file platform.h.

#define MBEDTLS_PLATFORM_STD_CALLOC

Default allocator to use, can be undefined. It must initialize the allocated buffer memory to zeroes. The size of the buffer is the product of the two parameters. The calloc function returns either a null pointer or a pointer to the allocated space. If the product is 0, the function may either return NULL or a valid pointer to an array of size 0 which is a valid input to the deallocation function. An uninitialized MBEDTLS_PLATFORM_STD_CALLOC always fails, returning a null pointer. See the description of MBEDTLS_PLATFORM_MEMORY for more details. The corresponding deallocation function is MBEDTLS_PLATFORM_STD_FREE.

Definition at line 124 of file platform.h.

#define MBEDTLS_PLATFORM_STD_FREE

Default free to use, can be undefined. NULL is a valid parameter, and the function must do nothing. A non-null parameter will always be a pointer previously returned by MBEDTLS_PLATFORM_STD_CALLOC and not yet freed. An uninitialized MBEDTLS_PLATFORM_STD_FREE does not do anything. See the description of MBEDTLS_PLATFORM_MEMORY for more details (same principles as for MBEDTLS_PLATFORM_STD_CALLOC apply).

Definition at line 128 of file platform.h.

Function Documentation

void* mbedtls_calloc ( size_t  n,
size_t  size 
)
void mbedtls_free ( void *  ptr)
int mbedtls_platform_set_calloc_free ( void *(*)(size_t, size_t)  calloc_func,
void(*)(void *)  free_func 
)

This function dynamically sets the memory-management functions used by the library, during runtime.

Parameters
calloc_funcThe calloc function implementation.
free_funcThe free function implementation.
Returns
0.
int mbedtls_platform_set_exit ( void(*)(int status)  exit_func)

This function dynamically configures the exit function that is called when the mbedtls_exit() function is invoked by the library.

Parameters
exit_funcThe exit function implementation.
Returns
0 on success.
int mbedtls_platform_set_fprintf ( int(*)(FILE *stream, const char *,...)  fprintf_func)

This function dynamically configures the fprintf function that is called when the mbedtls_fprintf() function is invoked by the library.

Parameters
fprintf_funcThe fprintf function implementation.
Returns
0.
int mbedtls_platform_set_nv_seed ( int(*)(unsigned char *buf, size_t buf_len)  nv_seed_read_func,
int(*)(unsigned char *buf, size_t buf_len)  nv_seed_write_func 
)

This function allows configuring custom seed file writing and reading functions.

Parameters
nv_seed_read_funcThe seed reading function implementation.
nv_seed_write_funcThe seed writing function implementation.
Returns
0 on success.
int mbedtls_platform_set_printf ( int(*)(const char *,...)  printf_func)

This function dynamically configures the snprintf function that is called when the mbedtls_snprintf() function is invoked by the library.

Parameters
printf_funcThe printf function implementation.
Returns
0 on success.
int mbedtls_platform_set_setbuf ( void(*)(FILE *stream, char *buf)  setbuf_func)

Dynamically configure the function that is called when the mbedtls_setbuf() function is called by the library.

Parameters
setbuf_funcThe setbuf function implementation
Returns
0
int mbedtls_platform_set_snprintf ( int(*)(char *s, size_t n, const char *format,...)  snprintf_func)

This function allows configuring a custom snprintf function pointer.

Parameters
snprintf_funcThe snprintf function implementation.
Returns
0 on success.
int mbedtls_platform_set_vsnprintf ( int(*)(char *s, size_t n, const char *format, va_list arg)  vsnprintf_func)

Set your own snprintf function pointer.

Parameters
vsnprintf_funcThe vsnprintf function implementation
Returns
0
int mbedtls_platform_setup ( mbedtls_platform_context ctx)

This function performs any platform-specific initialization operations.

Note
This function should be called before any other library functions.
     Its implementation is platform-specific, and unless
     platform-specific code is provided, it does nothing.
The usage and necessity of this function is dependent on the platform.
Parameters
ctxThe platform context.
Returns
0 on success.
void mbedtls_platform_teardown ( mbedtls_platform_context ctx)

This function performs any platform teardown operations.

Note
This function should be called after every other Mbed TLS module has been correctly freed using the appropriate free function.

Its implementation is platform-specific, and unless platform-specific code is provided, it does nothing.

Note
The usage and necessity of this function is dependent on the platform.
Parameters
ctxThe platform context.

Variable Documentation

void(* mbedtls_exit)(int status)
int(* mbedtls_fprintf)(FILE *stream, const char *format,...)
int(* mbedtls_nv_seed_read)(unsigned char *buf, size_t buf_len)
int(* mbedtls_nv_seed_write)(unsigned char *buf, size_t buf_len)
int(* mbedtls_printf)(const char *format,...)
void(* mbedtls_setbuf)(FILE *stream, char *buf)

Function pointer to call for setbuf() functionality (changing the internal buffering on stdio calls).

Note
The library calls this function to disable buffering when reading or writing sensitive data, to avoid having extra copies of sensitive data remaining in stdio buffers after the file is closed. If this is not a concern, for example if your platform's stdio doesn't have any buffering, you can set mbedtls_setbuf to a function that does nothing.

The library always calls this function with buf equal to NULL.

int(* mbedtls_snprintf)(char *s, size_t n, const char *format,...)
int(* mbedtls_vsnprintf)(char *s, size_t n, const char *format, va_list arg)