1 /** 2 * \file platform.h 3 * 4 * \brief This file contains the definitions and functions of the 5 * Mbed TLS platform abstraction layer. 6 * 7 * The platform abstraction layer removes the need for the library 8 * to directly link to standard C library functions or operating 9 * system services, making the library easier to port and embed. 10 * Application developers and users of the library can provide their own 11 * implementations of these functions, or implementations specific to 12 * their platform, which can be statically linked to the library or 13 * dynamically configured at runtime. 14 * 15 * When all compilation options related to platform abstraction are 16 * disabled, this header just defines `mbedtls_xxx` function names 17 * as aliases to the standard `xxx` function. 18 * 19 * Most modules in the library and example programs are expected to 20 * include this header. 21 */ 22 /* 23 * Copyright The Mbed TLS Contributors 24 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 25 */ 26 #ifndef MBEDTLS_PLATFORM_H 27 #define MBEDTLS_PLATFORM_H 28 29 #if !defined(MBEDTLS_CONFIG_FILE) 30 #include "mbedtls/config.h" 31 #else 32 #include MBEDTLS_CONFIG_FILE 33 #endif 34 35 #if defined(MBEDTLS_HAVE_TIME) 36 #include "mbedtls/platform_time.h" 37 #endif 38 39 /** Hardware accelerator failed */ 40 #define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED -0x0070 41 /** The requested feature is not supported by the platform */ 42 #define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * \name SECTION: Module settings 50 * 51 * The configuration options you can set for this module are in this section. 52 * Either change them in config.h or define them on the compiler command line. 53 * \{ 54 */ 55 56 /* The older Microsoft Windows common runtime provides non-conforming 57 * implementations of some standard library functions, including snprintf 58 * and vsnprintf. This affects MSVC and MinGW builds. 59 */ 60 #if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900) 61 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF 62 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF 63 #endif 64 65 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) 66 #include <stdio.h> 67 #include <stdlib.h> 68 #if defined(MBEDTLS_HAVE_TIME) 69 #include <time.h> 70 #endif 71 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF) 72 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF) 73 #define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */ 74 #else 75 #define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */ 76 #endif 77 #endif 78 #if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF) 79 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF) 80 #define MBEDTLS_PLATFORM_STD_VSNPRINTF mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use. */ 81 #else 82 #define MBEDTLS_PLATFORM_STD_VSNPRINTF vsnprintf /**< The default \c vsnprintf function to use. */ 83 #endif 84 #endif 85 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF) 86 #define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */ 87 #endif 88 #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF) 89 #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */ 90 #endif 91 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC) 92 #define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */ 93 #endif 94 #if !defined(MBEDTLS_PLATFORM_STD_FREE) 95 #define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */ 96 #endif 97 #if !defined(MBEDTLS_PLATFORM_STD_EXIT) 98 #define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */ 99 #endif 100 #if !defined(MBEDTLS_PLATFORM_STD_TIME) 101 #define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */ 102 #endif 103 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS) 104 #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */ 105 #endif 106 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE) 107 #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */ 108 #endif 109 #if defined(MBEDTLS_FS_IO) 110 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ) 111 #define MBEDTLS_PLATFORM_STD_NV_SEED_READ mbedtls_platform_std_nv_seed_read 112 #endif 113 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE) 114 #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE mbedtls_platform_std_nv_seed_write 115 #endif 116 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE) 117 #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE "seedfile" 118 #endif 119 #endif /* MBEDTLS_FS_IO */ 120 #else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */ 121 #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR) 122 #include MBEDTLS_PLATFORM_STD_MEM_HDR 123 #endif 124 #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */ 125 126 /* Enable certain documented defines only when generating doxygen to avoid 127 * an "unrecognized define" error. */ 128 #if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_CALLOC) 129 #define MBEDTLS_PLATFORM_STD_CALLOC 130 #endif 131 132 #if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_FREE) 133 #define MBEDTLS_PLATFORM_STD_FREE 134 #endif 135 136 /** \} name SECTION: Module settings */ 137 138 /* 139 * The function pointers for calloc and free. 140 * Please see MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE 141 * in mbedtls_config.h for more information about behaviour and requirements. 142 */ 143 #if defined(MBEDTLS_PLATFORM_MEMORY) 144 #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \ 145 defined(MBEDTLS_PLATFORM_CALLOC_MACRO) 146 #undef mbedtls_free 147 #undef mbedtls_calloc 148 #define mbedtls_free MBEDTLS_PLATFORM_FREE_MACRO 149 #define mbedtls_calloc MBEDTLS_PLATFORM_CALLOC_MACRO 150 #else 151 /* For size_t */ 152 #include <stddef.h> 153 extern void *mbedtls_calloc(size_t n, size_t size); 154 extern void mbedtls_free(void *ptr); 155 156 /** 157 * \brief This function dynamically sets the memory-management 158 * functions used by the library, during runtime. 159 * 160 * \param calloc_func The \c calloc function implementation. 161 * \param free_func The \c free function implementation. 162 * 163 * \return \c 0. 164 */ 165 int mbedtls_platform_set_calloc_free(void *(*calloc_func)(size_t, size_t), 166 void (*free_func)(void *)); 167 #endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */ 168 #else /* !MBEDTLS_PLATFORM_MEMORY */ 169 #undef mbedtls_free 170 #undef mbedtls_calloc 171 #define mbedtls_free free 172 #define mbedtls_calloc calloc 173 #endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */ 174 175 /* 176 * The function pointers for fprintf 177 */ 178 #if defined(MBEDTLS_PLATFORM_FPRINTF_ALT) 179 /* We need FILE * */ 180 #include <stdio.h> 181 extern int (*mbedtls_fprintf)(FILE *stream, const char *format, ...); 182 183 /** 184 * \brief This function dynamically configures the fprintf 185 * function that is called when the 186 * mbedtls_fprintf() function is invoked by the library. 187 * 188 * \param fprintf_func The \c fprintf function implementation. 189 * 190 * \return \c 0. 191 */ 192 int mbedtls_platform_set_fprintf(int (*fprintf_func)(FILE *stream, const char *, 193 ...)); 194 #else 195 #undef mbedtls_fprintf 196 #if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO) 197 #define mbedtls_fprintf MBEDTLS_PLATFORM_FPRINTF_MACRO 198 #else 199 #define mbedtls_fprintf fprintf 200 #endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */ 201 #endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */ 202 203 /* 204 * The function pointers for printf 205 */ 206 #if defined(MBEDTLS_PLATFORM_PRINTF_ALT) 207 extern int (*mbedtls_printf)(const char *format, ...); 208 209 /** 210 * \brief This function dynamically configures the snprintf 211 * function that is called when the mbedtls_snprintf() 212 * function is invoked by the library. 213 * 214 * \param printf_func The \c printf function implementation. 215 * 216 * \return \c 0 on success. 217 */ 218 int mbedtls_platform_set_printf(int (*printf_func)(const char *, ...)); 219 #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */ 220 #undef mbedtls_printf 221 #if defined(MBEDTLS_PLATFORM_PRINTF_MACRO) 222 #define mbedtls_printf MBEDTLS_PLATFORM_PRINTF_MACRO 223 #else 224 #define mbedtls_printf printf 225 #endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */ 226 #endif /* MBEDTLS_PLATFORM_PRINTF_ALT */ 227 228 /* 229 * The function pointers for snprintf 230 * 231 * The snprintf implementation should conform to C99: 232 * - it *must* always correctly zero-terminate the buffer 233 * (except when n == 0, then it must leave the buffer untouched) 234 * - however it is acceptable to return -1 instead of the required length when 235 * the destination buffer is too short. 236 */ 237 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF) 238 /* For Windows (inc. MSYS2), we provide our own fixed implementation */ 239 int mbedtls_platform_win32_snprintf(char *s, size_t n, const char *fmt, ...); 240 #endif 241 242 #if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT) 243 extern int (*mbedtls_snprintf)(char *s, size_t n, const char *format, ...); 244 245 /** 246 * \brief This function allows configuring a custom 247 * \c snprintf function pointer. 248 * 249 * \param snprintf_func The \c snprintf function implementation. 250 * 251 * \return \c 0 on success. 252 */ 253 int mbedtls_platform_set_snprintf(int (*snprintf_func)(char *s, size_t n, 254 const char *format, ...)); 255 #else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */ 256 #undef mbedtls_snprintf 257 #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO) 258 #define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO 259 #else 260 #define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF 261 #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */ 262 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */ 263 264 /* 265 * The function pointers for vsnprintf 266 * 267 * The vsnprintf implementation should conform to C99: 268 * - it *must* always correctly zero-terminate the buffer 269 * (except when n == 0, then it must leave the buffer untouched) 270 * - however it is acceptable to return -1 instead of the required length when 271 * the destination buffer is too short. 272 */ 273 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF) 274 #include <stdarg.h> 275 /* For Older Windows (inc. MSYS2), we provide our own fixed implementation */ 276 int mbedtls_platform_win32_vsnprintf(char *s, size_t n, const char *fmt, va_list arg); 277 #endif 278 279 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) 280 #include <stdarg.h> 281 extern int (*mbedtls_vsnprintf)(char *s, size_t n, const char *format, va_list arg); 282 283 /** 284 * \brief Set your own snprintf function pointer 285 * 286 * \param vsnprintf_func The \c vsnprintf function implementation 287 * 288 * \return \c 0 289 */ 290 int mbedtls_platform_set_vsnprintf(int (*vsnprintf_func)(char *s, size_t n, 291 const char *format, va_list arg)); 292 #else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */ 293 #undef mbedtls_vsnprintf 294 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO) 295 #define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO 296 #else 297 #define mbedtls_vsnprintf vsnprintf 298 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */ 299 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */ 300 301 /* 302 * The function pointers for exit 303 */ 304 #if defined(MBEDTLS_PLATFORM_EXIT_ALT) 305 extern void (*mbedtls_exit)(int status); 306 307 /** 308 * \brief This function dynamically configures the exit 309 * function that is called when the mbedtls_exit() 310 * function is invoked by the library. 311 * 312 * \param exit_func The \c exit function implementation. 313 * 314 * \return \c 0 on success. 315 */ 316 int mbedtls_platform_set_exit(void (*exit_func)(int status)); 317 #else 318 #undef mbedtls_exit 319 #if defined(MBEDTLS_PLATFORM_EXIT_MACRO) 320 #define mbedtls_exit MBEDTLS_PLATFORM_EXIT_MACRO 321 #else 322 #define mbedtls_exit exit 323 #endif /* MBEDTLS_PLATFORM_EXIT_MACRO */ 324 #endif /* MBEDTLS_PLATFORM_EXIT_ALT */ 325 326 /* 327 * The default exit values 328 */ 329 #if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS) 330 #define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS 331 #else 332 #define MBEDTLS_EXIT_SUCCESS 0 333 #endif 334 #if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE) 335 #define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE 336 #else 337 #define MBEDTLS_EXIT_FAILURE 1 338 #endif 339 340 /* 341 * The function pointers for reading from and writing a seed file to 342 * Non-Volatile storage (NV) in a platform-independent way 343 * 344 * Only enabled when the NV seed entropy source is enabled 345 */ 346 #if defined(MBEDTLS_ENTROPY_NV_SEED) 347 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO) 348 /* Internal standard platform definitions */ 349 int mbedtls_platform_std_nv_seed_read(unsigned char *buf, size_t buf_len); 350 int mbedtls_platform_std_nv_seed_write(unsigned char *buf, size_t buf_len); 351 #endif 352 353 #if defined(MBEDTLS_PLATFORM_NV_SEED_ALT) 354 extern int (*mbedtls_nv_seed_read)(unsigned char *buf, size_t buf_len); 355 extern int (*mbedtls_nv_seed_write)(unsigned char *buf, size_t buf_len); 356 357 /** 358 * \brief This function allows configuring custom seed file writing and 359 * reading functions. 360 * 361 * \param nv_seed_read_func The seed reading function implementation. 362 * \param nv_seed_write_func The seed writing function implementation. 363 * 364 * \return \c 0 on success. 365 */ 366 int mbedtls_platform_set_nv_seed( 367 int (*nv_seed_read_func)(unsigned char *buf, size_t buf_len), 368 int (*nv_seed_write_func)(unsigned char *buf, size_t buf_len) 369 ); 370 #else 371 #undef mbedtls_nv_seed_read 372 #undef mbedtls_nv_seed_write 373 #if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \ 374 defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO) 375 #define mbedtls_nv_seed_read MBEDTLS_PLATFORM_NV_SEED_READ_MACRO 376 #define mbedtls_nv_seed_write MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO 377 #else 378 #define mbedtls_nv_seed_read mbedtls_platform_std_nv_seed_read 379 #define mbedtls_nv_seed_write mbedtls_platform_std_nv_seed_write 380 #endif 381 #endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */ 382 #endif /* MBEDTLS_ENTROPY_NV_SEED */ 383 384 #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT) 385 386 /** 387 * \brief The platform context structure. 388 * 389 * \note This structure may be used to assist platform-specific 390 * setup or teardown operations. 391 */ 392 typedef struct mbedtls_platform_context { 393 char dummy; /**< A placeholder member, as empty structs are not portable. */ 394 } 395 mbedtls_platform_context; 396 397 #else 398 #include "platform_alt.h" 399 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ 400 401 /** 402 * \brief This function performs any platform-specific initialization 403 * operations. 404 * 405 * \note This function should be called before any other library functions. 406 * 407 * Its implementation is platform-specific, and unless 408 * platform-specific code is provided, it does nothing. 409 * 410 * \note The usage and necessity of this function is dependent on the platform. 411 * 412 * \param ctx The platform context. 413 * 414 * \return \c 0 on success. 415 */ 416 int mbedtls_platform_setup(mbedtls_platform_context *ctx); 417 /** 418 * \brief This function performs any platform teardown operations. 419 * 420 * \note This function should be called after every other Mbed TLS module 421 * has been correctly freed using the appropriate free function. 422 * 423 * Its implementation is platform-specific, and unless 424 * platform-specific code is provided, it does nothing. 425 * 426 * \note The usage and necessity of this function is dependent on the platform. 427 * 428 * \param ctx The platform context. 429 * 430 */ 431 void mbedtls_platform_teardown(mbedtls_platform_context *ctx); 432 433 #ifdef __cplusplus 434 } 435 #endif 436 437 #endif /* platform.h */ 438