mhd_tls_funcs.h (12117B)
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/mhd_tls_funcs.h 41 * @brief The TLS backend functions generic declaration, mapped to specific TLS 42 * backend at compile-time 43 * @author Karlson2k (Evgeny Grin) 44 */ 45 46 #ifndef MHD_TLS_FUNCS_H 47 #define MHD_TLS_FUNCS_H 1 48 49 #include "mhd_sys_options.h" 50 51 #include "sys_bool_type.h" 52 53 #include "mhd_tls_choice.h" 54 #ifndef MHD_SUPPORT_HTTPS 55 # error This header should be used only if HTTPS is enabled 56 #endif 57 58 #if defined(MHD_USE_MULTITLS) 59 # include "tls_multi_funcs.h" 60 #elif defined(MHD_SUPPORT_GNUTLS) 61 # include "tls_gnu_funcs.h" 62 #elif defined(MHD_SUPPORT_OPENSSL) 63 # include "tls_open_funcs.h" 64 #elif defined(MHD_SUPPORT_MBEDTLS) 65 # include "tls_mbed_funcs.h" 66 #endif 67 68 /* ** Global initialisation / de-initialisation ** */ 69 70 /** 71 * Perform one-time global initialisation of TLS backend 72 */ 73 #define mhd_tls_global_init_once() mhd_TLS_FUNC (_global_init_once)() 74 75 /** 76 * Perform de-initialisation of TLS backend 77 */ 78 #define mhd_tls_global_deinit() mhd_TLS_FUNC (_global_deinit)() 79 80 /** 81 * Perform re-initialisation of TLS backend 82 */ 83 #define mhd_tls_global_re_init() mhd_TLS_FUNC (_global_re_init)() 84 85 /* ** Daemon initialisation / de-initialisation ** */ 86 87 /** 88 * Check whether the selected backend supports edge-triggered sockets polling 89 * @param s the daemon settings 90 * @return 'true' if the backend supports edge-triggered sockets polling, 91 * 'false' if edge-triggered sockets polling cannot be used 92 */ 93 #define mhd_tls_is_edge_trigg_supported(s) \ 94 mhd_TLS_FUNC (_is_edge_trigg_supported)((s)) 95 96 #ifdef mhd_HAVE_TLS_ACME 97 /** 98 * Check whether selected backend supports ACME ALPN challenge protocol 99 * @param s the daemon settings 100 * @return 'true' if the backend supports ACME ALPN challenge protocol, 101 * 'false' otherwise 102 */ 103 # define mhd_tls_is_acme_alpn_supported(s) \ 104 mhd_TLS_FUNC (_is_acme_alpn_supported)((s)) 105 #endif /* mhd_HAVE_TLS_ACME */ 106 107 /** 108 * Allocate and initialise daemon TLS parameters 109 * @param d the daemon handle 110 * @param et if 'true' then sockets polling uses edge-triggering 111 * @param s the daemon settings 112 * @param p_d_tls the pointer to variable to set the pointer to 113 * the daemon's TLS settings (allocated by this function) 114 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 115 * error code otherwise 116 */ 117 #define mhd_tls_daemon_init(d, et, s, p_d_tls) \ 118 mhd_TLS_FUNC (_daemon_init)((d),(et),(s),(p_d_tls)) 119 120 /** 121 * De-initialise daemon TLS parameters (and free memory allocated for TLS 122 * settings) 123 * @param d_tls the pointer to the daemon's TLS settings 124 */ 125 #define mhd_tls_daemon_deinit(d_tls) \ 126 mhd_TLS_FUNC (_daemon_deinit)((d_tls)) 127 128 /** 129 * Perform clean-up of TLS resources before thread closing. 130 * Must be called before thread is closed, after any use of TLS functions 131 * in the thread, but before de-initialisation of daemon's TLS data. 132 * @param d_tls the pointer to the daemon's TLS settings 133 */ 134 #define mhd_tls_thread_cleanup(d_tls) \ 135 mhd_TLS_FUNC (_thread_cleanup)((d_tls)) 136 137 138 /* ** Credentials creation / destruction ** */ 139 140 /** 141 * Create TLS credentials from the provided certificate and key data 142 * 143 * Created credentials must be destroyed with mhd_tls_cred_destroy() 144 * function before de-initialisation of the daemon's TLS settings. 145 * 146 * @param d_tls the pointer to the daemon's TLS settings 147 * @param pp_c the pointer to the pointer to the credentials data structure 148 * to be allocated and filled, set to NULL on failure 149 * @param cert_l the length of the @p cert buffer, not including the 150 * zero-termination byte, 151 * must not be zero 152 * @param cert the certificate data in PEM format, zero-terminated 153 * @param key_l the length of the @p key buffer, not including the 154 * zero-termination byte, 155 * must not be zero 156 * @param key the private key data in PEM format, zero-terminated 157 * @param p_l the length of the @p pass buffer, not including the 158 * zero-termination byte, 159 * must be zero if the @p pass is NULL 160 * @param pass the password for the private key, zero-terminated, 161 * may be NULL if the private key is not password-protected 162 * @return #mhd_TLS_CRED_CREATE_OK on success, 163 * other enum mhd_TlsCredCreateResult values on failure 164 */ 165 #define mhd_tls_cred_create(d_tls, pp_c, cert_l, cert, key_l, key, p_l, pass) \ 166 mhd_TLS_FUNC (_cred_create)((d_tls),(pp_c),(cert_l),(cert), \ 167 (key_l),(key),(p_l),(pass)) 168 169 /** 170 * Destroy TLS credentials and free allocated memory 171 * @param d_tls the daemon TLS settings 172 * @param cred the pointer to the credentials data structure to be destroyed 173 */ 174 #define mhd_tls_cred_destroy(d_tls, cred) \ 175 mhd_TLS_FUNC (_cred_destroy)((d_tls),(cred)) 176 177 /* ** Connection initialisation / de-initialisation ** */ 178 179 /** 180 * Get size size of the connection's TLS settings 181 * @param d_tls the pointer to the daemon's TLS settings 182 */ 183 #define mhd_tls_conn_get_tls_size(d_tls) \ 184 mhd_TLS_FUNC (_conn_get_tls_size)(d_tls) 185 186 /** 187 * Initialise connection TLS settings 188 * @param d_tls the daemon TLS settings 189 * @param sk data about the socket for the connection 190 * @param[out] c_tls the pointer to the allocated space for 191 * the connection TLS settings 192 * @return 'true' on success, 193 * 'false' otherwise 194 */ 195 #define mhd_tls_conn_init(d_tls, sk, c_tls) \ 196 mhd_TLS_FUNC (_conn_init)((d_tls),(sk),(c_tls)) 197 198 /** 199 * De-initialise connection TLS settings. 200 * The provided pointer is not freed/deallocated. 201 * @param c_tls the initialised connection TLS settings 202 */ 203 #define mhd_tls_conn_deinit(c_tls) \ 204 mhd_TLS_FUNC (_conn_deinit)((c_tls)) 205 206 207 /* ** TLS connection establishing ** */ 208 209 /** 210 * Perform TLS handshake 211 * @param c_tls the connection TLS handle 212 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 213 * or other enum mhd_TlsProcedureResult values 214 */ 215 #define mhd_tls_conn_handshake(c_tls) \ 216 mhd_TLS_FUNC (_conn_handshake)((c_tls)) 217 218 /** 219 * Perform shutdown of TLS layer 220 * @param c_tls the connection TLS handle 221 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 222 * or other enum mhd_TlsProcedureResult values 223 */ 224 #define mhd_tls_conn_shutdown(c_tls) \ 225 mhd_TLS_FUNC (_conn_shutdown)((c_tls)) 226 227 /* ** Data sending and receiving over TLS connection ** */ 228 229 /** 230 * Receive the data from the remote side over TLS connection 231 * 232 * @param c_tls the connection TLS handle 233 * @param buf_size the size of the @a buf buffer 234 * @param[out] buf the buffer to fill with the received data 235 * @param[out] received the pointer to variable to get the size of the data 236 * actually put to the @a buffer 237 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 238 * the received size) or socket error 239 */ 240 #define mhd_tls_conn_recv(c_tls, buf_size, buf, received) \ 241 mhd_TLS_FUNC (_conn_recv)((c_tls),(buf_size),(buf),(received)) 242 243 /** 244 * Check whether any incoming data is pending in the TLS buffers 245 * 246 * @param c_tls the connection TLS handle 247 * @return 'true' if any incoming remote data is already pending (the TLS recv() 248 * call can be performed), 249 * 'false' otherwise 250 */ 251 #define mhd_tls_conn_has_data_in(c_tls) \ 252 mhd_TLS_FUNC (_conn_has_data_in)((c_tls)) 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 push_data set to 'false' if it is know that the data in the @a buf 261 * is incomplete (message or chunk), 262 * set to 'true' if the data is complete or the final part 263 * @param[out] sent the pointer to get amount of actually sent bytes 264 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 265 * the sent size) or socket error 266 */ 267 #define mhd_tls_conn_send(c_tls, buf_size, buf, push_data, sent) \ 268 mhd_TLS_FUNC (_conn_send)((c_tls),(buf_size),(buf),(push_data),(sent)) 269 270 271 /* ** TLS connection information ** */ 272 273 /** 274 * Check whether the connection is using "custom transport" functions. 275 * "Custom transport" means that data sending and receiving over system 276 * sockets is performed by MHD callbacks. 277 * When "custom transport" is used, backend TLS send/recv functions are: 278 * * perform additional syscalls (socket options) for data pushing/buffering, 279 * * change socket states like corked, NO_DELAY, both by syscalls and in 280 * MHD socket metadata, 281 * * set disconnect error from the system reported socket error. 282 * 283 * @param c_tls the connection TLS handle 284 * @return boolean 'true' if custom transport is used, 285 * boolean 'false' otherwise 286 */ 287 #define mhd_tls_conn_has_cstm_tr(c_tls) \ 288 mhd_TLS_FUNC (_conn_has_cstm_tr)((c_tls)) 289 290 /** 291 * Get the TLS session used in connection 292 * @param c_tls the connection TLS handle 293 * @param tls_ver_out the pointer to variable to be set to the TLS version 294 */ 295 #define mhd_tls_conn_get_tls_sess(c_tls, tls_sess_out) \ 296 mhd_TLS_FUNC (_conn_get_tls_sess)((c_tls),(tls_sess_out)) 297 298 /** 299 * Get the TLS version used in connection 300 * @param c_tls the connection TLS handle 301 * @param tls_ver_out the pointer to variable to be set to the TLS version 302 * @return 'true' is TLS version information set successfully, 303 * 'false' if TLS version information cannot be obtained or mapped 304 */ 305 #define mhd_tls_conn_get_tls_ver(c_tls, tls_ver_out) \ 306 mhd_TLS_FUNC (_conn_get_tls_ver)((c_tls),(tls_ver_out)) 307 308 /** 309 * Get a protocol selected by ALPN 310 * @param c_tls the connection TLS handle 311 * @return the selected protocol code 312 */ 313 #define mhd_tls_conn_get_alpn_prot(c_tls) \ 314 mhd_TLS_FUNC (_conn_get_alpn_prot)((c_tls)) 315 316 #ifdef mhd_HAVE_TLS_ACME 317 /** 318 * Check whether the connection is ACME ALPN challenge connection 319 * @param c_tls the connection TLS handle 320 * @return 'true' if the connection is ACME ALPN challenge connection, 321 * 'false' otherwise 322 */ 323 # define mhd_tls_conn_is_acme(c_tls) \ 324 mhd_TLS_FUNC (_conn_is_acme)((c_tls)) 325 #endif /* mhd_HAVE_TLS_ACME */ 326 327 328 #endif /* ! MHD_TLS_FUNCS_H */