Mbed TLS v4.1.1
Loading...
Searching...
No Matches
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 <stdio.h>
#include <stdlib.h>
#include <time.h>
Include dependency graph for platform.h:

Go to the source code of this file.

Data Structures

struct  mbedtls_platform_context
 The platform context structure. More...

Macros

#define mbedtls_free   free
#define mbedtls_calloc   calloc
#define mbedtls_fprintf   fprintf
#define mbedtls_printf   printf
#define mbedtls_snprintf   MBEDTLS_PLATFORM_STD_SNPRINTF
#define mbedtls_vsnprintf   vsnprintf
#define mbedtls_setbuf   setbuf
#define mbedtls_exit   exit
#define MBEDTLS_EXIT_SUCCESS   MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
#define MBEDTLS_EXIT_FAILURE   MBEDTLS_PLATFORM_STD_EXIT_FAILURE
#define MBEDTLS_PLATFORM_HAVE_DEV_RANDOM
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_SNPRINTF   snprintf
#define MBEDTLS_PLATFORM_STD_VSNPRINTF   vsnprintf
#define MBEDTLS_PLATFORM_STD_PRINTF   printf
#define MBEDTLS_PLATFORM_STD_FPRINTF   fprintf
#define MBEDTLS_PLATFORM_STD_SETBUF   setbuf
#define MBEDTLS_PLATFORM_STD_EXIT   exit
#define MBEDTLS_PLATFORM_STD_TIME   time
#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS   EXIT_SUCCESS
#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE   EXIT_FAILURE
#define MBEDTLS_PLATFORM_STD_NV_SEED_READ   mbedtls_platform_std_nv_seed_read
#define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE   mbedtls_platform_std_nv_seed_write
#define MBEDTLS_PLATFORM_STD_NV_SEED_FILE   "seedfile"
SECTION: Platform abstraction layer

This section sets platform specific settings.

#define MBEDTLS_PLATFORM_STD_CALLOC   calloc
#define MBEDTLS_PLATFORM_STD_FREE   free
#define MBEDTLS_PLATFORM_DEV_RANDOM   "/dev/random"

Typedefs

typedef struct mbedtls_platform_context mbedtls_platform_context
 The platform context structure.

Functions

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.
int mbedtls_platform_setup (mbedtls_platform_context *ctx)
 This function performs any platform-specific initialization operations.
void mbedtls_platform_teardown (mbedtls_platform_context *ctx)
 This function performs any platform teardown operations.

Variables

const char * mbedtls_platform_dev_random

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

◆ mbedtls_calloc

#define mbedtls_calloc   calloc

Definition at line 152 of file platform.h.

◆ mbedtls_exit

#define mbedtls_exit   exit

Definition at line 336 of file platform.h.

◆ MBEDTLS_EXIT_FAILURE

#define MBEDTLS_EXIT_FAILURE   MBEDTLS_PLATFORM_STD_EXIT_FAILURE

Definition at line 349 of file platform.h.

◆ MBEDTLS_EXIT_SUCCESS

#define MBEDTLS_EXIT_SUCCESS   MBEDTLS_PLATFORM_STD_EXIT_SUCCESS

Definition at line 344 of file platform.h.

◆ mbedtls_fprintf

#define mbedtls_fprintf   fprintf

Definition at line 179 of file platform.h.

◆ mbedtls_free

#define mbedtls_free   free

Definition at line 151 of file platform.h.

◆ MBEDTLS_PLATFORM_DEV_RANDOM

#define MBEDTLS_PLATFORM_DEV_RANDOM   "/dev/random"

Path to a special file that returns cryptographic-quality random bytes when read. This is used by the default platform entropy source on non-Windows platforms unless a dedicated system call is available (see MBEDTLS_PSA_BUILTIN_GET_ENTROPY).

The default value is /dev/random, which is suitable on most platforms other than Linux. On Linux, either /dev/random or /dev/urandom may be the right choice, depending on the circumstances:

  • If possible, the library will use the getrandom() system call, which is preferable, and MBEDTLS_PLATFORM_DEV_RANDOM is not used.
  • If there is a dedicated hardware entropy source (e.g. RDRAND on x86 processors), then both /dev/random and /dev/urandom are fine.
  • /dev/random is always secure. However, with kernels older than 5.6, /dev/random often blocks unnecessarily if there is no dedicated hardware entropy source.
  • /dev/urandom never blocks. However, it may return predictable data if it is used early after the kernel boots, especially on embedded devices without an interactive user.

