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 25 * 26 * Licensed under the Apache License, Version 2.0 (the "License"); you may 27 * not use this file except in compliance with the License. 28 * You may obtain a copy of the License at 29 * 30 * http://www.apache.org/licenses/LICENSE-2.0 31 * 32 * Unless required by applicable law or agreed to in writing, software 33 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 34 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 35 * See the License for the specific language governing permissions and 36 * limitations under the License. 37 */ 38 #ifndef MBEDTLS_PLATFORM_H 39 #define MBEDTLS_PLATFORM_H 40 #include "mbedtls/private_access.h" 41 42 #include "mbedtls/build_info.h" 43 44 #if defined(MBEDTLS_HAVE_TIME) 45 #include "mbedtls/platform_time.h" 46 #endif 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * \name SECTION: Module settings 54 * 55 * The configuration options you can set for this module are in this section. 56 * Either change them in mbedtls_config.h or define them on the compiler command line. 57 * \{ 58 */ 59 60 /* The older Microsoft Windows common runtime provides non-conforming 61 * implementations of some standard library functions, including snprintf 62 * and vsnprintf. This affects MSVC and MinGW builds. 63 */ 64 #if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900) 65 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF 66 #define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF 67 #endif 68 69 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) 70 #include <stdio.h> 71 #include <stdlib.h> 72 #if defined(MBEDTLS_HAVE_TIME) 73 #include <time.h> 74 #endif 75 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF) 76 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF) 77 #define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */ 78 #else 79 #define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */ 80 #endif 81 #endif 82 #if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF) 83 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF) 84 #define MBEDTLS_PLATFORM_STD_VSNPRINTF mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use. */ 85 #else 86 #define MBEDTLS_PLATFORM_STD_VSNPRINTF vsnprintf /**< The default \c vsnprintf function to use. */ 87 #endif 88 #endif 89 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF) 90 #define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */ 91 #endif 92 #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF) 93 #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */ 94 #endif 95 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC) 96 #define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */ 97 #endif 98 #if !defined(MBEDTLS_PLATFORM_STD_FREE) 99 #define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */ 100 #endif 101 #if !defined(MBEDTLS_PLATFORM_STD_SETBUF) 102 #define MBEDTLS_PLATFORM_STD_SETBUF setbuf /**< The default \c setbuf function to use. */ 103 #endif 104 #if !defined(MBEDTLS_PLATFORM_STD_EXIT) 105 #define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */ 106 #endif 107 #if !defined(MBEDTLS_PLATFORM_STD_TIME) 108 #define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */ 109 #endif 110 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS) 111 #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */ 112 #endif 113 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE) 114 #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */ 115 #endif 116 #if defined(MBEDTLS_FS_IO) 117 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ) 118 #define MBEDTLS_PLATFORM_STD_NV_SEED_READ mbedtls_platform_std_nv_seed_read 119 #endif 120 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE) 121 #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE mbedtls_platform_std_nv_seed_write 122 #endif 123 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE) 124 #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE "seedfile" 125 #endif 126 #endif /* MBEDTLS_FS_IO */ 127 #else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */ 128 #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR) 129 #include MBEDTLS_PLATFORM_STD_MEM_HDR 130 #endif 131 #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */ 132 133 134 /** \} name SECTION: Module settings */ 135 136 /* 137 * The function pointers for calloc and free. 138 */ 139 #if defined(MBEDTLS_PLATFORM_MEMORY) 140 #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \ 141 defined(MBEDTLS_PLATFORM_CALLOC_MACRO) 142 #define mbedtls_free MBEDTLS_PLATFORM_FREE_MACRO 143 #define mbedtls_calloc MBEDTLS_PLATFORM_CALLOC_MACRO 144 #else 145 /* For size_t */ 146 #include <stddef.h> 147 extern void *mbedtls_calloc( size_t n, size_t size ); 148 extern void mbedtls_free( void *ptr ); 149 150 /** 151 * \brief This function dynamically sets the memory-management 152 * functions used by the library, during runtime. 153 * 154 * \param calloc_func The \c calloc function implementation. 155 * \param free_func The \c free function implementation. 156 * 157 * \return \c 0. 158 */ 159 int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ), 160 void (*free_func)( void * ) ); 161 #endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */ 162 #else /* !MBEDTLS_PLATFORM_MEMORY */ 163 #define mbedtls_free free 164 #define mbedtls_calloc calloc 165 #endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */ 166 167 /* 168 * The function pointers for fprintf 169 */ 170 #if defined(MBEDTLS_PLATFORM_FPRINTF_ALT) 171 /* We need FILE * */ 172 #include <stdio.h> 173 extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... ); 174 175 /** 176 * \brief This function dynamically configures the fprintf 177 * function that is called when the 178 * mbedtls_fprintf() function is invoked by the library. 179 * 180 * \param fprintf_func The \c fprintf function implementation. 181 * 182 * \return \c 0. 183 */ 184 int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *, 185 ... ) ); 186 #else 187 #if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO) 188 #define mbedtls_fprintf MBEDTLS_PLATFORM_FPRINTF_MACRO 189 #else 190 #define mbedtls_fprintf fprintf 191 #endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */ 192 #endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */ 193 194 /* 195 * The function pointers for printf 196 */ 197 #if defined(MBEDTLS_PLATFORM_PRINTF_ALT) 198 extern int (*mbedtls_printf)( const char *format, ... ); 199 200 /** 201 * \brief This function dynamically configures the snprintf 202 * function that is called when the mbedtls_snprintf() 203 * function is invoked by the library. 204 * 205 * \param printf_func The \c printf function implementation. 206 * 207 * \return \c 0 on success. 208 */ 209 int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) ); 210 #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */ 211 #if defined(MBEDTLS_PLATFORM_PRINTF_MACRO) 212 #define mbedtls_printf MBEDTLS_PLATFORM_PRINTF_MACRO 213 #else 214 #define mbedtls_printf printf 215 #endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */ 216 #endif /* MBEDTLS_PLATFORM_PRINTF_ALT */ 217 218 /* 219 * The function pointers for snprintf 220 * 221 * The snprintf implementation should conform to C99: 222 * - it *must* always correctly zero-terminate the buffer 223 * (except when n == 0, then it must leave the buffer untouched) 224 * - however it is acceptable to return -1 instead of the required length when 225 * the destination buffer is too short. 226 */ 227 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF) 228 /* For Windows (inc. MSYS2), we provide our own fixed implementation */ 229 int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... ); 230 #endif 231 232 #if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT) 233 extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... ); 234 235 /** 236 * \brief This function allows configuring a custom 237 * \c snprintf function pointer. 238 * 239 * \param snprintf_func The \c snprintf function implementation. 240 * 241 * \return \c 0 on success. 242 */ 243 int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, 244 const char * format, ... ) ); 245 #else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */ 246 #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO) 247 #define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO 248 #else 249 #define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF 250 #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */ 251 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */ 252 253 /* 254 * The function pointers for vsnprintf 255 * 256 * The vsnprintf implementation should conform to C99: 257 * - it *must* always correctly zero-terminate the buffer 258 * (except when n == 0, then it must leave the buffer untouched) 259 * - however it is acceptable to return -1 instead of the required length when 260 * the destination buffer is too short. 261 */ 262 #if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF) 263 #include <stdarg.h> 264 /* For Older Windows (inc. MSYS2), we provide our own fixed implementation */ 265 int mbedtls_platform_win32_vsnprintf( char *s, size_t n, const char *fmt, va_list arg ); 266 #endif 267 268 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) 269 #include <stdarg.h> 270 extern int (*mbedtls_vsnprintf)( char * s, size_t n, const char * format, va_list arg ); 271 272 /** 273 * \brief Set your own snprintf function pointer 274 * 275 * \param vsnprintf_func The \c vsnprintf function implementation 276 * 277 * \return \c 0 278 */ 279 int mbedtls_platform_set_vsnprintf( int (*vsnprintf_func)( char * s, size_t n, 280 const char * format, va_list arg ) ); 281 #else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */ 282 #if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO) 283 #define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO 284 #else 285 #define mbedtls_vsnprintf vsnprintf 286 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */ 287 #endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */ 288 289 /* 290 * The function pointers for setbuf 291 */ 292 #if defined(MBEDTLS_PLATFORM_SETBUF_ALT) 293 #include <stdio.h> 294 /** 295 * \brief Function pointer to call for `setbuf()` functionality 296 * (changing the internal buffering on stdio calls). 297 * 298 * \note The library calls this function to disable 299 * buffering when reading or writing sensitive data, 300 * to avoid having extra copies of sensitive data 301 * remaining in stdio buffers after the file is 302 * closed. If this is not a concern, for example if 303 * your platform's stdio doesn't have any buffering, 304 * you can set mbedtls_setbuf to a function that 305 * does nothing. 306 * 307 * The library always calls this function with 308 * `buf` equal to `NULL`. 309 */ 310 extern void (*mbedtls_setbuf)( FILE *stream, char *buf ); 311 312 /** 313 * \brief Dynamically configure the function that is called 314 * when the mbedtls_setbuf() function is called by the 315 * library. 316 * 317 * \param setbuf_func The \c setbuf function implementation 318 * 319 * \return \c 0 320 */ 321 int mbedtls_platform_set_setbuf( void (*setbuf_func)( 322 FILE *stream, char *buf ) ); 323 #elif defined(MBEDTLS_PLATFORM_SETBUF_MACRO) 324 /** 325 * \brief Macro defining the function for the library to 326 * call for `setbuf` functionality (changing the 327 * internal buffering on stdio calls). 328 * 329 * \note See extra comments on the mbedtls_setbuf() function 330 * pointer above. 331 * 332 * \return \c 0 on success, negative on error. 333 */ 334 #define mbedtls_setbuf MBEDTLS_PLATFORM_SETBUF_MACRO 335 #else 336 #define mbedtls_setbuf setbuf 337 #endif /* MBEDTLS_PLATFORM_SETBUF_ALT / MBEDTLS_PLATFORM_SETBUF_MACRO */ 338 339 /* 340 * The function pointers for exit 341 */ 342 #if defined(MBEDTLS_PLATFORM_EXIT_ALT) 343 extern void (*mbedtls_exit)( int status ); 344 345 /** 346 * \brief This function dynamically configures the exit 347 * function that is called when the mbedtls_exit() 348 * function is invoked by the library. 349 * 350 * \param exit_func The \c exit function implementation. 351 * 352 * \return \c 0 on success. 353 */ 354 int mbedtls_platform_set_exit( void (*exit_func)( int status ) ); 355 #else 356 #if defined(MBEDTLS_PLATFORM_EXIT_MACRO) 357 #define mbedtls_exit MBEDTLS_PLATFORM_EXIT_MACRO 358 #else 359 #define mbedtls_exit exit 360 #endif /* MBEDTLS_PLATFORM_EXIT_MACRO */ 361 #endif /* MBEDTLS_PLATFORM_EXIT_ALT */ 362 363 /* 364 * The default exit values 365 */ 366 #if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS) 367 #define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS 368 #else 369 #define MBEDTLS_EXIT_SUCCESS 0 370 #endif 371 #if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE) 372 #define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE 373 #else 374 #define MBEDTLS_EXIT_FAILURE 1 375 #endif 376 377 /* 378 * The function pointers for reading from and writing a seed file to 379 * Non-Volatile storage (NV) in a platform-independent way 380 * 381 * Only enabled when the NV seed entropy source is enabled 382 */ 383 #if defined(MBEDTLS_ENTROPY_NV_SEED) 384 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO) 385 /* Internal standard platform definitions */ 386 int mbedtls_platform_std_nv_seed_read( unsigned char *buf, size_t buf_len ); 387 int mbedtls_platform_std_nv_seed_write( unsigned char *buf, size_t buf_len ); 388 #endif 389 390 #if defined(MBEDTLS_PLATFORM_NV_SEED_ALT) 391 extern int (*mbedtls_nv_seed_read)( unsigned char *buf, size_t buf_len ); 392 extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len ); 393 394 /** 395 * \brief This function allows configuring custom seed file writing and 396 * reading functions. 397 * 398 * \param nv_seed_read_func The seed reading function implementation. 399 * \param nv_seed_write_func The seed writing function implementation. 400 * 401 * \return \c 0 on success. 402 */ 403 int mbedtls_platform_set_nv_seed( 404 int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ), 405 int (*nv_seed_write_func)( unsigned char *buf, size_t buf_len ) 406 ); 407 #else 408 #if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \ 409 defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO) 410 #define mbedtls_nv_seed_read MBEDTLS_PLATFORM_NV_SEED_READ_MACRO 411 #define mbedtls_nv_seed_write MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO 412 #else 413 #define mbedtls_nv_seed_read mbedtls_platform_std_nv_seed_read 414 #define mbedtls_nv_seed_write mbedtls_platform_std_nv_seed_write 415 #endif 416 #endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */ 417 #endif /* MBEDTLS_ENTROPY_NV_SEED */ 418 419 #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT) 420 421 /** 422 * \brief The platform context structure. 423 * 424 * \note This structure may be used to assist platform-specific 425 * setup or teardown operations. 426 */ 427 typedef struct mbedtls_platform_context 428 { 429 char MBEDTLS_PRIVATE(dummy); /**< A placeholder member, as empty structs are not portable. */ 430 } 431 mbedtls_platform_context; 432 433 #else 434 #include "platform_alt.h" 435 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ 436 437 /** 438 * \brief This function performs any platform-specific initialization 439 * operations. 440 * 441 * \note This function should be called before any other library functions. 442 * 443 * Its implementation is platform-specific, and unless 444 * platform-specific code is provided, it does nothing. 445 * 446 * \note The usage and necessity of this function is dependent on the platform. 447 * 448 * \param ctx The platform context. 449 * 450 * \return \c 0 on success. 451 */ 452 int mbedtls_platform_setup( mbedtls_platform_context *ctx ); 453 /** 454 * \brief This function performs any platform teardown operations. 455 * 456 * \note This function should be called after every other Mbed TLS module 457 * has been correctly freed using the appropriate free function. 458 * 459 * Its implementation is platform-specific, and unless 460 * platform-specific code is provided, it does nothing. 461 * 462 * \note The usage and necessity of this function is dependent on the platform. 463 * 464 * \param ctx The platform context. 465 * 466 */ 467 void mbedtls_platform_teardown( mbedtls_platform_context *ctx ); 468 469 #ifdef __cplusplus 470 } 471 #endif 472 473 #endif /* platform.h */ 474
