git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/platform.h

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