mhd_tls_funcs.h (9588B)
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 /** 97 * Allocate and initialise daemon TLS parameters 98 * @param d the daemon handle 99 * @param et if 'true' then sockets polling uses edge-triggering 100 * @param s the daemon settings 101 * @param p_d_tls the pointer to variable to set the pointer to 102 * the daemon's TLS settings (allocated by this function) 103 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 104 * error code otherwise 105 */ 106 #define mhd_tls_daemon_init(d,et,s,p_d_tls) \ 107 mhd_TLS_FUNC (_daemon_init)((d),(et),(s),(p_d_tls)) 108 109 /** 110 * De-initialise daemon TLS parameters (and free memory allocated for TLS 111 * settings) 112 * @param d_tls the pointer to the daemon's TLS settings 113 */ 114 #define mhd_tls_daemon_deinit(d_tls) \ 115 mhd_TLS_FUNC (_daemon_deinit)((d_tls)) 116 117 /** 118 * Perform clean-up of TLS resources before thread closing. 119 * Must be called before thread is closed, after any use of TLS functions 120 * in the thread, but before de-initialisation of daemon's TLS data. 121 * @param d_tls the pointer to the daemon's TLS settings 122 */ 123 #define mhd_tls_thread_cleanup(d_tls) \ 124 mhd_TLS_FUNC (_thread_cleanup)((d_tls)) 125 126 127 /* ** Connection initialisation / de-initialisation ** */ 128 129 /** 130 * Get size size of the connection's TLS settings 131 * @param d_tls the pointer to the daemon's TLS settings 132 */ 133 #define mhd_tls_conn_get_tls_size(d_tls) \ 134 mhd_TLS_FUNC (_conn_get_tls_size)(d_tls) 135 136 /** 137 * Initialise connection TLS settings 138 * @param d_tls the daemon TLS settings 139 * @param sk data about the socket for the connection 140 * @param[out] c_tls the pointer to the allocated space for 141 * the connection TLS settings 142 * @return 'true' on success, 143 * 'false' otherwise 144 */ 145 #define mhd_tls_conn_init(d_tls,sk,c_tls) \ 146 mhd_TLS_FUNC (_conn_init)((d_tls),(sk),(c_tls)) 147 148 /** 149 * De-initialise connection TLS settings. 150 * The provided pointer is not freed/deallocated. 151 * @param c_tls the initialised connection TLS settings 152 */ 153 #define mhd_tls_conn_deinit(c_tls) \ 154 mhd_TLS_FUNC (_conn_deinit)((c_tls)) 155 156 157 /* ** TLS connection establishing ** */ 158 159 /** 160 * Perform TLS handshake 161 * @param c_tls the connection TLS handle 162 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 163 * or other enum mhd_TlsProcedureResult values 164 */ 165 #define mhd_tls_conn_handshake(c_tls) \ 166 mhd_TLS_FUNC (_conn_handshake)((c_tls)) 167 168 /** 169 * Perform shutdown of TLS layer 170 * @param c_tls the connection TLS handle 171 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 172 * or other enum mhd_TlsProcedureResult values 173 */ 174 #define mhd_tls_conn_shutdown(c_tls) \ 175 mhd_TLS_FUNC (_conn_shutdown)((c_tls)) 176 177 /* ** Data sending and receiving over TLS connection ** */ 178 179 /** 180 * Receive the data from the remote side over TLS connection 181 * 182 * @param c_tls the connection TLS handle 183 * @param buf_size the size of the @a buf buffer 184 * @param[out] buf the buffer to fill with the received data 185 * @param[out] received the pointer to variable to get the size of the data 186 * actually put to the @a buffer 187 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 188 * the received size) or socket error 189 */ 190 #define mhd_tls_conn_recv(c_tls,buf_size,buf,received) \ 191 mhd_TLS_FUNC (_conn_recv)((c_tls),(buf_size),(buf),(received)) 192 193 /** 194 * Check whether any incoming data is pending in the TLS buffers 195 * 196 * @param c_tls the connection TLS handle 197 * @return 'true' if any incoming remote data is already pending (the TLS recv() 198 * call can be performed), 199 * 'false' otherwise 200 */ 201 #define mhd_tls_conn_has_data_in(c_tls) \ 202 mhd_TLS_FUNC (_conn_has_data_in)((c_tls)) 203 204 /** 205 * Send data to the remote side over TLS connection 206 * 207 * @param c_tls the connection TLS handle 208 * @param buf_size the size of the @a buf (in bytes) 209 * @param buf content of the buffer to send 210 * @param push_data set to 'false' if it is know that the data in the @a buf 211 * is incomplete (message or chunk), 212 * set to 'true' if the data is complete or the final part 213 * @param[out] sent the pointer to get amount of actually sent bytes 214 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 215 * the sent size) or socket error 216 */ 217 #define mhd_tls_conn_send(c_tls,buf_size,buf,push_data,sent) \ 218 mhd_TLS_FUNC (_conn_send)((c_tls),(buf_size),(buf),(push_data),(sent)) 219 220 221 /* ** TLS connection information ** */ 222 223 /** 224 * Check whether the connection is using "custom transport" functions. 225 * "Custom transport" means that data sending and receiving over system 226 * sockets is performed by MHD callbacks. 227 * When "custom transport" is used, backend TLS send/recv functions are: 228 * * perform additional syscalls (socket options) for data pushing/buffering, 229 * * change socket states like corked, NO_DELAY, both by syscalls and in 230 * MHD socket metadata, 231 * * set disconnect error from the system reported socket error. 232 * 233 * @param c_tls the connection TLS handle 234 * @return boolean 'true' if custom transport is used, 235 * boolean 'false' otherwise 236 */ 237 #define mhd_tls_conn_has_cstm_tr(c_tls) \ 238 mhd_TLS_FUNC (_conn_has_cstm_tr)((c_tls)) 239 240 /** 241 * Get the TLS session used in connection 242 * @param c_tls the connection TLS handle 243 * @param tls_ver_out the pointer to variable to be set to the TLS version 244 */ 245 #define mhd_tls_conn_get_tls_sess(c_tls,tls_sess_out) \ 246 mhd_TLS_FUNC (_conn_get_tls_sess)((c_tls),(tls_sess_out)) 247 248 /** 249 * Get the TLS version used in connection 250 * @param c_tls the connection TLS handle 251 * @param tls_ver_out the pointer to variable to be set to the TLS version 252 * @return 'true' is TLS version information set successfully, 253 * 'false' if TLS version information cannot be obtained or mapped 254 */ 255 #define mhd_tls_conn_get_tls_ver(c_tls,tls_ver_out) \ 256 mhd_TLS_FUNC (_conn_get_tls_ver)((c_tls),(tls_ver_out)) 257 258 /** 259 * Get a protocol selected by ALPN 260 * @param c_tls the connection TLS handle 261 * @return the selected protocol code 262 */ 263 #define mhd_tls_conn_get_alpn_prot(c_tls) \ 264 mhd_TLS_FUNC (_conn_get_alpn_prot)((c_tls)) 265 266 #endif /* ! MHD_TLS_FUNCS_H */