tls_multi_funcs.h (11516B)
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) 2024-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_multi_funcs.h 41 * @brief The declarations of MultiTLS wrapper functions 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_TLS_MULTI_FUNCS_H 46 #define MHD_TLS_MULTI_FUNCS_H 1 47 48 #include "mhd_sys_options.h" 49 50 #include "mhd_tls_choice.h" 51 52 #ifndef MHD_USE_MULTITLS 53 # error This header can be used only when MultiTLS is enabled 54 #endif 55 56 #include "sys_bool_type.h" 57 #include "sys_base_types.h" 58 59 #include "mhd_status_code_int.h" 60 61 #include "mhd_tls_enums.h" 62 #include "mhd_socket_error.h" 63 64 /** 65 * The structure with daemon-specific MultiTLS data 66 */ 67 struct mhd_TlsMultiDaemonData; /* Forward declaration */ 68 69 /** 70 * The structure with connection-specific MultiTLS data 71 */ 72 struct mhd_TlsMultiConnData; /* Forward declaration */ 73 74 union MHD_ConnInfoDynamicTlsSess; /* Forward declaration */ 75 76 struct mhd_StctTlsVersion; /* Forward declaration */ 77 78 /* ** Global initialisation / de-initialisation ** */ 79 80 /** 81 * Globally initialise MultiTLS backend 82 */ 83 84 /** 85 * Perform one-time global initialisation of MultiTLS backend 86 */ 87 MHD_INTERNAL void 88 mhd_tls_multi_global_init_once (void); 89 90 /** 91 * Perform de-initialisation of MultiTLS backend 92 */ 93 MHD_INTERNAL void 94 mhd_tls_multi_global_deinit (void); 95 96 /** 97 * Perform re-initialisation of MultiTLS backend 98 */ 99 MHD_INTERNAL void 100 mhd_tls_multi_global_re_init (void); 101 102 103 /* ** Daemon initialisation / de-initialisation ** */ 104 105 struct MHD_Daemon; /* Forward declaration */ 106 struct DaemonOptions; /* Forward declaration */ 107 108 /** 109 * Check whether MultiTLS backend supports edge-triggered sockets polling 110 * @param s the daemon settings 111 * @return 'true' if the backend supports edge-triggered sockets polling, 112 * 'false' if edge-triggered sockets polling cannot be used 113 */ 114 MHD_INTERNAL bool 115 mhd_tls_multi_is_edge_trigg_supported (struct DaemonOptions *s) 116 MHD_FN_PURE_; 117 118 /** 119 * Allocate and initialise daemon TLS parameters 120 * @param d the daemon handle 121 * @param sk_edge_trigg if 'true' then sockets polling uses edge-triggering 122 * @param s the daemon settings 123 * @param p_d_tls the pointer to variable to set the pointer to 124 * the daemon's TLS settings (allocated by this function) 125 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 126 * error code otherwise 127 */ 128 MHD_INTERNAL mhd_StatusCodeInt 129 mhd_tls_multi_daemon_init (struct MHD_Daemon *restrict d, 130 bool sk_edge_trigg, 131 struct DaemonOptions *restrict s, 132 struct mhd_TlsMultiDaemonData **restrict p_d_tls) 133 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (4); 134 135 /** 136 * De-initialise daemon TLS parameters (and free memory allocated for TLS 137 * settings) 138 * @param d_tls the pointer to the daemon's TLS settings 139 */ 140 MHD_INTERNAL void 141 mhd_tls_multi_daemon_deinit (struct mhd_TlsMultiDaemonData *restrict d_tls) 142 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 143 144 #ifdef mhd_HAVE_TLS_THREAD_CLEANUP 145 /** 146 * Perform clean-up of TLS resources before thread closing. 147 * Must be called before thread is closed, after any use of TLS functions 148 * in the thread, but before de-initialisation of daemon's TLS data. 149 * @param d_tls the pointer to the daemon's TLS settings 150 */ 151 MHD_INTERNAL void 152 mhd_tls_multi_thread_cleanup (struct mhd_TlsMultiDaemonData *restrict d_tls) 153 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 154 155 #else /* ! mhd_HAVE_TLS_THREAD_CLEANUP */ 156 # define mhd_tls_multi_thread_cleanup(d_tls) ((void) 0) 157 #endif /* ! mhd_HAVE_TLS_THREAD_CLEANUP */ 158 159 160 /* ** Connection initialisation / de-initialisation ** */ 161 162 struct mhd_ConnSocket; /* Forward declaration */ 163 164 /** 165 * Get size size of the connection's TLS settings 166 */ 167 MHD_INTERNAL size_t 168 mhd_tls_multi_conn_get_tls_size (struct mhd_TlsMultiDaemonData *restrict d_tls); 169 170 /** 171 * Initialise connection TLS settings 172 * @param d_tls the daemon TLS settings 173 * @param sk data about the socket for the connection 174 * @param[out] c_tls the pointer to the allocated space for 175 * the connection TLS settings 176 * @return 'true' on success, 177 * 'false' otherwise 178 */ 179 MHD_INTERNAL bool 180 mhd_tls_multi_conn_init (const struct mhd_TlsMultiDaemonData *restrict d_tls, 181 struct mhd_ConnSocket *sk, 182 struct mhd_TlsMultiConnData *restrict c_tls) 183 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 184 185 /** 186 * De-initialise connection TLS settings. 187 * The provided pointer is not freed/deallocated. 188 * @param c_tls the initialised connection TLS settings 189 */ 190 MHD_INTERNAL void 191 mhd_tls_multi_conn_deinit (struct mhd_TlsMultiConnData *restrict c_tls) 192 MHD_FN_PAR_NONNULL_ALL_; 193 194 195 /* ** TLS connection establishing ** */ 196 197 /** 198 * Perform TLS handshake 199 * @param c_tls the connection TLS handle 200 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 201 * or other enum mhd_TlsProcedureResult values 202 */ 203 MHD_INTERNAL enum mhd_TlsProcedureResult 204 mhd_tls_multi_conn_handshake (struct mhd_TlsMultiConnData *restrict c_tls) 205 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 206 207 /** 208 * Perform shutdown of TLS layer 209 * @param c_tls the connection TLS handle 210 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 211 * or other enum mhd_TlsProcedureResult values 212 */ 213 MHD_INTERNAL enum mhd_TlsProcedureResult 214 mhd_tls_multi_conn_shutdown (struct mhd_TlsMultiConnData *restrict c_tls) 215 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 216 217 218 /* ** Data sending and receiving over TLS connection ** */ 219 220 /** 221 * Receive the data from the remote side over TLS connection 222 * 223 * @param c_tls the connection TLS handle 224 * @param buf_size the size of the @a buf buffer 225 * @param[out] buf the buffer to fill with the received data 226 * @param[out] received the pointer to variable to get the size of the data 227 * actually put to the @a buffer 228 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 229 * the received size) or socket error 230 */ 231 MHD_INTERNAL enum mhd_SocketError 232 mhd_tls_multi_conn_recv (struct mhd_TlsMultiConnData *restrict c_tls, 233 size_t buf_size, 234 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 235 size_t *restrict received) 236 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 237 238 /** 239 * Check whether any incoming data is pending in the TLS buffers 240 * 241 * @param c_tls the connection TLS handle 242 * @return 'true' if any incoming remote data is already pending (the TLS recv() 243 * call can be performed), 244 * 'false' otherwise 245 */ 246 MHD_INTERNAL bool 247 mhd_tls_multi_conn_has_data_in (struct mhd_TlsMultiConnData *restrict c_tls) 248 MHD_FN_PAR_NONNULL_ALL_; 249 250 /** 251 * Send data to the remote side over TLS connection 252 * 253 * @param c_tls the connection TLS handle 254 * @param buf_size the size of the @a buf (in bytes) 255 * @param buf content of the buffer to send 256 * @param push_data set to 'false' if it is know that the data in the @a buf 257 * is incomplete (message or chunk), 258 * set to 'true' if the data is complete or the final part 259 * @param[out] sent the pointer to get amount of actually sent bytes 260 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 261 * the sent size) or socket error 262 */ 263 MHD_INTERNAL enum mhd_SocketError 264 mhd_tls_multi_conn_send (struct mhd_TlsMultiConnData *restrict c_tls, 265 size_t buf_size, 266 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 267 bool push_data, 268 size_t *restrict sent) 269 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (5); 270 271 272 /* ** TLS connection information ** */ 273 274 /** 275 * Check whether the connection is using "custom transport" functions. 276 * "Custom transport" means that data sending and receiving over system 277 * sockets is performed by MHD callbacks. 278 * When "custom transport" is used, backend TLS send/recv functions are: 279 * * perform additional syscalls (socket options) for data pushing/buffering, 280 * * change socket states like corked, NO_DELAY, both by syscalls and in 281 * MHD socket metadata, 282 * * set disconnect error from the system reported socket error. 283 * 284 * @param c_tls the connection TLS handle 285 * @return boolean 'true' if custom transport is used, 286 * boolean 'false' otherwise 287 */ 288 MHD_INTERNAL bool 289 mhd_tls_multi_conn_has_cstm_tr (struct mhd_TlsMultiConnData *restrict c_tls) 290 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 291 292 /** 293 * Get the TLS session used in connection 294 * @param c_tls the connection TLS handle 295 * @param tls_sess_out the pointer to variable to be set to the TLS session 296 * handle 297 */ 298 MHD_INTERNAL void 299 mhd_tls_multi_conn_get_tls_sess ( 300 struct mhd_TlsMultiConnData *restrict c_tls, 301 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 302 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 303 304 /** 305 * Get the TLS version used in connection 306 * @param c_tls the connection TLS handle 307 * @param tls_ver_out the pointer to variable to be set to the TLS version 308 * @return 'true' is TLS version information set successfully, 309 * 'false' if TLS version information cannot be obtained or mapped 310 */ 311 MHD_INTERNAL bool 312 mhd_tls_multi_conn_get_tls_ver (struct mhd_TlsMultiConnData *restrict c_tls, 313 struct mhd_StctTlsVersion *restrict tls_ver_out) 314 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 315 316 /** 317 * Get a protocol selected by ALPN 318 * @param c_tls the connection TLS handle 319 * @return the selected protocol code 320 */ 321 MHD_INTERNAL enum mhd_TlsAlpnProt 322 mhd_tls_multi_conn_get_alpn_prot (struct mhd_TlsMultiConnData *restrict c_tls) 323 MHD_FN_PAR_NONNULL_ALL_; 324 325 #endif /* ! MHD_TLS_MULTI_FUNCS_H */