platform.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
  1. /**
  2. * \file platform.h
  3. *
  4. * \brief The Mbed TLS platform abstraction layer.
  5. */
  6. /*
  7. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of Mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_PLATFORM_H
  25. #define MBEDTLS_PLATFORM_H
  26. #if !defined(MBEDTLS_CONFIG_FILE)
  27. #include "config.h"
  28. #else
  29. #include MBEDTLS_CONFIG_FILE
  30. #endif
  31. #if defined(MBEDTLS_HAVE_TIME)
  32. #include "mbedtls/platform_time.h"
  33. #endif
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37. /**
  38. * \name SECTION: Module settings
  39. *
  40. * The configuration options you can set for this module are in this section.
  41. * Either change them in config.h or define them on the compiler command line.
  42. * \{
  43. */
  44. #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
  45. #include <stdio.h>
  46. #include <stdlib.h>
  47. #include <time.h>
  48. #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
  49. #if defined(_WIN32)
  50. #define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */
  51. #else
  52. #define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */
  53. #endif
  54. #endif
  55. #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
  56. #define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */
  57. #endif
  58. #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
  59. #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
  60. #endif
  61. #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
  62. #define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */
  63. #endif
  64. #if !defined(MBEDTLS_PLATFORM_STD_FREE)
  65. #define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */
  66. #endif
  67. #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
  68. #define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */
  69. #endif
  70. #if !defined(MBEDTLS_PLATFORM_STD_TIME)
  71. #define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */
  72. #endif
  73. #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
  74. #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */
  75. #endif
  76. #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
  77. #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */
  78. #endif
  79. #if defined(MBEDTLS_FS_IO)
  80. #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
  81. #define MBEDTLS_PLATFORM_STD_NV_SEED_READ mbedtls_platform_std_nv_seed_read
  82. #endif
  83. #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE)
  84. #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE mbedtls_platform_std_nv_seed_write
  85. #endif
  86. #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE)
  87. #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE "seedfile"
  88. #endif
  89. #endif /* MBEDTLS_FS_IO */
  90. #else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
  91. #if defined(MBEDTLS_PLATFORM_STD_MEM_HDR)
  92. #include MBEDTLS_PLATFORM_STD_MEM_HDR
  93. #endif
  94. #endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
  95. /* \} name SECTION: Module settings */
  96. /*
  97. * The function pointers for calloc and free
  98. */
  99. #if defined(MBEDTLS_PLATFORM_MEMORY)
  100. #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
  101. defined(MBEDTLS_PLATFORM_CALLOC_MACRO)
  102. #define mbedtls_free MBEDTLS_PLATFORM_FREE_MACRO
  103. #define mbedtls_calloc MBEDTLS_PLATFORM_CALLOC_MACRO
  104. #else
  105. /* For size_t */
  106. #include <stddef.h>
  107. extern void * (*mbedtls_calloc)( size_t n, size_t size );
  108. extern void (*mbedtls_free)( void *ptr );
  109. /**
  110. * \brief This function allows configuring custom memory-management functions.
  111. *
  112. * \param calloc_func The \c calloc function implementation.
  113. * \param free_func The \c free function implementation.
  114. *
  115. * \return \c 0.
  116. */
  117. int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
  118. void (*free_func)( void * ) );
  119. #endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */
  120. #else /* !MBEDTLS_PLATFORM_MEMORY */
  121. #define mbedtls_free free
  122. #define mbedtls_calloc calloc
  123. #endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */
  124. /*
  125. * The function pointers for fprintf
  126. */
  127. #if defined(MBEDTLS_PLATFORM_FPRINTF_ALT)
  128. /* We need FILE * */
  129. #include <stdio.h>
  130. extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
  131. /**
  132. * \brief This function allows configuring a custom \p fprintf function pointer.
  133. *
  134. * \param fprintf_func The \c fprintf function implementation.
  135. *
  136. * \return \c 0.
  137. */
  138. int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *,
  139. ... ) );
  140. #else
  141. #if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO)
  142. #define mbedtls_fprintf MBEDTLS_PLATFORM_FPRINTF_MACRO
  143. #else
  144. #define mbedtls_fprintf fprintf
  145. #endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */
  146. #endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */
  147. /*
  148. * The function pointers for printf
  149. */
  150. #if defined(MBEDTLS_PLATFORM_PRINTF_ALT)
  151. extern int (*mbedtls_printf)( const char *format, ... );
  152. /**
  153. * \brief This function allows configuring a custom \c printf function
  154. * pointer.
  155. *
  156. * \param printf_func The \c printf function implementation.
  157. *
  158. * \return \c 0 on success.
  159. */
  160. int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) );
  161. #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
  162. #if defined(MBEDTLS_PLATFORM_PRINTF_MACRO)
  163. #define mbedtls_printf MBEDTLS_PLATFORM_PRINTF_MACRO
  164. #else
  165. #define mbedtls_printf printf
  166. #endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */
  167. #endif /* MBEDTLS_PLATFORM_PRINTF_ALT */
  168. /*
  169. * The function pointers for snprintf
  170. *
  171. * The snprintf implementation should conform to C99:
  172. * - it *must* always correctly zero-terminate the buffer
  173. * (except when n == 0, then it must leave the buffer untouched)
  174. * - however it is acceptable to return -1 instead of the required length when
  175. * the destination buffer is too short.
  176. */
  177. #if defined(_WIN32)
  178. /* For Windows (inc. MSYS2), we provide our own fixed implementation */
  179. int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
  180. #endif
  181. #if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT)
  182. extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
  183. /**
  184. * \brief This function allows configuring a custom \c snprintf function
  185. * pointer.
  186. *
  187. * \param snprintf_func The \c snprintf function implementation.
  188. *
  189. * \return \c 0 on success.
  190. */
  191. int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
  192. const char * format, ... ) );
  193. #else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
  194. #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
  195. #define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO
  196. #define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO
  197. #else
  198. #define mbedtls_snprintf snprintf
  199. #define mbedtls_vsnprintf vsnprintf
  200. #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
  201. #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
  202. /*
  203. * The function pointers for exit
  204. */
  205. #if defined(MBEDTLS_PLATFORM_EXIT_ALT)
  206. extern void (*mbedtls_exit)( int status );
  207. /**
  208. * \brief This function allows configuring a custom \c exit function
  209. * pointer.
  210. *
  211. * \param exit_func The \c exit function implementation.
  212. *
  213. * \return \c 0 on success.
  214. */
  215. int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
  216. #else
  217. #if defined(MBEDTLS_PLATFORM_EXIT_MACRO)
  218. #define mbedtls_exit MBEDTLS_PLATFORM_EXIT_MACRO
  219. #else
  220. #define mbedtls_exit exit
  221. #endif /* MBEDTLS_PLATFORM_EXIT_MACRO */
  222. #endif /* MBEDTLS_PLATFORM_EXIT_ALT */
  223. /*
  224. * The default exit values
  225. */
  226. #if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
  227. #define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
  228. #else
  229. #define MBEDTLS_EXIT_SUCCESS 0
  230. #endif
  231. #if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
  232. #define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE
  233. #else
  234. #define MBEDTLS_EXIT_FAILURE 1
  235. #endif
  236. /*
  237. * The function pointers for reading from and writing a seed file to
  238. * Non-Volatile storage (NV) in a platform-independent way
  239. *
  240. * Only enabled when the NV seed entropy source is enabled
  241. */
  242. #if defined(MBEDTLS_ENTROPY_NV_SEED)
  243. #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO)
  244. /* Internal standard platform definitions */
  245. int mbedtls_platform_std_nv_seed_read( unsigned char *buf, size_t buf_len );
  246. int mbedtls_platform_std_nv_seed_write( unsigned char *buf, size_t buf_len );
  247. #endif
  248. #if defined(MBEDTLS_PLATFORM_NV_SEED_ALT)
  249. extern int (*mbedtls_nv_seed_read)( unsigned char *buf, size_t buf_len );
  250. extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len );
  251. /**
  252. * \brief This function allows configuring custom seed file writing and
  253. * reading functions.
  254. *
  255. * \param nv_seed_read_func The seed reading function implementation.
  256. * \param nv_seed_write_func The seed writing function implementation.
  257. *
  258. * \return \c 0 on success.
  259. */
  260. int mbedtls_platform_set_nv_seed(
  261. int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ),
  262. int (*nv_seed_write_func)( unsigned char *buf, size_t buf_len )
  263. );
  264. #else
  265. #if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \
  266. defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO)
  267. #define mbedtls_nv_seed_read MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
  268. #define mbedtls_nv_seed_write MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
  269. #else
  270. #define mbedtls_nv_seed_read mbedtls_platform_std_nv_seed_read
  271. #define mbedtls_nv_seed_write mbedtls_platform_std_nv_seed_write
  272. #endif
  273. #endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */
  274. #endif /* MBEDTLS_ENTROPY_NV_SEED */
  275. #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
  276. /**
  277. * \brief The platform context structure.
  278. *
  279. * \note This structure may be used to assist platform-specific
  280. * setup or teardown operations.
  281. */
  282. typedef struct {
  283. char dummy; /**< Placeholder member, as empty structs are not portable. */
  284. }
  285. mbedtls_platform_context;
  286. #else
  287. #include "platform_alt.h"
  288. #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
  289. /**
  290. * \brief This function performs any platform initialization operations.
  291. *
  292. * \param ctx The Mbed TLS context.
  293. *
  294. * \return \c 0 on success.
  295. *
  296. * \note This function is intended to allow platform-specific initialization,
  297. * and should be called before any other library functions. Its
  298. * implementation is platform-specific, and unless
  299. * platform-specific code is provided, it does nothing.
  300. *
  301. * Its use and whether it is necessary to call it is dependent on the
  302. * platform.
  303. */
  304. int mbedtls_platform_setup( mbedtls_platform_context *ctx );
  305. /**
  306. * \brief This function performs any platform teardown operations.
  307. *
  308. * \param ctx The Mbed TLS context.
  309. *
  310. * \note This function should be called after every other Mbed TLS module
  311. * has been correctly freed using the appropriate free function.
  312. * Its implementation is platform-specific, and unless
  313. * platform-specific code is provided, it does nothing.
  314. *
  315. * Its use and whether it is necessary to call it is dependent on the
  316. * platform.
  317. */
  318. void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
  319. #ifdef __cplusplus
  320. }
  321. #endif
  322. #endif /* platform.h */