tls_open_funcs.h (16751B)
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_OUT_ (2) 216 MHD_FN_PAR_IN_SIZE_ (4, 3) MHD_FN_PAR_IN_SIZE_ (6, 5) 217 MHD_FN_PAR_IN_SIZE_ (8, 7) 218 MHD_FN_PAR_CSTR_ (4) MHD_FN_PAR_CSTR_ (6) MHD_FN_PAR_CSTR_ (8); 219 220 /** 221 * Release TLS credentials and free the allocated memory. 222 * 223 * The certificate, the private key and the certificates chain are released. 224 * The objects still used by any TLS session or context stay alive as OpenSSL 225 * holds its own references for them. 226 * 227 * @param cred the backend-specific credentials pointer to release; the OpenSSL 228 * member must be non-NULL 229 */ 230 MHD_INTERNAL void 231 mhd_tls_open_cred_destroy_nodmn (union mhd_TlsCredDataPtr cred); 232 233 #else /* ! mhd_HAVE_OPENSSL_ACME */ 234 # define mhd_tls_open_cred_create(d_tls, pp_c, c_l, c, k_l, k, ps_l, ps) \ 235 ((void)d_tls, (void)pp_c, (void)c_l, (void)c, \ 236 (void)k_l, (void)k, (void)ps_l, (void)ps, \ 237 mhd_TLS_CRED_CREATE_UNSUPPORTED) 238 # define mhd_tls_open_cred_destroy_nodmn(cred) ((void)(cred)) 239 #endif /* ! mhd_HAVE_OPENSSL_ACME */ 240 241 /** 242 * Release TLS credentials and free the allocated memory when no references 243 * remain. 244 * 245 * @param d_tls the pointer to the daemon's TLS settings 246 * @param cred the backend-specific credentials pointer to release; the OpenSSL 247 * member must be non-NULL 248 */ 249 #define mhd_tls_open_cred_destroy(d_tls, cred) \ 250 do { (void)(d_tls); \ 251 mhd_tls_open_cred_destroy_nodmn ((cred)); } while (0) 252 253 /* ** Connection initialisation / de-initialisation ** */ 254 255 struct mhd_ConnSocket; /* Forward declaration */ 256 257 /** 258 * Get size size of the connection's TLS settings 259 */ 260 MHD_INTERNAL size_t 261 mhd_tls_open_conn_get_tls_size_v (void); 262 263 /** 264 * Get size size of the connection's TLS settings 265 * @param d_tls the pointer to the daemon's TLS settings 266 */ 267 #define mhd_tls_open_conn_get_tls_size(d_tls) \ 268 mhd_tls_open_conn_get_tls_size_v () 269 270 /** 271 * Initialise connection TLS settings 272 * @param d_tls the daemon TLS settings 273 * @param sk data about the socket for the connection 274 * @param[out] c_tls the pointer to the allocated space for 275 * the connection TLS settings 276 * @return 'true' on success, 277 * 'false' otherwise 278 */ 279 MHD_INTERNAL bool 280 mhd_tls_open_conn_init (const struct mhd_TlsOpenDaemonData *restrict d_tls, 281 const struct mhd_ConnSocket *sk, 282 struct mhd_TlsOpenConnData *restrict c_tls) 283 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 284 285 /** 286 * De-initialise connection TLS settings. 287 * The provided pointer is not freed/deallocated. 288 * @param c_tls the initialised connection TLS settings 289 */ 290 MHD_INTERNAL void 291 mhd_tls_open_conn_deinit (struct mhd_TlsOpenConnData *restrict c_tls) 292 MHD_FN_PAR_NONNULL_ALL_; 293 294 295 /* ** TLS connection establishing ** */ 296 297 /** 298 * Perform TLS handshake 299 * @param c_tls the connection TLS handle 300 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 301 * or other enum mhd_TlsProcedureResult values 302 */ 303 MHD_INTERNAL enum mhd_TlsProcedureResult 304 mhd_tls_open_conn_handshake (struct mhd_TlsOpenConnData *restrict c_tls) 305 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 306 307 /** 308 * Perform shutdown of TLS layer 309 * @param c_tls the connection TLS handle 310 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 311 * or other enum mhd_TlsProcedureResult values 312 */ 313 MHD_INTERNAL enum mhd_TlsProcedureResult 314 mhd_tls_open_conn_shutdown (struct mhd_TlsOpenConnData *restrict c_tls) 315 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 316 317 318 /* ** Data sending and receiving over TLS connection ** */ 319 320 /** 321 * Receive the data from the remote side over TLS connection 322 * 323 * @param c_tls the connection TLS handle 324 * @param buf_size the size of the @a buf buffer 325 * @param[out] buf the buffer to fill with the received data 326 * @param[out] received the pointer to variable to get the size of the data 327 * actually put to the @a buffer 328 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 329 * the received size) or socket error 330 */ 331 MHD_INTERNAL enum mhd_SocketError 332 mhd_tls_open_conn_recv (struct mhd_TlsOpenConnData *restrict c_tls, 333 size_t buf_size, 334 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 335 size_t *restrict received) 336 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 337 338 /** 339 * Check whether any incoming data is pending in the TLS buffers 340 * 341 * @param c_tls the connection TLS handle 342 * @return 'true' if any incoming remote data is already pending (the TLS recv() 343 * call can be performed), 344 * 'false' otherwise 345 */ 346 MHD_INTERNAL bool 347 mhd_tls_open_conn_has_data_in (struct mhd_TlsOpenConnData *restrict c_tls) 348 MHD_FN_PAR_NONNULL_ALL_; 349 350 /** 351 * Send data to the remote side over TLS connection 352 * 353 * @param c_tls the connection TLS handle 354 * @param buf_size the size of the @a buf (in bytes) 355 * @param buf content of the buffer to send 356 * @param[out] sent the pointer to get amount of actually sent bytes 357 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 358 * the sent size) or socket error 359 */ 360 MHD_INTERNAL enum mhd_SocketError 361 mhd_tls_open_conn_send4 (struct mhd_TlsOpenConnData *restrict c_tls, 362 size_t buf_size, 363 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 364 size_t *restrict sent) 365 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3, 2) MHD_FN_PAR_OUT_ (4); 366 367 /** 368 * Send data to the remote side over TLS connection 369 * 370 * @param c_tls the connection TLS handle 371 * @param buf_size the size of the @a buf (in bytes) 372 * @param buf content of the buffer to send 373 * @param push_data set to 'false' if it is know that the data in the @a buf 374 * is incomplete (message or chunk), 375 * set to 'true' if the data is complete or the final part 376 * @param[out] sent the pointer to get amount of actually sent bytes 377 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 378 * the sent size) or socket error 379 */ 380 #define mhd_tls_open_conn_send(c_tls, buf_size, buf, push_data, sent) \ 381 mhd_tls_open_conn_send4 (c_tls,buf_size,buf,sent) 382 383 384 /* ** TLS connection information ** */ 385 386 /** 387 * Check whether the connection is using "custom transport" functions. 388 * "Custom transport" means that data sending and receiving over system 389 * sockets is performed by MHD callbacks. 390 * When "custom transport" is used, backend TLS send/recv functions are: 391 * * perform additional syscalls (socket options) for data pushing/buffering, 392 * * change socket states like corked, NO_DELAY, both by syscalls and in 393 * MHD socket metadata, 394 * * set disconnect error from the system reported socket error. 395 * 396 * @param c_tls the connection TLS handle 397 * @return boolean 'true' if custom transport is used, 398 * boolean 'false' otherwise 399 */ 400 #define mhd_tls_open_conn_has_cstm_tr(c_tls) (! ! 0) 401 402 /** 403 * Get the TLS session used in connection 404 * @param c_tls the connection TLS handle 405 * @param tls_sess_out the pointer to variable to be set to the TLS session 406 * handle 407 */ 408 MHD_INTERNAL void 409 mhd_tls_open_conn_get_tls_sess ( 410 struct mhd_TlsOpenConnData *restrict c_tls, 411 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 412 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 413 414 /** 415 * Get the TLS version used in connection 416 * @param c_tls the connection TLS handle 417 * @param tls_ver_out the pointer to variable to be set to the TLS version 418 * @return always 'true' 419 */ 420 MHD_INTERNAL bool 421 mhd_tls_open_conn_get_tls_ver (struct mhd_TlsOpenConnData *restrict c_tls, 422 struct mhd_StctTlsVersion *restrict tls_ver_out) 423 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 424 425 /** 426 * Get a protocol selected by ALPN 427 * @param c_tls the connection TLS handle 428 * @return the selected protocol code 429 */ 430 MHD_INTERNAL enum mhd_TlsAlpnProt 431 mhd_tls_open_conn_get_alpn_prot (struct mhd_TlsOpenConnData *restrict c_tls) 432 MHD_FN_PAR_NONNULL_ALL_; 433 434 #ifdef mhd_HAVE_TLS_ACME 435 /** 436 * Check whether the connection is ACME ALPN challenge connection 437 * @param c_tls the connection TLS handle 438 * @return 'true' if the connection is ACME ALPN challenge connection, 439 * 'false' otherwise 440 */ 441 # ifdef mhd_HAVE_OPENSSL_ACME 442 MHD_INTERNAL bool 443 mhd_tls_open_conn_is_acme (struct mhd_TlsOpenConnData *restrict c_tls) 444 MHD_FN_PAR_NONNULL_ALL_; 445 446 # else /* ! mhd_HAVE_OPENSSL_ACME */ 447 # define mhd_tls_open_conn_is_acme(c_tls) (((void)(c_tls)), (!!0)) 448 # endif /* ! mhd_HAVE_OPENSSL_ACME */ 449 #endif /* mhd_HAVE_TLS_ACME */ 450 451 #endif /* ! MHD_TLS_OPEN_FUNCS_H */