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