include/mbedtls/platform.h

0001 /**
0002  * \file platform.h
0003  *
0004  * \brief This file contains the definitions and functions of the
0005  *        Mbed TLS platform abstraction layer.
0006  *
0007  *        The platform abstraction layer removes the need for the library
0008  *        to directly link to standard C library functions or operating
0009  *        system services, making the library easier to port and embed.
0010  *        Application developers and users of the library can provide their own
0011  *        implementations of these functions, or implementations specific to
0012  *        their platform, which can be statically linked to the library or
0013  *        dynamically configured at runtime.
0014  *
0015  *        When all compilation options related to platform abstraction are
0016  *        disabled, this header just defines `mbedtls_xxx` function names
0017  *        as aliases to the standard `xxx` function.
0018  *
0019  *        Most modules in the library and example programs are expected to
0020  *        include this header.
0021  */
0022 /*
0023  *  Copyright The Mbed TLS Contributors
0024  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0025  */
0026 #ifndef MBEDTLS_PLATFORM_H
0027 #define MBEDTLS_PLATFORM_H
0028 #include "mbedtls/private_access.h"
0029
0030 #include "mbedtls/build_info.h"
0031
0032 #if defined(MBEDTLS_HAVE_TIME)
0033 #include "mbedtls/platform_time.h"
0034 #endif
0035
0036 #ifdef __cplusplus
0037 extern "C" {
0038 #endif
0039
0040 /**
0041  * \name SECTION: Module settings
0042  *
0043  * The configuration options you can set for this module are in this section.
0044  * Either change them in mbedtls_config.h or define them on the compiler command line.
0045  * \{
0046  */
0047
0048 /* The older Microsoft Windows common runtime provides non-conforming
0049  * implementations of some standard library functions, including snprintf
0050  * and vsnprintf. This affects MSVC and MinGW builds.
0051  */
0052 #if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900)
0053 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF
0054 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF
0055 #endif
0056
0057 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
0058 #include <stdio.h>
0059 #include <stdlib.h>
0060 #if defined(MBEDTLS_HAVE_TIME)
0061 #include <time.h>
0062 #endif
0063 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
0064 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
0065 #define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use.  */
0066 #else
0067 #define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf /**< The default \c snprintf function to use.  */
0068 #endif
0069 #endif
0070 #if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF)
0071 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
0072 #define MBEDTLS_PLATFORM_STD_VSNPRINTF   mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use.  */
0073 #else
0074 #define MBEDTLS_PLATFORM_STD_VSNPRINTF   vsnprintf /**< The default \c vsnprintf function to use.  */
0075 #endif
0076 #endif
0077 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
0078 #define MBEDTLS_PLATFORM_STD_PRINTF   printf /**< The default \c printf function to use. */
0079 #endif
0080 #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
0081 #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
0082 #endif
0083 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
0084 #define MBEDTLS_PLATFORM_STD_CALLOC   calloc /**< The default \c calloc function to use. */
0085 #endif
0086 #if !defined(MBEDTLS_PLATFORM_STD_FREE)
0087 #define MBEDTLS_PLATFORM_STD_FREE       free /**< The default \c free function to use. */
0088 #endif
0089 #if !defined(MBEDTLS_PLATFORM_STD_SETBUF)
0090 #define MBEDTLS_PLATFORM_STD_SETBUF   setbuf /**< The default \c setbuf function to use. */
0091 #endif
0092 #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
0093 #define MBEDTLS_PLATFORM_STD_EXIT      exit /**< The default \c exit function to use. */
0094 #endif
0095 #if !defined(MBEDTLS_PLATFORM_STD_TIME)
0096 #define MBEDTLS_PLATFORM_STD_TIME       time    /**< The default \c time function to use. */
0097 #endif
0098 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
0099 #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS  EXIT_SUCCESS /**< The default exit value to use. */
0100 #endif
0101 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
0102 #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE  EXIT_FAILURE /**< The default exit value to use. */
0103 #endif
0104 #if defined(MBEDTLS_FS_IO)
0105 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
0106 #define MBEDTLS_PLATFORM_STD_NV_SEED_READ   mbedtls_platform_std_nv_seed_read
0107 #endif
0108 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE)
0109 #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE  mbedtls_platform_std_nv_seed_write
0110 #endif
0111 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE)
0112 #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE   "seedfile"
0113 #endif
0114 #endif /* MBEDTLS_FS_IO */
0115 #else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
0116 #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR)
0117 #include MBEDTLS_PLATFORM_STD_MEM_HDR
0118 #endif
0119 #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
0120
0121 /* Enable certain documented defines only when generating doxygen to avoid
0122  * an "unrecognized define" error. */
0123 #if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_CALLOC)
0124 #define MBEDTLS_PLATFORM_STD_CALLOC
0125 #endif
0126
0127 #if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_FREE)
0128 #define MBEDTLS_PLATFORM_STD_FREE
0129 #endif
0130
0131 /** \} name SECTION: Module settings */
0132
0133 /*
0134  * The function pointers for calloc and free.
0135  * Please see MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE
0136  * in mbedtls_config.h for more information about behaviour and requirements.
0137  */
0138 #if defined(MBEDTLS_PLATFORM_MEMORY)
0139 #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
0140     defined(MBEDTLS_PLATFORM_CALLOC_MACRO)
0141 #undef mbedtls_free
0142 #undef mbedtls_calloc
0143 #define mbedtls_free       MBEDTLS_PLATFORM_FREE_MACRO
0144 #define mbedtls_calloc     MBEDTLS_PLATFORM_CALLOC_MACRO
0145 #else
0146 /* For size_t */
0147 #include <stddef.h>
0148 extern void *mbedtls_calloc(size_t n, size_t size);
0149 extern void mbedtls_free(void *ptr);
0150
0151 /**
0152  * \brief               This function dynamically sets the memory-management
0153  *                      functions used by the library, during runtime.
0154  *
0155  * \param calloc_func   The \c calloc function implementation.
0156  * \param free_func     The \c free function implementation.
0157  *
0158  * \return              \c 0.
0159  */
0160 int mbedtls_platform_set_calloc_free(void *(*calloc_func)(size_t, size_t),
0161                                      void (*free_func)(void *));
0162 #endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */
0163 #else /* !MBEDTLS_PLATFORM_MEMORY */
0164 #undef mbedtls_free
0165 #undef mbedtls_calloc
0166 #define mbedtls_free       free
0167 #define mbedtls_calloc     calloc
0168 #endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */
0169
0170 /*
0171  * The function pointers for fprintf
0172  */
0173 #if defined(MBEDTLS_PLATFORM_FPRINTF_ALT)
0174 /* We need FILE * */
0175 #include <stdio.h>
0176 extern int (*mbedtls_fprintf)(FILE *stream, const char *format, ...);
0177
0178 /**
0179  * \brief                This function dynamically configures the fprintf
0180  *                       function that is called when the
0181  *                       mbedtls_fprintf() function is invoked by the library.
0182  *
0183  * \param fprintf_func   The \c fprintf function implementation.
0184  *
0185  * \return               \c 0.
0186  */
0187 int mbedtls_platform_set_fprintf(int (*fprintf_func)(FILE *stream, const char *,
0188                                                      ...));
0189 #else
0190 #undef mbedtls_fprintf
0191 #if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO)
0192 #define mbedtls_fprintf    MBEDTLS_PLATFORM_FPRINTF_MACRO
0193 #else
0194 #define mbedtls_fprintf    fprintf
0195 #endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */
0196 #endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */
0197
0198 /*
0199  * The function pointers for printf
0200  */
0201 #if defined(MBEDTLS_PLATFORM_PRINTF_ALT)
0202 extern int (*mbedtls_printf)(const char *format, ...);
0203
0204 /**
0205  * \brief               This function dynamically configures the snprintf
0206  *                      function that is called when the mbedtls_snprintf()
0207  *                      function is invoked by the library.
0208  *
0209  * \param printf_func   The \c printf function implementation.
0210  *
0211  * \return              \c 0 on success.
0212  */
0213 int mbedtls_platform_set_printf(int (*printf_func)(const char *, ...));
0214 #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
0215 #undef mbedtls_printf
0216 #if defined(MBEDTLS_PLATFORM_PRINTF_MACRO)
0217 #define mbedtls_printf     MBEDTLS_PLATFORM_PRINTF_MACRO
0218 #else
0219 #define mbedtls_printf     printf
0220 #endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */
0221 #endif /* MBEDTLS_PLATFORM_PRINTF_ALT */
0222
0223 /*
0224  * The function pointers for snprintf
0225  *
0226  * The snprintf implementation should conform to C99:
0227  * - it *must* always correctly zero-terminate the buffer
0228  *   (except when n == 0, then it must leave the buffer untouched)
0229  * - however it is acceptable to return -1 instead of the required length when
0230  *   the destination buffer is too short.
0231  */
0232 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
0233 /* For Windows (inc. MSYS2), we provide our own fixed implementation */
0234 int mbedtls_platform_win32_snprintf(char *s, size_t n, const char *fmt, ...);
0235 #endif
0236
0237 #if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT)
0238 extern int (*mbedtls_snprintf)(char *s, size_t n, const char *format, ...);
0239
0240 /**
0241  * \brief                 This function allows configuring a custom
0242  *                        \c snprintf function pointer.
0243  *
0244  * \param snprintf_func   The \c snprintf function implementation.
0245  *
0246  * \return                \c 0 on success.
0247  */
0248 int mbedtls_platform_set_snprintf(int (*snprintf_func)(char *s, size_t n,
0249                                                        const char *format, ...));
0250 #else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
0251 #undef mbedtls_snprintf
0252 #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
0253 #define mbedtls_snprintf   MBEDTLS_PLATFORM_SNPRINTF_MACRO
0254 #else
0255 #define mbedtls_snprintf   MBEDTLS_PLATFORM_STD_SNPRINTF
0256 #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
0257 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
0258
0259 /*
0260  * The function pointers for vsnprintf
0261  *
0262  * The vsnprintf implementation should conform to C99:
0263  * - it *must* always correctly zero-terminate the buffer
0264  *   (except when n == 0, then it must leave the buffer untouched)
0265  * - however it is acceptable to return -1 instead of the required length when
0266  *   the destination buffer is too short.
0267  */
0268 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
0269 #include <stdarg.h>
0270 /* For Older Windows (inc. MSYS2), we provide our own fixed implementation */
0271 int mbedtls_platform_win32_vsnprintf(char *s, size_t n, const char *fmt, va_list arg);
0272 #endif
0273
0274 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT)
0275 #include <stdarg.h>
0276 extern int (*mbedtls_vsnprintf)(char *s, size_t n, const char *format, va_list arg);
0277
0278 /**
0279  * \brief   Set your own snprintf function pointer
0280  *
0281  * \param   vsnprintf_func   The \c vsnprintf function implementation
0282  *
0283  * \return  \c 0
0284  */
0285 int mbedtls_platform_set_vsnprintf(int (*vsnprintf_func)(char *s, size_t n,
0286                                                          const char *format, va_list arg));
0287 #else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
0288 #undef mbedtls_vsnprintf
0289 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
0290 #define mbedtls_vsnprintf   MBEDTLS_PLATFORM_VSNPRINTF_MACRO
0291 #else
0292 #define mbedtls_vsnprintf   vsnprintf
0293 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */
0294 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
0295
0296 /*
0297  * The function pointers for setbuf
0298  */
0299 #if defined(MBEDTLS_PLATFORM_SETBUF_ALT)
0300 #include <stdio.h>
0301 /**
0302  * \brief                  Function pointer to call for `setbuf()` functionality
0303  *                         (changing the internal buffering on stdio calls).
0304  *
0305  * \note                   The library calls this function to disable
0306  *                         buffering when reading or writing sensitive data,
0307  *                         to avoid having extra copies of sensitive data
0308  *                         remaining in stdio buffers after the file is
0309  *                         closed. If this is not a concern, for example if
0310  *                         your platform's stdio doesn't have any buffering,
0311  *                         you can set mbedtls_setbuf to a function that
0312  *                         does nothing.
0313  *
0314  *                         The library always calls this function with
0315  *                         `buf` equal to `NULL`.
0316  */
0317 extern void (*mbedtls_setbuf)(FILE *stream, char *buf);
0318
0319 /**
0320  * \brief                  Dynamically configure the function that is called
0321  *                         when the mbedtls_setbuf() function is called by the
0322  *                         library.
0323  *
0324  * \param   setbuf_func   The \c setbuf function implementation
0325  *
0326  * \return                 \c 0
0327  */
0328 int mbedtls_platform_set_setbuf(void (*setbuf_func)(
0329                                     FILE *stream, char *buf));
0330 #else
0331 #undef mbedtls_setbuf
0332 #if defined(MBEDTLS_PLATFORM_SETBUF_MACRO)
0333 /**
0334  * \brief                  Macro defining the function for the library to
0335  *                         call for `setbuf` functionality (changing the
0336  *                         internal buffering on stdio calls).
0337  *
0338  * \note                   See extra comments on the mbedtls_setbuf() function
0339  *                         pointer above.
0340  *
0341  * \return                 \c 0 on success, negative on error.
0342  */
0343 #define mbedtls_setbuf    MBEDTLS_PLATFORM_SETBUF_MACRO
0344 #else
0345 #define mbedtls_setbuf    setbuf
0346 #endif /* MBEDTLS_PLATFORM_SETBUF_MACRO */
0347 #endif /* MBEDTLS_PLATFORM_SETBUF_ALT */
0348
0349 /*
0350  * The function pointers for exit
0351  */
0352 #if defined(MBEDTLS_PLATFORM_EXIT_ALT)
0353 extern void (*mbedtls_exit)(int status);
0354
0355 /**
0356  * \brief             This function dynamically configures the exit
0357  *                    function that is called when the mbedtls_exit()
0358  *                    function is invoked by the library.
0359  *
0360  * \param exit_func   The \c exit function implementation.
0361  *
0362  * \return            \c 0 on success.
0363  */
0364 int mbedtls_platform_set_exit(void (*exit_func)(int status));
0365 #else
0366 #undef mbedtls_exit
0367 #if defined(MBEDTLS_PLATFORM_EXIT_MACRO)
0368 #define mbedtls_exit   MBEDTLS_PLATFORM_EXIT_MACRO
0369 #else
0370 #define mbedtls_exit   exit
0371 #endif /* MBEDTLS_PLATFORM_EXIT_MACRO */
0372 #endif /* MBEDTLS_PLATFORM_EXIT_ALT */
0373
0374 /*
0375  * The default exit values
0376  */
0377 #if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
0378 #define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
0379 #else
0380 #define MBEDTLS_EXIT_SUCCESS 0
0381 #endif
0382 #if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
0383 #define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE
0384 #else
0385 #define MBEDTLS_EXIT_FAILURE 1
0386 #endif
0387
0388 /*
0389  * The function pointers for reading from and writing a seed file to
0390  * Non-Volatile storage (NV) in a platform-independent way
0391  *
0392  * Only enabled when the NV seed entropy source is enabled
0393  */
0394 #if defined(MBEDTLS_ENTROPY_NV_SEED)
0395 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO)
0396 /* Internal standard platform definitions */
0397 int mbedtls_platform_std_nv_seed_read(unsigned char *buf, size_t buf_len);
0398 int mbedtls_platform_std_nv_seed_write(unsigned char *buf, size_t buf_len);
0399 #endif
0400
0401 #if defined(MBEDTLS_PLATFORM_NV_SEED_ALT)
0402 extern int (*mbedtls_nv_seed_read)(unsigned char *buf, size_t buf_len);
0403 extern int (*mbedtls_nv_seed_write)(unsigned char *buf, size_t buf_len);
0404
0405 /**
0406  * \brief   This function allows configuring custom seed file writing and
0407  *          reading functions.
0408  *
0409  * \param   nv_seed_read_func   The seed reading function implementation.
0410  * \param   nv_seed_write_func  The seed writing function implementation.
0411  *
0412  * \return  \c 0 on success.
0413  */
0414 int mbedtls_platform_set_nv_seed(
0415     int (*nv_seed_read_func)(unsigned char *buf, size_t buf_len),
0416     int (*nv_seed_write_func)(unsigned char *buf, size_t buf_len)
0417     );
0418 #else
0419 #undef mbedtls_nv_seed_read
0420 #undef mbedtls_nv_seed_write
0421 #if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \
0422     defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO)
0423 #define mbedtls_nv_seed_read    MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
0424 #define mbedtls_nv_seed_write   MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
0425 #else
0426 #define mbedtls_nv_seed_read    mbedtls_platform_std_nv_seed_read
0427 #define mbedtls_nv_seed_write   mbedtls_platform_std_nv_seed_write
0428 #endif
0429 #endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */
0430 #endif /* MBEDTLS_ENTROPY_NV_SEED */
0431
0432 #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
0433
0434 /**
0435  * \brief   The platform context structure.
0436  *
0437  * \note    This structure may be used to assist platform-specific
0438  *          setup or teardown operations.
0439  */
0440 typedef struct mbedtls_platform_context {
0441     char MBEDTLS_PRIVATE(dummy); /**< A placeholder member, as empty structs are not portable. */
0442 }
0443 mbedtls_platform_context;
0444
0445 #else
0446 #include "platform_alt.h"
0447 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
0448
0449 /**
0450  * \brief   This function performs any platform-specific initialization
0451  *          operations.
0452  *
0453  * \note    This function should be called before any other library functions.
0454  *
0455  *          Its implementation is platform-specific, and unless
0456  *          platform-specific code is provided, it does nothing.
0457  *
0458  * \note    The usage and necessity of this function is dependent on the platform.
0459  *
0460  * \param   ctx     The platform context.
0461  *
0462  * \return  \c 0 on success.
0463  */
0464 int mbedtls_platform_setup(mbedtls_platform_context *ctx);
0465 /**
0466  * \brief   This function performs any platform teardown operations.
0467  *
0468  * \note    This function should be called after every other Mbed TLS module
0469  *          has been correctly freed using the appropriate free function.
0470  *
0471  *          Its implementation is platform-specific, and unless
0472  *          platform-specific code is provided, it does nothing.
0473  *
0474  * \note    The usage and necessity of this function is dependent on the platform.
0475  *
0476  * \param   ctx     The platform context.
0477  *
0478  */
0479 void mbedtls_platform_teardown(mbedtls_platform_context *ctx);
0480
0481 #ifdef __cplusplus
0482 }
0483 #endif
0484
0485 #endif /* platform.h */