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