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