tls_gnu_funcs.h (12343B)
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_gnu_funcs.h 41 * @brief The declarations of GnuTLS wrapper functions 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_TLS_GNU_FUNCS_H 46 #define MHD_TLS_GNU_FUNCS_H 1 47 48 #include "mhd_sys_options.h" 49 50 #ifndef MHD_SUPPORT_GNUTLS 51 #error This header can be used only if GnuTLS is enabled 52 #endif 53 54 #include "sys_bool_type.h" 55 #include "sys_base_types.h" 56 57 #include "mhd_status_code_int.h" 58 59 #include "mhd_tls_enums.h" 60 #include "mhd_socket_error.h" 61 62 /** 63 * The structure with daemon-specific GnuTLS data 64 */ 65 struct mhd_TlsGnuDaemonData; /* Forward declaration */ 66 67 /** 68 * The structure with connection-specific GnuTLS data 69 */ 70 struct mhd_TlsGnuConnData; /* Forward declaration */ 71 72 union MHD_ConnInfoDynamicTlsSess; /* Forward declaration */ 73 74 struct mhd_StctTlsVersion; /* Forward declaration */ 75 76 /* ** Global initialisation / de-initialisation ** */ 77 78 /** 79 * Globally initialise GnuTLS backend 80 */ 81 MHD_INTERNAL void 82 mhd_tls_gnu_global_init (void); 83 84 /* An alias for mhd_tls_gnu_global_init() */ 85 #define mhd_tls_gnu_global_init_once() mhd_tls_gnu_global_init () 86 87 /* An alias for mhd_tls_gnu_global_init() */ 88 #define mhd_tls_gnu_global_re_init() mhd_tls_gnu_global_init () 89 90 /** 91 * Globally de-initialise GnuTLS backend 92 */ 93 MHD_INTERNAL void 94 mhd_tls_gnu_global_deinit (void); 95 96 /** 97 * Check whether GnuTLS backend was successfully initialised globally 98 * @return 'true' if backend has been successfully initialised, 99 * 'false' if backend cannot be used 100 */ 101 MHD_INTERNAL bool 102 mhd_tls_gnu_is_inited_fine (void) 103 MHD_FN_PURE_; 104 105 106 /* ** Daemon initialisation / de-initialisation ** */ 107 108 struct MHD_Daemon; /* Forward declaration */ 109 struct DaemonOptions; /* Forward declaration */ 110 111 /** 112 * Check whether GnuTLS backend supports edge-triggered sockets polling 113 * @param s the daemon settings 114 * @return 'true' if the backend supports edge-triggered sockets polling, 115 * 'false' if edge-triggered sockets polling cannot be used 116 */ 117 #define mhd_tls_gnu_is_edge_trigg_supported(s) (! 0) 118 119 120 /** 121 * Allocate and initialise daemon TLS parameters 122 * @param d the daemon handle 123 * @param s the daemon settings 124 * @param p_d_tls the pointer to variable to set the pointer to 125 * the daemon's TLS settings (allocated by this function) 126 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 127 * error code otherwise 128 */ 129 MHD_INTERNAL mhd_StatusCodeInt 130 mhd_tls_gnu_daemon_init3 (struct MHD_Daemon *restrict d, 131 struct DaemonOptions *restrict s, 132 struct mhd_TlsGnuDaemonData **restrict p_d_tls) 133 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 134 135 136 /** 137 * Allocate and initialise daemon TLS parameters 138 * @param d the daemon handle 139 * @param et if 'true' then sockets polling uses edge-triggering 140 * @param s the daemon settings 141 * @param p_d_tls the pointer to variable to set the pointer to 142 * the daemon's TLS settings (allocated by this function) 143 * @return #MHD_SC_OK on success (p_d_tls set to the allocated settings), 144 * error code otherwise 145 */ 146 #define mhd_tls_gnu_daemon_init(d,et,s,p_d_tls) \ 147 mhd_tls_gnu_daemon_init3 ((d),(s),(p_d_tls)) 148 149 /** 150 * De-initialise daemon TLS parameters (and free memory allocated for TLS 151 * settings) 152 * @param d_tls the pointer to the daemon's TLS settings 153 */ 154 MHD_INTERNAL void 155 mhd_tls_gnu_daemon_deinit (struct mhd_TlsGnuDaemonData *restrict d_tls) 156 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_INOUT_ (1); 157 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 #define mhd_tls_gnu_thread_cleanup(d_tls) ((void) 0) 165 166 /* ** Connection initialisation / de-initialisation ** */ 167 168 struct mhd_ConnSocket; /* Forward declaration */ 169 170 /** 171 * Get size size of the connection's TLS settings 172 */ 173 MHD_INTERNAL size_t 174 mhd_tls_gnu_conn_get_tls_size_v (void); 175 176 /** 177 * Get size size of the connection's TLS settings 178 * @param d_tls the pointer to the daemon's TLS settings 179 */ 180 #define mhd_tls_gnu_conn_get_tls_size(d_tls) \ 181 mhd_tls_gnu_conn_get_tls_size_v () 182 183 /** 184 * Initialise connection TLS settings 185 * @param d_tls the daemon TLS settings 186 * @param sk data about the socket for the connection 187 * @param[out] c_tls the pointer to the allocated space for 188 * the connection TLS settings 189 * @return 'true' on success, 190 * 'false' otherwise 191 */ 192 MHD_INTERNAL bool 193 mhd_tls_gnu_conn_init (const struct mhd_TlsGnuDaemonData *restrict d_tls, 194 const struct mhd_ConnSocket *sk, 195 struct mhd_TlsGnuConnData *restrict c_tls) 196 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 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 MHD_INTERNAL void 204 mhd_tls_gnu_conn_deinit (struct mhd_TlsGnuConnData *restrict c_tls) 205 MHD_FN_PAR_NONNULL_ALL_; 206 207 208 /* ** TLS connection establishing ** */ 209 210 /** 211 * Perform TLS handshake 212 * @param c_tls the connection TLS handle 213 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 214 * or other enum mhd_TlsProcedureResult values 215 */ 216 MHD_INTERNAL enum mhd_TlsProcedureResult 217 mhd_tls_gnu_conn_handshake (struct mhd_TlsGnuConnData *restrict c_tls) 218 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 219 220 /** 221 * Perform shutdown of TLS layer 222 * @param c_tls the connection TLS handle 223 * @return #mhd_TLS_PROCED_SUCCESS if completed successfully 224 * or other enum mhd_TlsProcedureResult values 225 */ 226 MHD_INTERNAL enum mhd_TlsProcedureResult 227 mhd_tls_gnu_conn_shutdown (struct mhd_TlsGnuConnData *restrict c_tls) 228 MHD_FN_MUST_CHECK_RESULT_ MHD_FN_PAR_NONNULL_ALL_; 229 230 231 /* ** Data sending and receiving over TLS connection ** */ 232 233 /** 234 * Receive the data from the remote side over TLS connection 235 * 236 * @param c_tls the connection TLS handle 237 * @param buf_size the size of the @a buf buffer 238 * @param[out] buf the buffer to fill with the received data 239 * @param[out] received the pointer to variable to get the size of the data 240 * actually put to the @a buffer 241 * @return mhd_SOCKET_ERR_NO_ERROR if receive succeed (the @a received gets 242 * the received size) or socket error 243 */ 244 MHD_INTERNAL enum mhd_SocketError 245 mhd_tls_gnu_conn_recv (struct mhd_TlsGnuConnData *restrict c_tls, 246 size_t buf_size, 247 char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 248 size_t *restrict received) 249 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_ (3,2) MHD_FN_PAR_OUT_ (4); 250 251 /** 252 * Check whether any incoming data is pending in the TLS buffers 253 * 254 * @param c_tls the connection TLS handle 255 * @return 'true' if any incoming remote data is already pending (the TLS recv() 256 * call can be performed), 257 * 'false' otherwise 258 */ 259 MHD_INTERNAL bool 260 mhd_tls_gnu_conn_has_data_in (struct mhd_TlsGnuConnData *restrict c_tls) 261 MHD_FN_PAR_NONNULL_ALL_; 262 263 /** 264 * Send data to the remote side over TLS connection 265 * 266 * @param c_tls the connection TLS handle 267 * @param buf_size the size of the @a buf (in bytes) 268 * @param buf content of the buffer to send 269 * @param[out] sent the pointer to get amount of actually sent bytes 270 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 271 * the sent size) or socket error 272 */ 273 MHD_INTERNAL enum mhd_SocketError 274 mhd_tls_gnu_conn_send4 (struct mhd_TlsGnuConnData *restrict c_tls, 275 size_t buf_size, 276 const char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)], 277 size_t *restrict sent) 278 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_ (3,2) MHD_FN_PAR_OUT_ (4); 279 280 /** 281 * Send data to the remote side over TLS connection 282 * 283 * @param c_tls the connection TLS handle 284 * @param buf_size the size of the @a buf (in bytes) 285 * @param buf content of the buffer to send 286 * @param push_data set to 'false' if it is know that the data in the @a b 287 * is incomplete (message or chunk), 288 * set to 'true' if the data is complete or the final part 289 * @param[out] sent the pointer to get amount of actually sent bytes 290 * @return mhd_SOCKET_ERR_NO_ERROR if send succeed (the @a sent gets 291 * the sent size) or socket error 292 */ 293 #define mhd_tls_gnu_conn_send(c_tls,buf_size,buf,push_data,sent) \ 294 mhd_tls_gnu_conn_send4 (c_tls,buf_size,buf,sent) 295 296 /* ** TLS connection information ** */ 297 298 /** 299 * Check whether the connection is using "custom transport" functions. 300 * "Custom transport" means that data sending and receiving over system 301 * sockets is performed by MHD callbacks. 302 * When "custom transport" is used, backend TLS send/recv functions are: 303 * * perform additional syscalls (socket options) for data pushing/buffering, 304 * * change socket states like corked, NO_DELAY, both by syscalls and in 305 * MHD socket metadata, 306 * * set disconnect error from the system reported socket error. 307 * 308 * @param c_tls the connection TLS handle 309 * @return boolean 'true' if custom transport is used, 310 * boolean 'false' otherwise 311 */ 312 #define mhd_tls_gnu_conn_has_cstm_tr(c_tls) (! ! 0) 313 314 /** 315 * Get the TLS session used in connection 316 * @param c_tls the connection TLS handle 317 * @param tls_sess_out the pointer to variable to be set to the TLS session 318 * handle 319 */ 320 MHD_INTERNAL void 321 mhd_tls_gnu_conn_get_tls_sess ( 322 struct mhd_TlsGnuConnData *restrict c_tls, 323 union MHD_ConnInfoDynamicTlsSess *restrict tls_sess_out) 324 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 325 326 /** 327 * Get the TLS version used in connection 328 * @param c_tls the connection TLS handle 329 * @param tls_ver_out the pointer to variable to be set to the TLS version 330 * @return 'true' is TLS version information set successfully, 331 * 'false' if TLS version information cannot be obtained or mapped 332 */ 333 MHD_INTERNAL bool 334 mhd_tls_gnu_conn_get_tls_ver (struct mhd_TlsGnuConnData *restrict c_tls, 335 struct mhd_StctTlsVersion *restrict tls_ver_out) 336 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2); 337 338 /** 339 * Get a protocol selected by ALPN 340 * @param c_tls the connection TLS handle 341 * @return the selected protocol code 342 */ 343 MHD_INTERNAL enum mhd_TlsAlpnProt 344 mhd_tls_gnu_conn_get_alpn_prot (struct mhd_TlsGnuConnData *restrict c_tls) 345 MHD_FN_PAR_NONNULL_ALL_; 346 347 348 #endif /* ! MHD_TLS_GNU_FUNCS_H */