common/mbedtls/platform.h

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