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 "tf-psa-crypto/build_info.h"
#include "mbedtls/platform_time.h"
#include <psa/crypto_driver_random.h>
#include <stdlib.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_free   MBEDTLS_PLATFORM_FREE_MACRO
#define	mbedtls_calloc   MBEDTLS_PLATFORM_CALLOC_MACRO
#define	MBEDTLS_EXIT_SUCCESS   MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
#define	MBEDTLS_EXIT_FAILURE   MBEDTLS_PLATFORM_STD_EXIT_FAILURE

Functions
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_get_entropy (psa_driver_get_entropy_flags_t flags, size_t *estimate_bits, unsigned char *output, size_t output_size)
	User defined callback function that is used from the entropy module to gather entropy data from some hardware device. 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_calloc   MBEDTLS_PLATFORM_CALLOC_MACRO

Definition at line 146 of file platform.h.

#define MBEDTLS_EXIT_FAILURE   MBEDTLS_PLATFORM_STD_EXIT_FAILURE

Definition at line 385 of file platform.h.

#define MBEDTLS_EXIT_SUCCESS   MBEDTLS_PLATFORM_STD_EXIT_SUCCESS

Definition at line 380 of file platform.h.

#define mbedtls_free   MBEDTLS_PLATFORM_FREE_MACRO

Definition at line 145 of file platform.h.

Function Documentation

int mbedtls_platform_get_entropy	(	psa_driver_get_entropy_flags_t	flags,
		size_t *	estimate_bits,
		unsigned char *	output,
		size_t	output_size
	)

User defined callback function that is used from the entropy module to gather entropy data from some hardware device.

Parameters

	flags	A mask of PSA_DRIVER_GET_ENTROPY_xxx flags. As of TF-PSA-Crypto 1.0, this is always 0.
[out]	estimate_bits	Measure of the entropy content (in bits) of the data written in the output buffer.
[out]	output	Output buffer where the entropy data will be stored.
	output_size	Size of the output buffer in bytes.

Return values

0	Success.
PSA_ERROR_INSUFFICIENT_ENTROPY	The entropy source failed.
PSA_ERROR_NOT_SUPPORTED	The value of flags is not supported.

Warning

For the time being TF-PSA-Crypto only supports implementations that return a maximum entropy output on each call, i.e. estimate_bits = 8 * output_size. Returning a smaller entropy content is the same as returning PSA_ERROR_INSUFFICIENT_ENTROPY so the hardware polling will fail. In the future TF-PSA-Crypto will be smarter and capable to cope with entropy sources with lower entropy content (i.e. 0 < estimate_bits < 8 * output_size) by calling the callback function in loop.

Note

This function is not meant to be called by application code, and it is not guaranteed that this function will exist or will behave in the same way in future versions of the library. Applications should call psa_generate_random() to obtain random data.

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_func

The 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_func

The 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_func	The seed reading function implementation.
nv_seed_write_func	The 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_func

The 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_func

The 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_func

The 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_func

The 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

ctx	The 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

ctx	The 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)