tls_multi_funcs.h (14913B)
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 #ifdef mhd_HAVE_TLS_ACME 119 /** 120 * Check whether GnuTLS backend supports ACME ALPN challenge protocol 121 * @param s the daemon settings 122 * @return 'true' if the backend supports ACME ALPN challenge protocol, 123 * 'false' otherwise 124 */ 125 MHD_INTERNAL bool 126 mhd_tls_multi_is_acme_alpn_supported (struct DaemonOptions *s) 127 MHD_FN_PURE_; 128 129 #endif /* mhd_HAVE_TLS_ACME */ 130 131 /** 132 * Allocate and initialise daemon TLS parameters 133 * @param d the daemon handle 134 * @param sk_edge_trigg if 'true' then sockets polling uses edge-triggering 135 * @param s the daemon settings 136 * @param p_d_tls the pointer to variable to set the pointer to 137 * the daemon's TLS settings (allocated by this function) 138 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 139 * error code otherwise 140 */ 141 MHD_INTERNAL mhd_StatusCodeInt 142 mhd_tls_multi_daemon_init (struct MHD_Daemon *restrict d, 143 bool sk_edge_trigg, 144 struct DaemonOptions *restrict s, 145 struct mhd_TlsMultiDaemonData **restrict p_d_tls) 146 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (4); 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_multi_daemon_deinit (struct mhd_TlsMultiDaemonData *restrict d_tls) 155 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 156 157 #ifdef mhd_HAVE_TLS_THREAD_CLEANUP 158 /** 159 * Perform clean-up of TLS resources before thread closing. 160 * Must be called before thread is closed, after any use of TLS functions 161 * in the thread, but before de-initialisation of daemon's TLS data. 162 * @param d_tls the pointer to the daemon's TLS settings 163 */ 164 MHD_INTERNAL void 165 mhd_tls_multi_thread_cleanup (struct mhd_TlsMultiDaemonData *restrict d_tls) 166 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 167 168 #else /* ! mhd_HAVE_TLS_THREAD_CLEANUP */ 169 # define mhd_tls_multi_thread_cleanup(d_tls) ((void) 0) 170 #endif /* ! mhd_HAVE_TLS_THREAD_CLEANUP */ 171 172 /* ** Credentials creation / destruction ** */ 173 174 #ifdef mhd_HAVE_TLS_ACME 175 /** 176 * Create TLS credentials from the provided certificate and key data 177 * 178 * Created credentials must be destroyed with #mhd_tls_gnu_cred_destroy_nodmn() 179 * function before de-initialisation of the daemon's TLS settings. 180 * 181 * @param d_tls the pointer to the daemon's TLS settings 182 * @param[out] pp_cred the backend-specific credentials pointer to initialise; 183 * the GnuTLS member is set to the allocated credentials on 184 * success and to NULL on failure 185 * @param cert_len the length of the @p cert buffer, not including the 186 * zero-termination byte, 187 * must not be zero 188 * @param cert the certificate data in PEM format, zero-terminated 189 * @param key_len the length of the @p key buffer, not including the 190 * zero-termination byte, 191 * must not be zero 192 * @param key the private key data in PEM format, zero-terminated 193 * @param pass_len the length of the @p pass buffer, not including the 194 * zero-termination byte, 195 * must be zero if the @p pass is NULL 196 * @param pass the password for the private key, zero-terminated, 197 * may be NULL if the private key is not password-protected 198 * @return #mhd_TLS_CRED_CREATE_OK on success, 199 * other enum mhd_TlsCredCreateResult values on failure 200 */ 201 MHD_INTERNAL enum mhd_TlsCredCreateResult 202 mhd_tls_multi_cred_create (struct mhd_TlsMultiDaemonData *restrict d_tls, 203 union mhd_TlsCredDataPtr *restrict pp_cred, 204 size_t cert_len, 205 const char *restrict cert, 206 size_t key_len, 207 const char *restrict key, 208 size_t pass_len, 209 const char *restrict pass) 210 MHD_FN_MUST_CHECK_RESULT_ 211 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (2) 212 MHD_FN_PAR_NONNULL_ (4) MHD_FN_PAR_NONNULL_ (6) 213 MHD_FN_PAR_NONNULL_IF_NONZERO_ (8, 7) 214 MHD_FN_PAR_OUT_ (2) 215 MHD_FN_PAR_IN_SIZE_ (4, 3) MHD_FN_PAR_IN_SIZE_ (6, 5) 216 MHD_FN_PAR_IN_SIZE_ (8, 7) 217 MHD_FN_PAR_CSTR_ (4) MHD_FN_PAR_CSTR_ (6) MHD_FN_PAR_CSTR_ (8); 218 219 /** 220 * Release TLS credentials and free the allocated memory when no references 221 * remain. 222 * 223 * @param cred the backend-specific credentials pointer to release; the GnuTLS 224 * member must be non-NULL 225 */ 226 MHD_INTERNAL void 227 mhd_tls_multi_cred_destroy (struct mhd_TlsMultiDaemonData *restrict d_tls, 228 union mhd_TlsCredDataPtr cred) 229 MHD_FN_PAR_NONNULL_ALL_; 230 231 #endif /* mhd_HAVE_TLS_ACME */ 232 233 /* ** Connection initialisation / de-initialisation ** */ 234 235 struct mhd_ConnSocket; /* Forward declaration */ 236 237 /** 238 * Get size of the connection's TLS settings 239 */ 240 MHD_INTERNAL size_t 241 mhd_tls_multi_conn_get_tls_size (struct mhd_TlsMultiDaemonData *restrict d_tls); 242 243 /** 244 * Initialise connection TLS settings 245 * @param d_tls the daemon TLS settings 246 * @param sk data about the socket for the connection 247 * @param[out] c_tls the pointer to the allocated space for 248 * the connection TLS settings 249 * @return 'true' on success, 250 * 'false' otherwise 251 */ 252 MHD_INTERNAL bool 253 mhd_tls_multi_conn_init (const struct mhd_TlsMultiDaemonData *restrict d_tls, 254 struct mhd_ConnSocket *sk, 255 struct mhd_TlsMultiConnData *restrict c_tls) 256 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 257 258 /** 259 * De-initialise connection TLS settings. 260 * The provided pointer is not freed/deallocated. 261 * @param c_tls the initialised connection TLS settings 262 */ 263 MHD_INTERNAL void 264 mhd_tls_multi_conn_deinit (struct mhd_TlsMultiConnData *restrict c_tls) 265 MHD_FN_PAR_NONNULL_ALL_; 266 267 268 /* ** TLS connection establishing ** */ 269 270 /** 271 * Perform TLS handshake 272 * @param c_tls the connection TLS handle 273 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 274 * or other enum mhd_TlsProcedureResult values 275 */ 276 MHD_INTERNAL enum mhd_TlsProcedureResult 277 mhd_tls_multi_conn_handshake (struct mhd_TlsMultiConnData *restrict c_tls) 278 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 279 280 /** 281 * Perform shutdown of TLS layer 282 * @param c_tls the connection TLS handle 283 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 284 * or other enum mhd_TlsProcedureResult values 285 */ 286 MHD_INTERNAL enum mhd_TlsProcedureResult 287 mhd_tls_multi_conn_shutdown (struct mhd_TlsMultiConnData *restrict c_tls) 288 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 289 290 291 /* ** Data sending and receiving over TLS connection ** */ 292 293 /** 294 * Receive the data from the remote side over TLS connection 295 * 296 * @param c_tls the connection TLS handle 297 * @param buf_size the size of the @a buf buffer 298 * @param[out] buf the buffer to fill with the received data 299 * @param[out] received the pointer to variable to get the size of the data 300 * actually put to the @a buffer 301 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 302 * the received size) or socket error 303 */ 304 MHD_INTERNAL enum mhd_SocketError 305 mhd_tls_multi_conn_recv (struct mhd_TlsMultiConnData *restrict c_tls, 306 size_t buf_size, 307 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 308 size_t *restrict received) 309 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 310 311 /** 312 * Check whether any incoming data is pending in the TLS buffers 313 * 314 * @param c_tls the connection TLS handle 315 * @return 'true' if any incoming remote data is already pending (the TLS recv() 316 * call can be performed), 317 * 'false' otherwise 318 */ 319 MHD_INTERNAL bool 320 mhd_tls_multi_conn_has_data_in (struct mhd_TlsMultiConnData *restrict c_tls) 321 MHD_FN_PAR_NONNULL_ALL_; 322 323 /** 324 * Send data to the remote side over TLS connection 325 * 326 * @param c_tls the connection TLS handle 327 * @param buf_size the size of the @a buf (in bytes) 328 * @param buf content of the buffer to send 329 * @param push_data set to 'false' if it is know that the data in the @a buf 330 * is incomplete (message or chunk), 331 * set to 'true' if the data is complete or the final part 332 * @param[out] sent the pointer to get amount of actually sent bytes 333 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 334 * the sent size) or socket error 335 */ 336 MHD_INTERNAL enum mhd_SocketError 337 mhd_tls_multi_conn_send (struct mhd_TlsMultiConnData *restrict c_tls, 338 size_t buf_size, 339 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 340 bool push_data, 341 size_t *restrict sent) 342 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (5); 343 344 345 /* ** TLS connection information ** */ 346 347 /** 348 * Check whether the connection is using "custom transport" functions. 349 * "Custom transport" means that data sending and receiving over system 350 * sockets is performed by MHD callbacks. 351 * When "custom transport" is used, backend TLS send/recv functions are: 352 * * perform additional syscalls (socket options) for data pushing/buffering, 353 * * change socket states like corked, NO_DELAY, both by syscalls and in 354 * MHD socket metadata, 355 * * set disconnect error from the system reported socket error. 356 * 357 * @param c_tls the connection TLS handle 358 * @return boolean 'true' if custom transport is used, 359 * boolean 'false' otherwise 360 */ 361 MHD_INTERNAL bool 362 mhd_tls_multi_conn_has_cstm_tr (struct mhd_TlsMultiConnData *restrict c_tls) 363 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 364 365 /** 366 * Get the TLS session used in connection 367 * @param c_tls the connection TLS handle 368 * @param tls_sess_out the pointer to variable to be set to the TLS session 369 * handle 370 */ 371 MHD_INTERNAL void 372 mhd_tls_multi_conn_get_tls_sess ( 373 struct mhd_TlsMultiConnData *restrict c_tls, 374 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 375 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 376 377 /** 378 * Get the TLS version used in connection 379 * @param c_tls the connection TLS handle 380 * @param tls_ver_out the pointer to variable to be set to the TLS version 381 * @return 'true' is TLS version information set successfully, 382 * 'false' if TLS version information cannot be obtained or mapped 383 */ 384 MHD_INTERNAL bool 385 mhd_tls_multi_conn_get_tls_ver (struct mhd_TlsMultiConnData *restrict c_tls, 386 struct mhd_StctTlsVersion *restrict tls_ver_out) 387 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 388 389 /** 390 * Get a protocol selected by ALPN 391 * @param c_tls the connection TLS handle 392 * @return the selected protocol code 393 */ 394 MHD_INTERNAL enum mhd_TlsAlpnProt 395 mhd_tls_multi_conn_get_alpn_prot (struct mhd_TlsMultiConnData *restrict c_tls) 396 MHD_FN_PAR_NONNULL_ALL_; 397 398 399 #ifdef mhd_HAVE_TLS_ACME 400 /** 401 * Check whether the connection is ACME ALPN challenge connection 402 * @param c_tls the connection TLS handle 403 * @return 'true' if the connection is ACME ALPN challenge connection, 404 * 'false' otherwise 405 */ 406 MHD_INTERNAL bool 407 mhd_tls_multi_conn_is_acme (struct mhd_TlsMultiConnData *restrict c_tls) 408 MHD_FN_PAR_NONNULL_ALL_; 409 410 #endif /* mhd_HAVE_TLS_ACME */ 411 412 #endif /* ! MHD_TLS_MULTI_FUNCS_H */