platform.h

00001 /**
00002  * \file platform.h
00003  *
00004  * \brief The Mbed TLS platform abstraction layer.
00005  */
00006 /*
00007  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of Mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_PLATFORM_H
00025 #define MBEDTLS_PLATFORM_H
00026 
00027 #if !defined(MBEDTLS_CONFIG_FILE)
00028 #include "config.h"
00029 #else
00030 #include MBEDTLS_CONFIG_FILE
00031 #endif
00032 
00033 #if defined(MBEDTLS_HAVE_TIME)
00034 #include "mbedtls/platform_time.h"
00035 #endif
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 /**
00042  * \name SECTION: Module settings
00043  *
00044  * The configuration options you can set for this module are in this section.
00045  * Either change them in config.h or define them on the compiler command line.
00046  * \{
00047  */
00048 
00049 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
00050 #include <stdio.h>
00051 #include <stdlib.h>
00052 #include <time.h>
00053 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
00054 #if defined(_WIN32)
00055 #define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use.  */
00056 #else
00057 #define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf /**< The default \c snprintf function to use.  */
00058 #endif
00059 #endif
00060 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
00061 #define MBEDTLS_PLATFORM_STD_PRINTF   printf /**< The default \c printf function to use. */
00062 #endif
00063 #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
00064 #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
00065 #endif
00066 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
00067 #define MBEDTLS_PLATFORM_STD_CALLOC   calloc /**< The default \c calloc function to use. */
00068 #endif
00069 #if !defined(MBEDTLS_PLATFORM_STD_FREE)
00070 #define MBEDTLS_PLATFORM_STD_FREE       free /**< The default \c free function to use. */
00071 #endif
00072 #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
00073 #define MBEDTLS_PLATFORM_STD_EXIT      exit /**< The default \c exit function to use. */
00074 #endif
00075 #if !defined(MBEDTLS_PLATFORM_STD_TIME)
00076 #define MBEDTLS_PLATFORM_STD_TIME       time    /**< The default \c time function to use. */
00077 #endif
00078 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
00079 #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS  EXIT_SUCCESS /**< The default exit value to use. */
00080 #endif
00081 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
00082 #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE  EXIT_FAILURE /**< The default exit value to use. */
00083 #endif
00084 #if defined(MBEDTLS_FS_IO)
00085 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
00086 #define MBEDTLS_PLATFORM_STD_NV_SEED_READ   mbedtls_platform_std_nv_seed_read
00087 #endif
00088 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE)
00089 #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE  mbedtls_platform_std_nv_seed_write
00090 #endif
00091 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE)
00092 #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE   "seedfile"
00093 #endif
00094 #endif /* MBEDTLS_FS_IO */
00095 #else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
00096 #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR)
00097 #include MBEDTLS_PLATFORM_STD_MEM_HDR
00098 #endif
00099 #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
00100 
00101 
00102 /* \} name SECTION: Module settings */
00103 
00104 /*
00105  * The function pointers for calloc and free
00106  */
00107 #if defined(MBEDTLS_PLATFORM_MEMORY)
00108 #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
00109     defined(MBEDTLS_PLATFORM_CALLOC_MACRO)
00110 #define mbedtls_free       MBEDTLS_PLATFORM_FREE_MACRO
00111 #define mbedtls_calloc     MBEDTLS_PLATFORM_CALLOC_MACRO
00112 #else
00113 /* For size_t */
00114 #include <stddef.h>
00115 extern void * (*mbedtls_calloc)( size_t n, size_t size );
00116 extern void (*mbedtls_free)( void *ptr );
00117 
00118 /**
00119  * \brief   This function allows configuring custom memory-management functions.
00120  *
00121  * \param calloc_func   The \c calloc function implementation.
00122  * \param free_func     The \c free function implementation.
00123  *
00124  * \return              \c 0.
00125  */
00126 int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
00127                               void (*free_func)( void * ) );
00128 #endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */
00129 #else /* !MBEDTLS_PLATFORM_MEMORY */
00130 #define mbedtls_free       free
00131 #define mbedtls_calloc     calloc
00132 #endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */
00133 
00134 /*
00135  * The function pointers for fprintf
00136  */
00137 #if defined(MBEDTLS_PLATFORM_FPRINTF_ALT)
00138 /* We need FILE * */
00139 #include <stdio.h>
00140 extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
00141 
00142 /**
00143  * \brief   This function allows configuring a custom \p fprintf function pointer.
00144  *
00145  * \param fprintf_func   The \c fprintf function implementation.
00146  *
00147  * \return               \c 0.
00148  */
00149 int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *,
00150                                                ... ) );
00151 #else
00152 #if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO)
00153 #define mbedtls_fprintf    MBEDTLS_PLATFORM_FPRINTF_MACRO
00154 #else
00155 #define mbedtls_fprintf    fprintf
00156 #endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */
00157 #endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */
00158 
00159 /*
00160  * The function pointers for printf
00161  */
00162 #if defined(MBEDTLS_PLATFORM_PRINTF_ALT)
00163 extern int (*mbedtls_printf)( const char *format, ... );
00164 
00165 /**
00166  * \brief    This function allows configuring a custom \c printf function
00167  *           pointer.
00168  *
00169  * \param printf_func   The \c printf function implementation.
00170  *
00171  * \return              \c 0 on success.
00172  */
00173 int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) );
00174 #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
00175 #if defined(MBEDTLS_PLATFORM_PRINTF_MACRO)
00176 #define mbedtls_printf     MBEDTLS_PLATFORM_PRINTF_MACRO
00177 #else
00178 #define mbedtls_printf     printf
00179 #endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */
00180 #endif /* MBEDTLS_PLATFORM_PRINTF_ALT */
00181 
00182 /*
00183  * The function pointers for snprintf
00184  *
00185  * The snprintf implementation should conform to C99:
00186  * - it *must* always correctly zero-terminate the buffer
00187  *   (except when n == 0, then it must leave the buffer untouched)
00188  * - however it is acceptable to return -1 instead of the required length when
00189  *   the destination buffer is too short.
00190  */
00191 #if defined(_WIN32)
00192 /* For Windows (inc. MSYS2), we provide our own fixed implementation */
00193 int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
00194 #endif
00195 
00196 #if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT)
00197 extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
00198 
00199 /**
00200  * \brief   This function allows configuring a custom \c snprintf function
00201  *          pointer.
00202  *
00203  * \param snprintf_func   The \c snprintf function implementation.
00204  *
00205  * \return    \c 0 on success.
00206  */
00207 int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
00208                                                  const char * format, ... ) );
00209 #else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
00210 #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
00211 #define mbedtls_snprintf   MBEDTLS_PLATFORM_SNPRINTF_MACRO
00212 #else
00213 #define mbedtls_snprintf   snprintf
00214 #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
00215 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
00216 
00217 /*
00218  * The function pointers for exit
00219  */
00220 #if defined(MBEDTLS_PLATFORM_EXIT_ALT)
00221 extern void (*mbedtls_exit)( int status );
00222 
00223 /**
00224  * \brief   This function allows configuring a custom \c exit function
00225  *          pointer.
00226  *
00227  * \param exit_func   The \c exit function implementation.
00228  *
00229  * \return  \c 0 on success.
00230  */
00231 int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
00232 #else
00233 #if defined(MBEDTLS_PLATFORM_EXIT_MACRO)
00234 #define mbedtls_exit   MBEDTLS_PLATFORM_EXIT_MACRO
00235 #else
00236 #define mbedtls_exit   exit
00237 #endif /* MBEDTLS_PLATFORM_EXIT_MACRO */
00238 #endif /* MBEDTLS_PLATFORM_EXIT_ALT */
00239 
00240 /*
00241  * The default exit values
00242  */
00243 #if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
00244 #define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
00245 #else
00246 #define MBEDTLS_EXIT_SUCCESS 0
00247 #endif
00248 #if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
00249 #define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE
00250 #else
00251 #define MBEDTLS_EXIT_FAILURE 1
00252 #endif
00253 
00254 /*
00255  * The function pointers for reading from and writing a seed file to
00256  * Non-Volatile storage (NV) in a platform-independent way
00257  *
00258  * Only enabled when the NV seed entropy source is enabled
00259  */
00260 #if defined(MBEDTLS_ENTROPY_NV_SEED)
00261 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO)
00262 /* Internal standard platform definitions */
00263 int mbedtls_platform_std_nv_seed_read( unsigned char *buf, size_t buf_len );
00264 int mbedtls_platform_std_nv_seed_write( unsigned char *buf, size_t buf_len );
00265 #endif
00266 
00267 #if defined(MBEDTLS_PLATFORM_NV_SEED_ALT)
00268 extern int (*mbedtls_nv_seed_read)( unsigned char *buf, size_t buf_len );
00269 extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len );
00270 
00271 /**
00272  * \brief   This function allows configuring custom seed file writing and
00273  *          reading functions.
00274  *
00275  * \param   nv_seed_read_func   The seed reading function implementation.
00276  * \param   nv_seed_write_func  The seed writing function implementation.
00277  *
00278  * \return  \c 0 on success.
00279  */
00280 int mbedtls_platform_set_nv_seed(
00281             int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ),
00282             int (*nv_seed_write_func)( unsigned char *buf, size_t buf_len )
00283             );
00284 #else
00285 #if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \
00286     defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO)
00287 #define mbedtls_nv_seed_read    MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
00288 #define mbedtls_nv_seed_write   MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
00289 #else
00290 #define mbedtls_nv_seed_read    mbedtls_platform_std_nv_seed_read
00291 #define mbedtls_nv_seed_write   mbedtls_platform_std_nv_seed_write
00292 #endif
00293 #endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */
00294 #endif /* MBEDTLS_ENTROPY_NV_SEED */
00295 
00296 #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
00297 
00298 /**
00299  * \brief   The platform context structure.
00300  *
00301  * \note    This structure may be used to assist platform-specific
00302  *          setup or teardown operations.
00303  */
00304 typedef struct {
00305     char dummy; /**< Placeholder member, as empty structs are not portable. */
00306 }
00307 mbedtls_platform_context;
00308 
00309 #else
00310 #include "platform_alt.h"
00311 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
00312 
00313 /**
00314  * \brief   This function performs any platform initialization operations.
00315  *
00316  * \param   ctx     The Mbed TLS context.
00317  *
00318  * \return  \c 0 on success.
00319  *
00320  * \note    This function is intended to allow platform-specific initialization,
00321  *          and should be called before any other library functions. Its
00322  *          implementation is platform-specific, and unless
00323  *          platform-specific code is provided, it does nothing.
00324  *
00325  *          Its use and whether it is necessary to call it is dependent on the
00326  *          platform.
00327  */
00328 int mbedtls_platform_setup( mbedtls_platform_context *ctx );
00329 /**
00330  * \brief   This function performs any platform teardown operations.
00331  *
00332  * \param   ctx     The Mbed TLS context.
00333  *
00334  * \note    This function should be called after every other Mbed TLS module
00335  *          has been correctly freed using the appropriate free function.
00336  *          Its implementation is platform-specific, and unless
00337  *          platform-specific code is provided, it does nothing.
00338  *
00339  *          Its use and whether it is necessary to call it is dependent on the
00340  *          platform.
00341  */
00342 void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
00343 
00344 #ifdef __cplusplus
00345 }
00346 #endif
00347 
00348 #endif /* platform.h */