platform.h 13 KB

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