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