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