tls_mbed_funcs.h (11908B)
1 /* SPDX-License-Identifier: LGPL-2.1-or-later OR (GPL-2.0-or-later WITH eCos-exception-2.0) */ 2 /* 3 This file is part of GNU libmicrohttpd. 4 Copyright (C) 2025 Evgeny Grin (Karlson2k) 5 6 GNU libmicrohttpd is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public 8 License as published by the Free Software Foundation; either 9 version 2.1 of the License, or (at your option) any later version. 10 11 GNU libmicrohttpd is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 Alternatively, you can redistribute GNU libmicrohttpd and/or 17 modify it under the terms of the GNU General Public License as 18 published by the Free Software Foundation; either version 2 of 19 the License, or (at your option) any later version, together 20 with the eCos exception, as follows: 21 22 As a special exception, if other files instantiate templates or 23 use macros or inline functions from this file, or you compile this 24 file and link it with other works to produce a work based on this 25 file, this file does not by itself cause the resulting work to be 26 covered by the GNU General Public License. However the source code 27 for this file must still be made available in accordance with 28 section (3) of the GNU General Public License v2. 29 30 This exception does not invalidate any other reasons why a work 31 based on this file might be covered by the GNU General Public 32 License. 33 34 You should have received copies of the GNU Lesser General Public 35 License and the GNU General Public License along with this library; 36 if not, see <https://www.gnu.org/licenses/>. 37 */ 38 39 /** 40 * @file src/mhd2/tls_mbed_funcs.h 41 * @brief The declarations of MbedTLS wrapper functions 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_TLS_MBED_FUNCS_H 46 #define MHD_TLS_MBED_FUNCS_H 1 47 48 #include "mhd_sys_options.h" 49 50 #ifndef MHD_SUPPORT_MBEDTLS 51 #error This header can be used only if MbedTLS is enabled 52 #endif 53 54 #include "sys_bool_type.h" 55 #include "sys_base_types.h" 56 57 #include "mhd_status_code_int.h" 58 59 #include "mhd_tls_enums.h" 60 #include "mhd_socket_error.h" 61 62 /** 63 * The structure with daemon-specific MbedTLS data 64 */ 65 struct mhd_TlsMbedDaemonData; /* Forward declaration */ 66 67 /** 68 * The structure with connection-specific MbedTLS data 69 */ 70 struct mhd_TlsMbedConnData; /* Forward declaration */ 71 72 union MHD_ConnInfoDynamicTlsSess; /* Forward declaration */ 73 74 struct mhd_StctTlsVersion; /* Forward declaration */ 75 76 /* ** Global initialisation / de-initialisation ** */ 77 78 /** 79 * Globally initialise MbedTLS backend 80 */ 81 MHD_INTERNAL void 82 mhd_tls_mbed_global_init (void); 83 84 /* An alias for mhd_tls_mbed_global_init() */ 85 #define mhd_tls_mbed_global_init_once() mhd_tls_mbed_global_init () 86 87 /* An alias for mhd_tls_mbed_global_init() */ 88 #define mhd_tls_mbed_global_re_init() mhd_tls_mbed_global_init () 89 90 /** 91 * Globally de-initialise MbedTLS backend 92 */ 93 MHD_INTERNAL void 94 mhd_tls_mbed_global_deinit (void); 95 96 /** 97 * Check whether MbedTLS backend was successfully initialised globally 98 * @return 'true' if backend has been successfully initialised, 99 * 'false' if backend cannot be used 100 */ 101 MHD_INTERNAL bool 102 mhd_tls_mbed_is_inited_fine (void) 103 MHD_FN_PURE_; 104 105 106 /* ** Daemon initialisation / de-initialisation ** */ 107 108 struct MHD_Daemon; /* Forward declaration */ 109 struct DaemonOptions; /* Forward declaration */ 110 111 /** 112 * Check whether MbedTLS backend supports edge-triggered sockets polling 113 * @param s the daemon settings 114 * @return 'true' if the backend supports edge-triggered sockets polling, 115 * 'false' if edge-triggered sockets polling cannot be used 116 */ 117 #define mhd_tls_mbed_is_edge_trigg_supported(s) (! 0) 118 119 120 /** 121 * Allocate and initialise daemon TLS parameters 122 * @param d the daemon handle 123 * @param s the daemon settings 124 * @param p_d_tls the pointer to variable to set the pointer to 125 * the daemon's TLS settings (allocated by this function) 126 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 127 * error code otherwise 128 */ 129 MHD_INTERNAL mhd_StatusCodeInt 130 mhd_tls_mbed_daemon_init3 (struct MHD_Daemon *restrict d, 131 struct DaemonOptions *restrict s, 132 struct mhd_TlsMbedDaemonData **restrict p_d_tls) 133 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 134 135 /** 136 * Allocate and initialise daemon TLS parameters 137 * @param d the daemon handle 138 * @param et if 'true' then sockets polling uses edge-triggering 139 * @param s the daemon settings 140 * @param p_d_tls the pointer to variable to set the pointer to 141 * the daemon's TLS settings (allocated by this function) 142 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 143 * error code otherwise 144 */ 145 #define mhd_tls_mbed_daemon_init(d,et,s,p_d_tls) \ 146 mhd_tls_mbed_daemon_init3 ((d),(s),(p_d_tls)) 147 148 /** 149 * De-initialise daemon TLS parameters (and free memory allocated for TLS 150 * settings) 151 * @param d_tls the pointer to the daemon's TLS settings 152 */ 153 MHD_INTERNAL void 154 mhd_tls_mbed_daemon_deinit (struct mhd_TlsMbedDaemonData *restrict d_tls) 155 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 156 157 /** 158 * Perform clean-up of TLS resources before thread closing. 159 * Must be called before thread is closed, after any use of TLS functions 160 * in the thread, but before de-initialisation of daemon's TLS data. 161 * @param d_tls the pointer to the daemon's TLS settings 162 */ 163 #define mhd_tls_mbed_thread_cleanup(d_tls) ((void) 0) 164 165 /* ** Connection initialisation / de-initialisation ** */ 166 167 struct mhd_ConnSocket; /* Forward declaration */ 168 169 /** 170 * Get size size of the connection's TLS settings 171 */ 172 MHD_INTERNAL size_t 173 mhd_tls_mbed_conn_get_tls_size_v (void); 174 175 /** 176 * Get size size of the connection's TLS settings 177 * @param d_tls the pointer to the daemon's TLS settings 178 */ 179 #define mhd_tls_mbed_conn_get_tls_size(d_tls) \ 180 mhd_tls_mbed_conn_get_tls_size_v () 181 182 /** 183 * Initialise connection TLS settings 184 * @param d_tls the daemon TLS settings 185 * @param sk data about the socket for the connection 186 * @param[out] c_tls the pointer to the allocated space for 187 * the connection TLS settings 188 * @return 'true' on success, 189 * 'false' otherwise 190 */ 191 MHD_INTERNAL bool 192 mhd_tls_mbed_conn_init (const struct mhd_TlsMbedDaemonData *restrict d_tls, 193 struct mhd_ConnSocket *sk, 194 struct mhd_TlsMbedConnData *restrict c_tls) 195 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 196 197 /** 198 * De-initialise connection TLS settings. 199 * The provided pointer is not freed/deallocated. 200 * @param c_tls the initialised connection TLS settings 201 */ 202 MHD_INTERNAL void 203 mhd_tls_mbed_conn_deinit (struct mhd_TlsMbedConnData *restrict c_tls) 204 MHD_FN_PAR_NONNULL_ALL_; 205 206 207 /* ** TLS connection establishing ** */ 208 209 /** 210 * Perform TLS handshake 211 * @param c_tls the connection TLS handle 212 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 213 * or other enum mhd_TlsProcedureResult values 214 */ 215 MHD_INTERNAL enum mhd_TlsProcedureResult 216 mhd_tls_mbed_conn_handshake (struct mhd_TlsMbedConnData *c_tls) 217 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 218 219 /** 220 * Perform shutdown of TLS layer 221 * @param c_tls the connection TLS handle 222 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 223 * or other enum mhd_TlsProcedureResult values 224 */ 225 MHD_INTERNAL enum mhd_TlsProcedureResult 226 mhd_tls_mbed_conn_shutdown (struct mhd_TlsMbedConnData *c_tls) 227 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 228 229 230 /* ** Data sending and receiving over TLS connection ** */ 231 232 /** 233 * Receive the data from the remote side over TLS connection 234 * 235 * @param c_tls the connection TLS handle 236 * @param buf_size the size of the @a buf buffer 237 * @param[out] buf the buffer to fill with the received data 238 * @param[out] received the pointer to variable to get the size of the data 239 * actually put to the @a buffer 240 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 241 * the received size) or socket error 242 */ 243 MHD_INTERNAL enum mhd_SocketError 244 mhd_tls_mbed_conn_recv (struct mhd_TlsMbedConnData *c_tls, 245 size_t buf_size, 246 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 247 size_t *restrict received) 248 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3,2) MHD_FN_PAR_OUT_ (4); 249 250 /** 251 * Check whether any incoming data is pending in the TLS buffers 252 * 253 * @param c_tls the connection TLS handle 254 * @return 'true' if any incoming remote data is already pending (the TLS recv() 255 * call can be performed), 256 * 'false' otherwise 257 */ 258 MHD_INTERNAL bool 259 mhd_tls_mbed_conn_has_data_in (struct mhd_TlsMbedConnData *restrict c_tls) 260 MHD_FN_PAR_NONNULL_ALL_; 261 262 /** 263 * Send data to the remote side over TLS connection 264 * 265 * @param c_tls the connection TLS handle 266 * @param buf_size the size of the @a buf (in bytes) 267 * @param buf content of the buffer to send 268 * @param push_data set to 'false' if it is know that the data in the @a buf 269 * is incomplete (message or chunk), 270 * set to 'true' if the data is complete or the final part 271 * @param[out] sent the pointer to get amount of actually sent bytes 272 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 273 * the sent size) or socket error 274 */ 275 MHD_INTERNAL enum mhd_SocketError 276 mhd_tls_mbed_conn_send (struct mhd_TlsMbedConnData *c_tls, 277 size_t buf_size, 278 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 279 bool push_data, 280 size_t *restrict sent) 281 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3,2) MHD_FN_PAR_OUT_ (5); 282 283 284 /* ** TLS connection information ** */ 285 286 /** 287 * Check whether the connection is using "custom transport" functions. 288 * "Custom transport" means that data sending and receiving over system 289 * sockets is performed by MHD callbacks. 290 * When "custom transport" is used, backend TLS send/recv functions are: 291 * * perform additional syscalls (socket options) for data pushing/buffering, 292 * * change socket states like corked, NO_DELAY, both by syscalls and in 293 * MHD socket metadata, 294 * * set disconnect error from the system reported socket error. 295 * 296 * @param c_tls the connection TLS handle 297 * @return boolean 'true' if custom transport is used, 298 * boolean 'false' otherwise 299 */ 300 #define mhd_tls_mbed_conn_has_cstm_tr(c_tls) (! 0) 301 302 /** 303 * Get the TLS session used in connection 304 * @param c_tls the connection TLS handle 305 * @param tls_sess_out the pointer to variable to be set to the TLS session 306 * handle 307 */ 308 MHD_INTERNAL void 309 mhd_tls_mbed_conn_get_tls_sess ( 310 struct mhd_TlsMbedConnData *restrict c_tls, 311 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 312 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 313 314 /** 315 * Get the TLS version used in connection 316 * @param c_tls the connection TLS handle 317 * @param tls_ver_out the pointer to variable to be set to the TLS version 318 * @return 'true' is TLS version information set successfully, 319 * 'false' if TLS version information cannot be obtained or mapped 320 */ 321 MHD_INTERNAL bool 322 mhd_tls_mbed_conn_get_tls_ver (struct mhd_TlsMbedConnData *restrict c_tls, 323 struct mhd_StctTlsVersion *restrict tls_ver_out) 324 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 325 326 /** 327 * Get a protocol selected by ALPN 328 * @param c_tls the connection TLS handle 329 * @return the selected protocol code 330 */ 331 MHD_INTERNAL enum mhd_TlsAlpnProt 332 mhd_tls_mbed_conn_get_alpn_prot (struct mhd_TlsMbedConnData *restrict c_tls) 333 MHD_FN_PAR_NONNULL_ALL_; 334 335 336 #endif /* ! MHD_TLS_MBED_FUNCS_H */