tls_multi_funcs.h (14875B)
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_OUT_ (2) 214 MHD_FN_PAR_IN_SIZE_ (4, 3) MHD_FN_PAR_IN_SIZE_ (6, 5) 215 MHD_FN_PAR_IN_SIZE_ (8, 7) 216 MHD_FN_PAR_CSTR_ (4) MHD_FN_PAR_CSTR_ (6) MHD_FN_PAR_CSTR_ (8); 217 218 /** 219 * Release TLS credentials and free the allocated memory when no references 220 * remain. 221 * 222 * @param cred the backend-specific credentials pointer to release; the GnuTLS 223 * member must be non-NULL 224 */ 225 MHD_INTERNAL void 226 mhd_tls_multi_cred_destroy (struct mhd_TlsMultiDaemonData *restrict d_tls, 227 union mhd_TlsCredDataPtr cred) 228 MHD_FN_PAR_NONNULL_ALL_; 229 230 #endif /* mhd_HAVE_TLS_ACME */ 231 232 /* ** Connection initialisation / de-initialisation ** */ 233 234 struct mhd_ConnSocket; /* Forward declaration */ 235 236 /** 237 * Get size of the connection's TLS settings 238 */ 239 MHD_INTERNAL size_t 240 mhd_tls_multi_conn_get_tls_size (struct mhd_TlsMultiDaemonData *restrict d_tls); 241 242 /** 243 * Initialise connection TLS settings 244 * @param d_tls the daemon TLS settings 245 * @param sk data about the socket for the connection 246 * @param[out] c_tls the pointer to the allocated space for 247 * the connection TLS settings 248 * @return 'true' on success, 249 * 'false' otherwise 250 */ 251 MHD_INTERNAL bool 252 mhd_tls_multi_conn_init (const struct mhd_TlsMultiDaemonData *restrict d_tls, 253 struct mhd_ConnSocket *sk, 254 struct mhd_TlsMultiConnData *restrict c_tls) 255 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 256 257 /** 258 * De-initialise connection TLS settings. 259 * The provided pointer is not freed/deallocated. 260 * @param c_tls the initialised connection TLS settings 261 */ 262 MHD_INTERNAL void 263 mhd_tls_multi_conn_deinit (struct mhd_TlsMultiConnData *restrict c_tls) 264 MHD_FN_PAR_NONNULL_ALL_; 265 266 267 /* ** TLS connection establishing ** */ 268 269 /** 270 * Perform TLS handshake 271 * @param c_tls the connection TLS handle 272 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 273 * or other enum mhd_TlsProcedureResult values 274 */ 275 MHD_INTERNAL enum mhd_TlsProcedureResult 276 mhd_tls_multi_conn_handshake (struct mhd_TlsMultiConnData *restrict c_tls) 277 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 278 279 /** 280 * Perform shutdown of TLS layer 281 * @param c_tls the connection TLS handle 282 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 283 * or other enum mhd_TlsProcedureResult values 284 */ 285 MHD_INTERNAL enum mhd_TlsProcedureResult 286 mhd_tls_multi_conn_shutdown (struct mhd_TlsMultiConnData *restrict c_tls) 287 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 288 289 290 /* ** Data sending and receiving over TLS connection ** */ 291 292 /** 293 * Receive the data from the remote side over TLS connection 294 * 295 * @param c_tls the connection TLS handle 296 * @param buf_size the size of the @a buf buffer 297 * @param[out] buf the buffer to fill with the received data 298 * @param[out] received the pointer to variable to get the size of the data 299 * actually put to the @a buffer 300 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 301 * the received size) or socket error 302 */ 303 MHD_INTERNAL enum mhd_SocketError 304 mhd_tls_multi_conn_recv (struct mhd_TlsMultiConnData *restrict c_tls, 305 size_t buf_size, 306 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 307 size_t *restrict received) 308 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 309 310 /** 311 * Check whether any incoming data is pending in the TLS buffers 312 * 313 * @param c_tls the connection TLS handle 314 * @return 'true' if any incoming remote data is already pending (the TLS recv() 315 * call can be performed), 316 * 'false' otherwise 317 */ 318 MHD_INTERNAL bool 319 mhd_tls_multi_conn_has_data_in (struct mhd_TlsMultiConnData *restrict c_tls) 320 MHD_FN_PAR_NONNULL_ALL_; 321 322 /** 323 * Send data to the remote side over TLS connection 324 * 325 * @param c_tls the connection TLS handle 326 * @param buf_size the size of the @a buf (in bytes) 327 * @param buf content of the buffer to send 328 * @param push_data set to 'false' if it is know that the data in the @a buf 329 * is incomplete (message or chunk), 330 * set to 'true' if the data is complete or the final part 331 * @param[out] sent the pointer to get amount of actually sent bytes 332 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 333 * the sent size) or socket error 334 */ 335 MHD_INTERNAL enum mhd_SocketError 336 mhd_tls_multi_conn_send (struct mhd_TlsMultiConnData *restrict c_tls, 337 size_t buf_size, 338 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 339 bool push_data, 340 size_t *restrict sent) 341 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (5); 342 343 344 /* ** TLS connection information ** */ 345 346 /** 347 * Check whether the connection is using "custom transport" functions. 348 * "Custom transport" means that data sending and receiving over system 349 * sockets is performed by MHD callbacks. 350 * When "custom transport" is used, backend TLS send/recv functions are: 351 * * perform additional syscalls (socket options) for data pushing/buffering, 352 * * change socket states like corked, NO_DELAY, both by syscalls and in 353 * MHD socket metadata, 354 * * set disconnect error from the system reported socket error. 355 * 356 * @param c_tls the connection TLS handle 357 * @return boolean 'true' if custom transport is used, 358 * boolean 'false' otherwise 359 */ 360 MHD_INTERNAL bool 361 mhd_tls_multi_conn_has_cstm_tr (struct mhd_TlsMultiConnData *restrict c_tls) 362 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 363 364 /** 365 * Get the TLS session used in connection 366 * @param c_tls the connection TLS handle 367 * @param tls_sess_out the pointer to variable to be set to the TLS session 368 * handle 369 */ 370 MHD_INTERNAL void 371 mhd_tls_multi_conn_get_tls_sess ( 372 struct mhd_TlsMultiConnData *restrict c_tls, 373 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 374 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 375 376 /** 377 * Get the TLS version used in connection 378 * @param c_tls the connection TLS handle 379 * @param tls_ver_out the pointer to variable to be set to the TLS version 380 * @return 'true' is TLS version information set successfully, 381 * 'false' if TLS version information cannot be obtained or mapped 382 */ 383 MHD_INTERNAL bool 384 mhd_tls_multi_conn_get_tls_ver (struct mhd_TlsMultiConnData *restrict c_tls, 385 struct mhd_StctTlsVersion *restrict tls_ver_out) 386 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 387 388 /** 389 * Get a protocol selected by ALPN 390 * @param c_tls the connection TLS handle 391 * @return the selected protocol code 392 */ 393 MHD_INTERNAL enum mhd_TlsAlpnProt 394 mhd_tls_multi_conn_get_alpn_prot (struct mhd_TlsMultiConnData *restrict c_tls) 395 MHD_FN_PAR_NONNULL_ALL_; 396 397 398 #ifdef mhd_HAVE_TLS_ACME 399 /** 400 * Check whether the connection is ACME ALPN challenge connection 401 * @param c_tls the connection TLS handle 402 * @return 'true' if the connection is ACME ALPN challenge connection, 403 * 'false' otherwise 404 */ 405 MHD_INTERNAL bool 406 mhd_tls_multi_conn_is_acme (struct mhd_TlsMultiConnData *restrict c_tls) 407 MHD_FN_PAR_NONNULL_ALL_; 408 409 #endif /* mhd_HAVE_TLS_ACME */ 410 411 #endif /* ! MHD_TLS_MULTI_FUNCS_H */