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