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