tls_open_funcs.h (16789B)
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 when OpenSSL is used 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_tls_cred_ptr.h" 66 #include "mhd_socket_error.h" 67 68 /** 69 * The structure with daemon-specific OpenSSL data 70 */ 71 struct mhd_TlsOpenDaemonData; /* Forward declaration */ 72 73 /** 74 * The structure with connection-specific OpenSSL data 75 */ 76 struct mhd_TlsOpenConnData; /* Forward declaration */ 77 78 union MHD_ConnInfoDynamicTlsSess; /* Forward declaration */ 79 80 struct mhd_StctTlsVersion; /* Forward declaration */ 81 82 83 /* ** Global initialisation / de-initialisation ** */ 84 85 /** 86 * Globally initialise OpenSSL backend. 87 * Once initialised, this backend cannot be de-initialised. 88 */ 89 MHD_INTERNAL void 90 mhd_tls_open_global_init_once (void); 91 92 /* No-op for OpenSSL backend */ 93 #define mhd_tls_open_global_re_init() ((void) 0) 94 95 /* No-op for OpenSSL backend */ 96 #define mhd_tls_open_global_deinit() ((void) 0) 97 98 /** 99 * Check whether OpenSSL backend was successfully initialised globally 100 * @return 'true' if backend has been successfully initialised, 101 * 'false' if backend cannot be used 102 */ 103 MHD_INTERNAL bool 104 mhd_tls_open_is_inited_fine (void) 105 MHD_FN_PURE_; 106 107 108 /* ** Daemon initialisation / de-initialisation ** */ 109 110 struct MHD_Daemon; /* Forward declaration */ 111 struct DaemonOptions; /* Forward declaration */ 112 113 /** 114 * Check whether OpenSSL backend supports edge-triggered sockets polling 115 * @param s the daemon settings 116 * @return 'true' if the backend supports edge-triggered sockets polling, 117 * 'false' if edge-triggered sockets polling cannot be used 118 */ 119 #define mhd_tls_open_is_edge_trigg_supported(s) (! ! 0) 120 121 #ifdef mhd_HAVE_TLS_ACME 122 /** 123 * Check whether OpenSSL backend supports ACME ALPN challenge protocol 124 * @param s the daemon settings 125 * @return 'true' if the backend supports ACME ALPN challenge protocol, 126 * 'false' otherwise 127 */ 128 # ifdef mhd_HAVE_OPENSSL_ACME 129 # define mhd_tls_open_is_acme_alpn_supported(s) ((void)(s), (!0)) 130 # else /* ! mhd_HAVE_OPENSSL_ACME */ 131 # define mhd_tls_open_is_acme_alpn_supported(s) ((void)(s), (!!0)) 132 # endif /* ! mhd_HAVE_OPENSSL_ACME */ 133 #endif /* mhd_HAVE_TLS_ACME */ 134 135 /** 136 * Allocate and initialise daemon TLS parameters 137 * @param d the daemon handle 138 * @param sk_edge_trigg if 'true' then sockets polling uses edge-triggering 139 * @param s the daemon settings 140 * @param p_d_tls the pointer to variable to set the pointer to 141 * the daemon's TLS settings (allocated by this function) 142 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 143 * error code otherwise 144 */ 145 MHD_INTERNAL mhd_StatusCodeInt 146 mhd_tls_open_daemon_init (struct MHD_Daemon *restrict d, 147 bool sk_edge_trigg, 148 struct DaemonOptions *restrict s, 149 struct mhd_TlsOpenDaemonData **restrict p_d_tls) 150 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (4); 151 152 /** 153 * De-initialise daemon TLS parameters (and free memory allocated for TLS 154 * settings) 155 * @param d_tls the pointer to the daemon's TLS settings 156 */ 157 MHD_INTERNAL void 158 mhd_tls_open_daemon_deinit (struct mhd_TlsOpenDaemonData *restrict d_tls) 159 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 160 161 /** 162 * Perform clean-up of TLS resources before thread closing. 163 * Must be called before thread is closed, after any use of TLS functions 164 * in the thread, but before de-initialisation of daemon's TLS data. 165 * @param d_tls the pointer to the daemon's TLS settings 166 */ 167 MHD_INTERNAL void 168 mhd_tls_open_thread_cleanup (struct mhd_TlsOpenDaemonData *restrict d_tls) 169 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 170 171 /* ** Credentials creation / destruction ** */ 172 173 #ifdef mhd_HAVE_OPENSSL_ACME 174 /** 175 * Create TLS credentials from the provided certificate and key data. 176 * 177 * Created credentials must be destroyed with #mhd_tls_open_cred_destroy_nodmn() 178 * function before de-initialisation of the daemon's TLS settings. 179 * 180 * @param d_tls the pointer to the daemon's TLS settings 181 * @param[out] pp_cred the backend-specific credentials pointer to initialise; 182 * the OpenSSL member is set to the allocated credentials on 183 * success and to NULL on failure 184 * @param cert_len the length of the @p cert buffer, not including the 185 * zero-termination byte, 186 * must not be zero 187 * @param cert the certificates data in PEM format, zero-terminated; 188 * the first certificate is the end-entity certificate, any 189 * following certificates form the chain of the signing 190 * certificates 191 * @param key_len the length of the @p key buffer, not including the 192 * zero-termination byte, 193 * must not be zero 194 * @param key the private key data in PEM format, zero-terminated 195 * @param pass_len the length of the @p pass buffer, not including the 196 * zero-termination byte, 197 * must be zero if the @p pass is NULL 198 * @param pass the password for the private key, zero-terminated, 199 * may be NULL if the private key is not password-protected 200 * @return #mhd_TLS_CRED_CREATE_OK on success, 201 * other enum mhd_TlsCredCreateResult values on failure 202 */ 203 MHD_INTERNAL enum mhd_TlsCredCreateResult 204 mhd_tls_open_cred_create (struct mhd_TlsOpenDaemonData *restrict d_tls, 205 union mhd_TlsCredDataPtr *restrict pp_cred, 206 size_t cert_len, 207 const char *restrict cert, 208 size_t key_len, 209 const char *restrict key, 210 size_t pass_len, 211 const char *restrict pass) 212 MHD_FN_MUST_CHECK_RESULT_ 213 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (2) 214 MHD_FN_PAR_NONNULL_ (4) MHD_FN_PAR_NONNULL_ (6) 215 MHD_FN_PAR_NONNULL_IF_NONZERO_ (8, 7) 216 MHD_FN_PAR_OUT_ (2) 217 MHD_FN_PAR_IN_SIZE_ (4, 3) MHD_FN_PAR_IN_SIZE_ (6, 5) 218 MHD_FN_PAR_IN_SIZE_ (8, 7) 219 MHD_FN_PAR_CSTR_ (4) MHD_FN_PAR_CSTR_ (6) MHD_FN_PAR_CSTR_ (8); 220 221 /** 222 * Release TLS credentials and free the allocated memory. 223 * 224 * The certificate, the private key and the certificates chain are released. 225 * The objects still used by any TLS session or context stay alive as OpenSSL 226 * holds its own references for them. 227 * 228 * @param cred the backend-specific credentials pointer to release; the OpenSSL 229 * member must be non-NULL 230 */ 231 MHD_INTERNAL void 232 mhd_tls_open_cred_destroy_nodmn (union mhd_TlsCredDataPtr cred); 233 234 #else /* ! mhd_HAVE_OPENSSL_ACME */ 235 # define mhd_tls_open_cred_create(d_tls, pp_c, c_l, c, k_l, k, ps_l, ps) \ 236 ((void)d_tls, (void)pp_c, (void)c_l, (void)c, \ 237 (void)k_l, (void)k, (void)ps_l, (void)ps, \ 238 mhd_TLS_CRED_CREATE_UNSUPPORTED) 239 # define mhd_tls_open_cred_destroy_nodmn(cred) ((void)(cred)) 240 #endif /* ! mhd_HAVE_OPENSSL_ACME */ 241 242 /** 243 * Release TLS credentials and free the allocated memory when no references 244 * remain. 245 * 246 * @param d_tls the pointer to the daemon's TLS settings 247 * @param cred the backend-specific credentials pointer to release; the OpenSSL 248 * member must be non-NULL 249 */ 250 #define mhd_tls_open_cred_destroy(d_tls, cred) \ 251 do { (void)(d_tls); \ 252 mhd_tls_open_cred_destroy_nodmn ((cred)); } while (0) 253 254 /* ** Connection initialisation / de-initialisation ** */ 255 256 struct mhd_ConnSocket; /* Forward declaration */ 257 258 /** 259 * Get size size of the connection's TLS settings 260 */ 261 MHD_INTERNAL size_t 262 mhd_tls_open_conn_get_tls_size_v (void); 263 264 /** 265 * Get size size of the connection's TLS settings 266 * @param d_tls the pointer to the daemon's TLS settings 267 */ 268 #define mhd_tls_open_conn_get_tls_size(d_tls) \ 269 mhd_tls_open_conn_get_tls_size_v () 270 271 /** 272 * Initialise connection TLS settings 273 * @param d_tls the daemon TLS settings 274 * @param sk data about the socket for the connection 275 * @param[out] c_tls the pointer to the allocated space for 276 * the connection TLS settings 277 * @return 'true' on success, 278 * 'false' otherwise 279 */ 280 MHD_INTERNAL bool 281 mhd_tls_open_conn_init (const struct mhd_TlsOpenDaemonData *restrict d_tls, 282 const struct mhd_ConnSocket *sk, 283 struct mhd_TlsOpenConnData *restrict c_tls) 284 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 285 286 /** 287 * De-initialise connection TLS settings. 288 * The provided pointer is not freed/deallocated. 289 * @param c_tls the initialised connection TLS settings 290 */ 291 MHD_INTERNAL void 292 mhd_tls_open_conn_deinit (struct mhd_TlsOpenConnData *restrict c_tls) 293 MHD_FN_PAR_NONNULL_ALL_; 294 295 296 /* ** TLS connection establishing ** */ 297 298 /** 299 * Perform TLS handshake 300 * @param c_tls the connection TLS handle 301 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 302 * or other enum mhd_TlsProcedureResult values 303 */ 304 MHD_INTERNAL enum mhd_TlsProcedureResult 305 mhd_tls_open_conn_handshake (struct mhd_TlsOpenConnData *restrict c_tls) 306 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 307 308 /** 309 * Perform shutdown of TLS layer 310 * @param c_tls the connection TLS handle 311 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 312 * or other enum mhd_TlsProcedureResult values 313 */ 314 MHD_INTERNAL enum mhd_TlsProcedureResult 315 mhd_tls_open_conn_shutdown (struct mhd_TlsOpenConnData *restrict c_tls) 316 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 317 318 319 /* ** Data sending and receiving over TLS connection ** */ 320 321 /** 322 * Receive the data from the remote side over TLS connection 323 * 324 * @param c_tls the connection TLS handle 325 * @param buf_size the size of the @a buf buffer 326 * @param[out] buf the buffer to fill with the received data 327 * @param[out] received the pointer to variable to get the size of the data 328 * actually put to the @a buffer 329 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 330 * the received size) or socket error 331 */ 332 MHD_INTERNAL enum mhd_SocketError 333 mhd_tls_open_conn_recv (struct mhd_TlsOpenConnData *restrict c_tls, 334 size_t buf_size, 335 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 336 size_t *restrict received) 337 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 338 339 /** 340 * Check whether any incoming data is pending in the TLS buffers 341 * 342 * @param c_tls the connection TLS handle 343 * @return 'true' if any incoming remote data is already pending (the TLS recv() 344 * call can be performed), 345 * 'false' otherwise 346 */ 347 MHD_INTERNAL bool 348 mhd_tls_open_conn_has_data_in (struct mhd_TlsOpenConnData *restrict c_tls) 349 MHD_FN_PAR_NONNULL_ALL_; 350 351 /** 352 * Send data to the remote side over TLS connection 353 * 354 * @param c_tls the connection TLS handle 355 * @param buf_size the size of the @a buf (in bytes) 356 * @param buf content of the buffer to send 357 * @param[out] sent the pointer to get amount of actually sent bytes 358 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 359 * the sent size) or socket error 360 */ 361 MHD_INTERNAL enum mhd_SocketError 362 mhd_tls_open_conn_send4 (struct mhd_TlsOpenConnData *restrict c_tls, 363 size_t buf_size, 364 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 365 size_t *restrict sent) 366 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 367 368 /** 369 * Send data to the remote side over TLS connection 370 * 371 * @param c_tls the connection TLS handle 372 * @param buf_size the size of the @a buf (in bytes) 373 * @param buf content of the buffer to send 374 * @param push_data set to 'false' if it is know that the data in the @a buf 375 * is incomplete (message or chunk), 376 * set to 'true' if the data is complete or the final part 377 * @param[out] sent the pointer to get amount of actually sent bytes 378 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 379 * the sent size) or socket error 380 */ 381 #define mhd_tls_open_conn_send(c_tls, buf_size, buf, push_data, sent) \ 382 mhd_tls_open_conn_send4 (c_tls,buf_size,buf,sent) 383 384 385 /* ** TLS connection information ** */ 386 387 /** 388 * Check whether the connection is using "custom transport" functions. 389 * "Custom transport" means that data sending and receiving over system 390 * sockets is performed by MHD callbacks. 391 * When "custom transport" is used, backend TLS send/recv functions are: 392 * * perform additional syscalls (socket options) for data pushing/buffering, 393 * * change socket states like corked, NO_DELAY, both by syscalls and in 394 * MHD socket metadata, 395 * * set disconnect error from the system reported socket error. 396 * 397 * @param c_tls the connection TLS handle 398 * @return boolean 'true' if custom transport is used, 399 * boolean 'false' otherwise 400 */ 401 #define mhd_tls_open_conn_has_cstm_tr(c_tls) (! ! 0) 402 403 /** 404 * Get the TLS session used in connection 405 * @param c_tls the connection TLS handle 406 * @param tls_sess_out the pointer to variable to be set to the TLS session 407 * handle 408 */ 409 MHD_INTERNAL void 410 mhd_tls_open_conn_get_tls_sess ( 411 struct mhd_TlsOpenConnData *restrict c_tls, 412 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 413 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 414 415 /** 416 * Get the TLS version used in connection 417 * @param c_tls the connection TLS handle 418 * @param tls_ver_out the pointer to variable to be set to the TLS version 419 * @return always 'true' 420 */ 421 MHD_INTERNAL bool 422 mhd_tls_open_conn_get_tls_ver (struct mhd_TlsOpenConnData *restrict c_tls, 423 struct mhd_StctTlsVersion *restrict tls_ver_out) 424 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 425 426 /** 427 * Get a protocol selected by ALPN 428 * @param c_tls the connection TLS handle 429 * @return the selected protocol code 430 */ 431 MHD_INTERNAL enum mhd_TlsAlpnProt 432 mhd_tls_open_conn_get_alpn_prot (struct mhd_TlsOpenConnData *restrict c_tls) 433 MHD_FN_PAR_NONNULL_ALL_; 434 435 #ifdef mhd_HAVE_TLS_ACME 436 /** 437 * Check whether the connection is ACME ALPN challenge connection 438 * @param c_tls the connection TLS handle 439 * @return 'true' if the connection is ACME ALPN challenge connection, 440 * 'false' otherwise 441 */ 442 # ifdef mhd_HAVE_OPENSSL_ACME 443 MHD_INTERNAL bool 444 mhd_tls_open_conn_is_acme (struct mhd_TlsOpenConnData *restrict c_tls) 445 MHD_FN_PAR_NONNULL_ALL_; 446 447 # else /* ! mhd_HAVE_OPENSSL_ACME */ 448 # define mhd_tls_open_conn_is_acme(c_tls) (((void)(c_tls)), (!!0)) 449 # endif /* ! mhd_HAVE_OPENSSL_ACME */ 450 #endif /* mhd_HAVE_TLS_ACME */ 451 452 #endif /* ! MHD_TLS_OPEN_FUNCS_H */