Thus you should change the value to /dev/urandom if your application definitely won't be used on a device running Linux without a dedicated entropy source early during or after boot.

This is the default value of mbedtls_platform_dev_random, which can be changed at run time.

Definition at line 363 of file platform.h.

◆ MBEDTLS_PLATFORM_HAVE_DEV_RANDOM

#define MBEDTLS_PLATFORM_HAVE_DEV_RANDOM

Definition at line 359 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_CALLOC

#define MBEDTLS_PLATFORM_STD_CALLOC   calloc

The default calloc function to use.

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 69 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_EXIT

#define MBEDTLS_PLATFORM_STD_EXIT   exit

The default exit function to use.

Definition at line 78 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_EXIT_FAILURE

#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE   EXIT_FAILURE

The default exit value to use.

Definition at line 87 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_EXIT_SUCCESS

#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS   EXIT_SUCCESS

The default exit value to use.

Definition at line 84 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_FPRINTF

#define MBEDTLS_PLATFORM_STD_FPRINTF   fprintf

The default fprintf function to use.

Definition at line 66 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_FREE

#define MBEDTLS_PLATFORM_STD_FREE   free

The default free function to use.

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 72 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_NV_SEED_FILE

#define MBEDTLS_PLATFORM_STD_NV_SEED_FILE   "seedfile"

Definition at line 97 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_NV_SEED_READ

#define MBEDTLS_PLATFORM_STD_NV_SEED_READ   mbedtls_platform_std_nv_seed_read

Definition at line 91 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_NV_SEED_WRITE

#define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE   mbedtls_platform_std_nv_seed_write

Definition at line 94 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_PRINTF

#define MBEDTLS_PLATFORM_STD_PRINTF   printf

The default printf function to use.

Definition at line 63 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_SETBUF

#define MBEDTLS_PLATFORM_STD_SETBUF   setbuf

The default setbuf function to use.

Definition at line 75 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_SNPRINTF

#define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf

The default snprintf function to use.

Definition at line 57 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_TIME

#define MBEDTLS_PLATFORM_STD_TIME   time

The default time function to use.

Definition at line 81 of file platform.h.

◆ MBEDTLS_PLATFORM_STD_VSNPRINTF

#define MBEDTLS_PLATFORM_STD_VSNPRINTF   vsnprintf

The default vsnprintf function to use.

Definition at line 60 of file platform.h.

◆ mbedtls_printf

#define mbedtls_printf   printf

Definition at line 214 of file platform.h.

◆ mbedtls_setbuf

#define mbedtls_setbuf   setbuf

Definition at line 311 of file platform.h.

◆ mbedtls_snprintf

#define mbedtls_snprintf   MBEDTLS_PLATFORM_STD_SNPRINTF

Definition at line 236 of file platform.h.

◆ mbedtls_vsnprintf

#define mbedtls_vsnprintf   vsnprintf

Definition at line 258 of file platform.h.

Typedef Documentation

◆ mbedtls_platform_context

typedef struct mbedtls_platform_context mbedtls_platform_context

The platform context structure.

Note
This structure may be used to assist platform-specific setup or teardown operations.

Function Documentation

◆ mbedtls_platform_get_entropy()

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
flagsA mask of PSA_DRIVER_GET_ENTROPY_xxx flags. As of TF-PSA-Crypto 1.0, this is always 0.
[out]estimate_bitsMeasure of the entropy content (in bits) of the data written in the output buffer.
[out]outputOutput buffer where the entropy data will be stored.
output_sizeSize of the output buffer in bytes.
Return values
0Success.
PSA_ERROR_INSUFFICIENT_ENTROPYThe entropy source failed.
PSA_ERROR_NOT_SUPPORTEDThe 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.

◆ mbedtls_platform_setup()

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.

◆ mbedtls_platform_teardown()

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

◆ mbedtls_platform_dev_random

const char* mbedtls_platform_dev_random
extern

Path to a special file that returns cryptographic-quality random bytes when read.

The default value is MBEDTLS_PLATFORM_DEV_RANDOM. See the documentation of this option for guidance.