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