aboutsummaryrefslogtreecommitdiff
path: root/include/mbedtls/platform.h
diff options
context:
space:
mode:
authorLibravatar vnugent <public@vaughnnugent.com>2024-01-28 19:23:18 -0500
committerLibravatar vnugent <public@vaughnnugent.com>2024-01-28 19:23:18 -0500
commit626a8d8d3df8880991684d6d1a06b82f6685b51a (patch)
tree183c981ac44886445240ad1e1945f325ceaa9298 /include/mbedtls/platform.h
initial commit
Diffstat (limited to 'include/mbedtls/platform.h')
-rw-r--r--include/mbedtls/platform.h485
1 files changed, 485 insertions, 0 deletions
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
new file mode 100644
index 0000000..de3d71d
--- /dev/null
+++ b/include/mbedtls/platform.h
@@ -0,0 +1,485 @@
+/**
+ * \file platform.h
+ *
+ * \brief This file contains the definitions and functions of the
+ * Mbed TLS platform abstraction layer.
+ *
+ * The platform abstraction layer removes the need for the library
+ * to directly link to standard C library functions or operating
+ * system services, making the library easier to port and embed.
+ * Application developers and users of the library can provide their own
+ * implementations of these functions, or implementations specific to
+ * their platform, which can be statically linked to the library or
+ * dynamically configured at runtime.
+ *
+ * When all compilation options related to platform abstraction are
+ * disabled, this header just defines `mbedtls_xxx` function names
+ * as aliases to the standard `xxx` function.
+ *
+ * Most modules in the library and example programs are expected to
+ * include this header.
+ */
+/*
+ * Copyright The Mbed TLS Contributors
+ * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
+ */
+#ifndef MBEDTLS_PLATFORM_H
+#define MBEDTLS_PLATFORM_H
+#include "mbedtls/private_access.h"
+
+#include "mbedtls/build_info.h"
+
+#if defined(MBEDTLS_HAVE_TIME)
+#include "mbedtls/platform_time.h"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \name SECTION: Module settings
+ *
+ * The configuration options you can set for this module are in this section.
+ * Either change them in mbedtls_config.h or define them on the compiler command line.
+ * \{
+ */
+
+/* The older Microsoft Windows common runtime provides non-conforming
+ * implementations of some standard library functions, including snprintf
+ * and vsnprintf. This affects MSVC and MinGW builds.
+ */
+#if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900)
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF
+#endif
+
+#if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
+#include <stdio.h>
+#include <stdlib.h>
+#if defined(MBEDTLS_HAVE_TIME)
+#include <time.h>
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
+#define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */
+#else
+#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */
+#endif
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use. */
+#else
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF vsnprintf /**< The default \c vsnprintf function to use. */
+#endif
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
+#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
+#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
+#define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_FREE)
+#define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_SETBUF)
+#define MBEDTLS_PLATFORM_STD_SETBUF setbuf /**< The default \c setbuf function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_EXIT)
+#define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_TIME)
+#define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
+#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
+#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */
+#endif
+#if defined(MBEDTLS_FS_IO)
+#if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
+#define MBEDTLS_PLATFORM_STD_NV_SEED_READ mbedtls_platform_std_nv_seed_read
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_WRITE)
+#define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE mbedtls_platform_std_nv_seed_write
+#endif
+#if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_FILE)
+#define MBEDTLS_PLATFORM_STD_NV_SEED_FILE "seedfile"
+#endif
+#endif /* MBEDTLS_FS_IO */
+#else /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
+#if defined(MBEDTLS_PLATFORM_STD_MEM_HDR)
+#include MBEDTLS_PLATFORM_STD_MEM_HDR
+#endif
+#endif /* MBEDTLS_PLATFORM_NO_STD_FUNCTIONS */
+
+/* Enable certain documented defines only when generating doxygen to avoid
+ * an "unrecognized define" error. */
+#if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_CALLOC)
+#define MBEDTLS_PLATFORM_STD_CALLOC
+#endif
+
+#if defined(__DOXYGEN__) && !defined(MBEDTLS_PLATFORM_STD_FREE)
+#define MBEDTLS_PLATFORM_STD_FREE
+#endif
+
+/** \} name SECTION: Module settings */
+
+/*
+ * The function pointers for calloc and free.
+ * Please see MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE
+ * in mbedtls_config.h for more information about behaviour and requirements.
+ */
+#if defined(MBEDTLS_PLATFORM_MEMORY)
+#if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
+ defined(MBEDTLS_PLATFORM_CALLOC_MACRO)
+#undef mbedtls_free
+#undef mbedtls_calloc
+#define mbedtls_free MBEDTLS_PLATFORM_FREE_MACRO
+#define mbedtls_calloc MBEDTLS_PLATFORM_CALLOC_MACRO
+#else
+/* For size_t */
+#include <stddef.h>
+extern void *mbedtls_calloc(size_t n, size_t size);
+extern void mbedtls_free(void *ptr);
+
+/**
+ * \brief This function dynamically sets the memory-management
+ * functions used by the library, during runtime.
+ *
+ * \param calloc_func The \c calloc function implementation.
+ * \param free_func The \c free function implementation.
+ *
+ * \return \c 0.
+ */
+int mbedtls_platform_set_calloc_free(void *(*calloc_func)(size_t, size_t),
+ void (*free_func)(void *));
+#endif /* MBEDTLS_PLATFORM_FREE_MACRO && MBEDTLS_PLATFORM_CALLOC_MACRO */
+#else /* !MBEDTLS_PLATFORM_MEMORY */
+#undef mbedtls_free
+#undef mbedtls_calloc
+#define mbedtls_free free
+#define mbedtls_calloc calloc
+#endif /* MBEDTLS_PLATFORM_MEMORY && !MBEDTLS_PLATFORM_{FREE,CALLOC}_MACRO */
+
+/*
+ * The function pointers for fprintf
+ */
+#if defined(MBEDTLS_PLATFORM_FPRINTF_ALT)
+/* We need FILE * */
+#include <stdio.h>
+extern int (*mbedtls_fprintf)(FILE *stream, const char *format, ...);
+
+/**
+ * \brief This function dynamically configures the fprintf
+ * function that is called when the
+ * mbedtls_fprintf() function is invoked by the library.
+ *
+ * \param fprintf_func The \c fprintf function implementation.
+ *
+ * \return \c 0.
+ */
+int mbedtls_platform_set_fprintf(int (*fprintf_func)(FILE *stream, const char *,
+ ...));
+#else
+#undef mbedtls_fprintf
+#if defined(MBEDTLS_PLATFORM_FPRINTF_MACRO)
+#define mbedtls_fprintf MBEDTLS_PLATFORM_FPRINTF_MACRO
+#else
+#define mbedtls_fprintf fprintf
+#endif /* MBEDTLS_PLATFORM_FPRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_FPRINTF_ALT */
+
+/*
+ * The function pointers for printf
+ */
+#if defined(MBEDTLS_PLATFORM_PRINTF_ALT)
+extern int (*mbedtls_printf)(const char *format, ...);
+
+/**
+ * \brief This function dynamically configures the snprintf
+ * function that is called when the mbedtls_snprintf()
+ * function is invoked by the library.
+ *
+ * \param printf_func The \c printf function implementation.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_platform_set_printf(int (*printf_func)(const char *, ...));
+#else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
+#undef mbedtls_printf
+#if defined(MBEDTLS_PLATFORM_PRINTF_MACRO)
+#define mbedtls_printf MBEDTLS_PLATFORM_PRINTF_MACRO
+#else
+#define mbedtls_printf printf
+#endif /* MBEDTLS_PLATFORM_PRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_PRINTF_ALT */
+
+/*
+ * The function pointers for snprintf
+ *
+ * The snprintf implementation should conform to C99:
+ * - it *must* always correctly zero-terminate the buffer
+ * (except when n == 0, then it must leave the buffer untouched)
+ * - however it is acceptable to return -1 instead of the required length when
+ * the destination buffer is too short.
+ */
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
+/* For Windows (inc. MSYS2), we provide our own fixed implementation */
+int mbedtls_platform_win32_snprintf(char *s, size_t n, const char *fmt, ...);
+#endif
+
+#if defined(MBEDTLS_PLATFORM_SNPRINTF_ALT)
+extern int (*mbedtls_snprintf)(char *s, size_t n, const char *format, ...);
+
+/**
+ * \brief This function allows configuring a custom
+ * \c snprintf function pointer.
+ *
+ * \param snprintf_func The \c snprintf function implementation.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_platform_set_snprintf(int (*snprintf_func)(char *s, size_t n,
+ const char *format, ...));
+#else /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
+#undef mbedtls_snprintf
+#if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
+#define mbedtls_snprintf MBEDTLS_PLATFORM_SNPRINTF_MACRO
+#else
+#define mbedtls_snprintf MBEDTLS_PLATFORM_STD_SNPRINTF
+#endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
+
+/*
+ * The function pointers for vsnprintf
+ *
+ * The vsnprintf implementation should conform to C99:
+ * - it *must* always correctly zero-terminate the buffer
+ * (except when n == 0, then it must leave the buffer untouched)
+ * - however it is acceptable to return -1 instead of the required length when
+ * the destination buffer is too short.
+ */
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+#include <stdarg.h>
+/* For Older Windows (inc. MSYS2), we provide our own fixed implementation */
+int mbedtls_platform_win32_vsnprintf(char *s, size_t n, const char *fmt, va_list arg);
+#endif
+
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT)
+#include <stdarg.h>
+extern int (*mbedtls_vsnprintf)(char *s, size_t n, const char *format, va_list arg);
+
+/**
+ * \brief Set your own snprintf function pointer
+ *
+ * \param vsnprintf_func The \c vsnprintf function implementation
+ *
+ * \return \c 0
+ */
+int mbedtls_platform_set_vsnprintf(int (*vsnprintf_func)(char *s, size_t n,
+ const char *format, va_list arg));
+#else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+#undef mbedtls_vsnprintf
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
+#define mbedtls_vsnprintf MBEDTLS_PLATFORM_VSNPRINTF_MACRO
+#else
+#define mbedtls_vsnprintf vsnprintf
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+
+/*
+ * The function pointers for setbuf
+ */
+#if defined(MBEDTLS_PLATFORM_SETBUF_ALT)
+#include <stdio.h>
+/**
+ * \brief Function pointer to call for `setbuf()` functionality
+ * (changing the internal buffering on stdio calls).
+ *
+ * \note The library calls this function to disable
+ * buffering when reading or writing sensitive data,
+ * to avoid having extra copies of sensitive data
+ * remaining in stdio buffers after the file is
+ * closed. If this is not a concern, for example if
+ * your platform's stdio doesn't have any buffering,
+ * you can set mbedtls_setbuf to a function that
+ * does nothing.
+ *
+ * The library always calls this function with
+ * `buf` equal to `NULL`.
+ */
+extern void (*mbedtls_setbuf)(FILE *stream, char *buf);
+
+/**
+ * \brief Dynamically configure the function that is called
+ * when the mbedtls_setbuf() function is called by the
+ * library.
+ *
+ * \param setbuf_func The \c setbuf function implementation
+ *
+ * \return \c 0
+ */
+int mbedtls_platform_set_setbuf(void (*setbuf_func)(
+ FILE *stream, char *buf));
+#else
+#undef mbedtls_setbuf
+#if defined(MBEDTLS_PLATFORM_SETBUF_MACRO)
+/**
+ * \brief Macro defining the function for the library to
+ * call for `setbuf` functionality (changing the
+ * internal buffering on stdio calls).
+ *
+ * \note See extra comments on the mbedtls_setbuf() function
+ * pointer above.
+ *
+ * \return \c 0 on success, negative on error.
+ */
+#define mbedtls_setbuf MBEDTLS_PLATFORM_SETBUF_MACRO
+#else
+#define mbedtls_setbuf setbuf
+#endif /* MBEDTLS_PLATFORM_SETBUF_MACRO */
+#endif /* MBEDTLS_PLATFORM_SETBUF_ALT */
+
+/*
+ * The function pointers for exit
+ */
+#if defined(MBEDTLS_PLATFORM_EXIT_ALT)
+extern void (*mbedtls_exit)(int status);
+
+/**
+ * \brief This function dynamically configures the exit
+ * function that is called when the mbedtls_exit()
+ * function is invoked by the library.
+ *
+ * \param exit_func The \c exit function implementation.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_platform_set_exit(void (*exit_func)(int status));
+#else
+#undef mbedtls_exit
+#if defined(MBEDTLS_PLATFORM_EXIT_MACRO)
+#define mbedtls_exit MBEDTLS_PLATFORM_EXIT_MACRO
+#else
+#define mbedtls_exit exit
+#endif /* MBEDTLS_PLATFORM_EXIT_MACRO */
+#endif /* MBEDTLS_PLATFORM_EXIT_ALT */
+
+/*
+ * The default exit values
+ */
+#if defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
+#define MBEDTLS_EXIT_SUCCESS MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
+#else
+#define MBEDTLS_EXIT_SUCCESS 0
+#endif
+#if defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
+#define MBEDTLS_EXIT_FAILURE MBEDTLS_PLATFORM_STD_EXIT_FAILURE
+#else
+#define MBEDTLS_EXIT_FAILURE 1
+#endif
+
+/*
+ * The function pointers for reading from and writing a seed file to
+ * Non-Volatile storage (NV) in a platform-independent way
+ *
+ * Only enabled when the NV seed entropy source is enabled
+ */
+#if defined(MBEDTLS_ENTROPY_NV_SEED)
+#if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO)
+/* Internal standard platform definitions */
+int mbedtls_platform_std_nv_seed_read(unsigned char *buf, size_t buf_len);
+int mbedtls_platform_std_nv_seed_write(unsigned char *buf, size_t buf_len);
+#endif
+
+#if defined(MBEDTLS_PLATFORM_NV_SEED_ALT)
+extern int (*mbedtls_nv_seed_read)(unsigned char *buf, size_t buf_len);
+extern int (*mbedtls_nv_seed_write)(unsigned char *buf, size_t buf_len);
+
+/**
+ * \brief This function allows configuring custom seed file writing and
+ * reading functions.
+ *
+ * \param nv_seed_read_func The seed reading function implementation.
+ * \param nv_seed_write_func The seed writing function implementation.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_platform_set_nv_seed(
+ int (*nv_seed_read_func)(unsigned char *buf, size_t buf_len),
+ int (*nv_seed_write_func)(unsigned char *buf, size_t buf_len)
+ );
+#else
+#undef mbedtls_nv_seed_read
+#undef mbedtls_nv_seed_write
+#if defined(MBEDTLS_PLATFORM_NV_SEED_READ_MACRO) && \
+ defined(MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO)
+#define mbedtls_nv_seed_read MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
+#define mbedtls_nv_seed_write MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
+#else
+#define mbedtls_nv_seed_read mbedtls_platform_std_nv_seed_read
+#define mbedtls_nv_seed_write mbedtls_platform_std_nv_seed_write
+#endif
+#endif /* MBEDTLS_PLATFORM_NV_SEED_ALT */
+#endif /* MBEDTLS_ENTROPY_NV_SEED */
+
+#if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
+
+/**
+ * \brief The platform context structure.
+ *
+ * \note This structure may be used to assist platform-specific
+ * setup or teardown operations.
+ */
+typedef struct mbedtls_platform_context {
+ char MBEDTLS_PRIVATE(dummy); /**< A placeholder member, as empty structs are not portable. */
+}
+mbedtls_platform_context;
+
+#else
+#include "platform_alt.h"
+#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
+
+/**
+ * \brief This function performs any platform-specific initialization
+ * operations.
+ *
+ * \note This function should be called before any other library functions.
+ *
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
+ *
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The platform context.
+ *
+ * \return \c 0 on success.
+ */
+int mbedtls_platform_setup(mbedtls_platform_context *ctx);
+/**
+ * \brief This function performs any platform teardown operations.
+ *
+ * \note This function should be called after every other Mbed TLS module
+ * has been correctly freed using the appropriate free function.
+ *
+ * Its implementation is platform-specific, and unless
+ * platform-specific code is provided, it does nothing.
+ *
+ * \note The usage and necessity of this function is dependent on the platform.
+ *
+ * \param ctx The platform context.
+ *
+ */
+void mbedtls_platform_teardown(mbedtls_platform_context *ctx);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* platform.h */