tls_mbed_funcs.h (13368B)
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 #ifdef mhd_HAVE_TLS_ACME 120 /** 121 * Check whether MbedTLS backend supports ACME ALPN challenge protocol 122 * @param s the daemon settings 123 * @return 'true' if the backend supports ACME ALPN challenge protocol, 124 * 'false' otherwise 125 */ 126 # define mhd_tls_mbed_is_acme_alpn_supported(s) ((void)(s), (!!0)) 127 #endif /* mhd_HAVE_TLS_ACME */ 128 129 /** 130 * Allocate and initialise daemon TLS parameters 131 * @param d the daemon handle 132 * @param s the daemon settings 133 * @param p_d_tls the pointer to variable to set the pointer to 134 * the daemon's TLS settings (allocated by this function) 135 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 136 * error code otherwise 137 */ 138 MHD_INTERNAL mhd_StatusCodeInt 139 mhd_tls_mbed_daemon_init3 (struct MHD_Daemon *restrict d, 140 struct DaemonOptions *restrict s, 141 struct mhd_TlsMbedDaemonData **restrict p_d_tls) 142 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 143 144 /** 145 * Allocate and initialise daemon TLS parameters 146 * @param d the daemon handle 147 * @param et if 'true' then sockets polling uses edge-triggering 148 * @param s the daemon settings 149 * @param p_d_tls the pointer to variable to set the pointer to 150 * the daemon's TLS settings (allocated by this function) 151 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 152 * error code otherwise 153 */ 154 #define mhd_tls_mbed_daemon_init(d, et, s, p_d_tls) \ 155 mhd_tls_mbed_daemon_init3 ((d),(s),(p_d_tls)) 156 157 /** 158 * De-initialise daemon TLS parameters (and free memory allocated for TLS 159 * settings) 160 * @param d_tls the pointer to the daemon's TLS settings 161 */ 162 MHD_INTERNAL void 163 mhd_tls_mbed_daemon_deinit (struct mhd_TlsMbedDaemonData *restrict d_tls) 164 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 165 166 /** 167 * Perform clean-up of TLS resources before thread closing. 168 * Must be called before thread is closed, after any use of TLS functions 169 * in the thread, but before de-initialisation of daemon's TLS data. 170 * @param d_tls the pointer to the daemon's TLS settings 171 */ 172 #define mhd_tls_mbed_thread_cleanup(d_tls) ((void) 0) 173 174 /* ** Credentials creation / destruction ** */ 175 176 #define mhd_tls_mbed_cred_create(d_tls, pp_c, cert_l, cert, k_l, k, ps_l, ps) \ 177 ((void)d_tls, (void)pp_c, (void)cert_l, (void)cert, \ 178 (void)k_l, (void)k, (void)ps_l, (void)ps, \ 179 mhd_TLS_CRED_CREATE_UNSUPPORTED) 180 #define mhd_tls_mbed_cred_destroy_nodmn(cred) ((void)(cred)) 181 182 /** 183 * Release TLS credentials and free the allocated memory when no references 184 * remain. 185 * 186 * @param d_tls the pointer to the daemon's TLS settings 187 * @param cred the backend-specific credentials pointer to release; the MbedTLS 188 * member must be non-NULL 189 */ 190 #define mhd_tls_mbed_cred_destroy(d_tls, cred) \ 191 do { (void)(d_tls); \ 192 mhd_tls_mbed_cred_destroy_nodmn ((cred)); } while (0) 193 194 /* ** Connection initialisation / de-initialisation ** */ 195 196 struct mhd_ConnSocket; /* Forward declaration */ 197 198 /** 199 * Get size size of the connection's TLS settings 200 */ 201 MHD_INTERNAL size_t 202 mhd_tls_mbed_conn_get_tls_size_v (void); 203 204 /** 205 * Get size size of the connection's TLS settings 206 * @param d_tls the pointer to the daemon's TLS settings 207 */ 208 #define mhd_tls_mbed_conn_get_tls_size(d_tls) \ 209 mhd_tls_mbed_conn_get_tls_size_v () 210 211 /** 212 * Initialise connection TLS settings 213 * @param d_tls the daemon TLS settings 214 * @param sk data about the socket for the connection 215 * @param[out] c_tls the pointer to the allocated space for 216 * the connection TLS settings 217 * @return 'true' on success, 218 * 'false' otherwise 219 */ 220 MHD_INTERNAL bool 221 mhd_tls_mbed_conn_init (const struct mhd_TlsMbedDaemonData *restrict d_tls, 222 struct mhd_ConnSocket *sk, 223 struct mhd_TlsMbedConnData *restrict c_tls) 224 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 225 226 /** 227 * De-initialise connection TLS settings. 228 * The provided pointer is not freed/deallocated. 229 * @param c_tls the initialised connection TLS settings 230 */ 231 MHD_INTERNAL void 232 mhd_tls_mbed_conn_deinit (struct mhd_TlsMbedConnData *restrict c_tls) 233 MHD_FN_PAR_NONNULL_ALL_; 234 235 236 /* ** TLS connection establishing ** */ 237 238 /** 239 * Perform TLS handshake 240 * @param c_tls the connection TLS handle 241 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 242 * or other enum mhd_TlsProcedureResult values 243 */ 244 MHD_INTERNAL enum mhd_TlsProcedureResult 245 mhd_tls_mbed_conn_handshake (struct mhd_TlsMbedConnData *c_tls) 246 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 247 248 /** 249 * Perform shutdown of TLS layer 250 * @param c_tls the connection TLS handle 251 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 252 * or other enum mhd_TlsProcedureResult values 253 */ 254 MHD_INTERNAL enum mhd_TlsProcedureResult 255 mhd_tls_mbed_conn_shutdown (struct mhd_TlsMbedConnData *c_tls) 256 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 257 258 259 /* ** Data sending and receiving over TLS connection ** */ 260 261 /** 262 * Receive the data from the remote side over TLS connection 263 * 264 * @param c_tls the connection TLS handle 265 * @param buf_size the size of the @a buf buffer 266 * @param[out] buf the buffer to fill with the received data 267 * @param[out] received the pointer to variable to get the size of the data 268 * actually put to the @a buffer 269 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 270 * the received size) or socket error 271 */ 272 MHD_INTERNAL enum mhd_SocketError 273 mhd_tls_mbed_conn_recv (struct mhd_TlsMbedConnData *c_tls, 274 size_t buf_size, 275 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 276 size_t *restrict received) 277 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 278 279 /** 280 * Check whether any incoming data is pending in the TLS buffers 281 * 282 * @param c_tls the connection TLS handle 283 * @return 'true' if any incoming remote data is already pending (the TLS recv() 284 * call can be performed), 285 * 'false' otherwise 286 */ 287 MHD_INTERNAL bool 288 mhd_tls_mbed_conn_has_data_in (struct mhd_TlsMbedConnData *restrict c_tls) 289 MHD_FN_PAR_NONNULL_ALL_; 290 291 /** 292 * Send data to the remote side over TLS connection 293 * 294 * @param c_tls the connection TLS handle 295 * @param buf_size the size of the @a buf (in bytes) 296 * @param buf content of the buffer to send 297 * @param push_data set to 'false' if it is know that the data in the @a buf 298 * is incomplete (message or chunk), 299 * set to 'true' if the data is complete or the final part 300 * @param[out] sent the pointer to get amount of actually sent bytes 301 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 302 * the sent size) or socket error 303 */ 304 MHD_INTERNAL enum mhd_SocketError 305 mhd_tls_mbed_conn_send (struct mhd_TlsMbedConnData *c_tls, 306 size_t buf_size, 307 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 308 bool push_data, 309 size_t *restrict sent) 310 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (5); 311 312 313 /* ** TLS connection information ** */ 314 315 /** 316 * Check whether the connection is using "custom transport" functions. 317 * "Custom transport" means that data sending and receiving over system 318 * sockets is performed by MHD callbacks. 319 * When "custom transport" is used, backend TLS send/recv functions are: 320 * * perform additional syscalls (socket options) for data pushing/buffering, 321 * * change socket states like corked, NO_DELAY, both by syscalls and in 322 * MHD socket metadata, 323 * * set disconnect error from the system reported socket error. 324 * 325 * @param c_tls the connection TLS handle 326 * @return boolean 'true' if custom transport is used, 327 * boolean 'false' otherwise 328 */ 329 #define mhd_tls_mbed_conn_has_cstm_tr(c_tls) (! 0) 330 331 /** 332 * Get the TLS session used in connection 333 * @param c_tls the connection TLS handle 334 * @param tls_sess_out the pointer to variable to be set to the TLS session 335 * handle 336 */ 337 MHD_INTERNAL void 338 mhd_tls_mbed_conn_get_tls_sess ( 339 struct mhd_TlsMbedConnData *restrict c_tls, 340 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 341 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 342 343 /** 344 * Get the TLS version used in connection 345 * @param c_tls the connection TLS handle 346 * @param tls_ver_out the pointer to variable to be set to the TLS version 347 * @return 'true' is TLS version information set successfully, 348 * 'false' if TLS version information cannot be obtained or mapped 349 */ 350 MHD_INTERNAL bool 351 mhd_tls_mbed_conn_get_tls_ver (struct mhd_TlsMbedConnData *restrict c_tls, 352 struct mhd_StctTlsVersion *restrict tls_ver_out) 353 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 354 355 /** 356 * Get a protocol selected by ALPN 357 * @param c_tls the connection TLS handle 358 * @return the selected protocol code 359 */ 360 MHD_INTERNAL enum mhd_TlsAlpnProt 361 mhd_tls_mbed_conn_get_alpn_prot (struct mhd_TlsMbedConnData *restrict c_tls) 362 MHD_FN_PAR_NONNULL_ALL_; 363 364 #ifdef mhd_HAVE_TLS_ACME 365 /** 366 * Check whether the connection is ACME ALPN challenge connection 367 * @param c_tls the connection TLS handle 368 * @return 'true' if the connection is ACME ALPN challenge connection, 369 * 'false' otherwise 370 */ 371 # define mhd_tls_mbed_conn_is_acme(c_tls) (((void)(c_tls)), (!!0)) 372 #endif /* mhd_HAVE_TLS_ACME */ 373 374 375 #endif /* ! MHD_TLS_MBED_FUNCS_H */