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