microhttpd.h (253585B)
1 /* 2 This file is part of libmicrohttpd 3 Copyright (C) 2006-2021 Christian Grothoff (and other contributing authors) 4 Copyright (C) 2014-2023 Evgeny Grin (Karlson2k) 5 6 This library 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 This library 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 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** 22 * @file microhttpd.h 23 * @brief public interface to libmicrohttpd 24 * @author Christian Grothoff 25 * @author Karlson2k (Evgeny Grin) 26 * @author Chris GauthierDickey 27 * 28 * All symbols defined in this header start with MHD. MHD is a small 29 * HTTP daemon library. As such, it does not have any API for logging 30 * errors (you can only enable or disable logging to stderr). Also, 31 * it may not support all of the HTTP features directly, where 32 * applicable, portions of HTTP may have to be handled by clients of 33 * the library. 34 * 35 * The library is supposed to handle everything that it must handle 36 * (because the API would not allow clients to do this), such as basic 37 * connection management; however, detailed interpretations of headers 38 * -- such as range requests -- and HTTP methods are left to clients. 39 * The library does understand HEAD and will only send the headers of 40 * the response and not the body, even if the client supplied a body. 41 * The library also understands headers that control connection 42 * management (specifically, "Connection: close" and "Expect: 100 43 * continue" are understood and handled automatically). 44 * 45 * MHD understands POST data and is able to decode certain formats 46 * (at the moment only "application/x-www-form-urlencoded" and 47 * "multipart/formdata"). Unsupported encodings and large POST 48 * submissions may require the application to manually process 49 * the stream, which is provided to the main application (and thus can be 50 * processed, just not conveniently by MHD). 51 * 52 * The header file defines various constants used by the HTTP protocol. 53 * This does not mean that MHD actually interprets all of these 54 * values. The provided constants are exported as a convenience 55 * for users of the library. MHD does not verify that transmitted 56 * HTTP headers are part of the standard specification; users of the 57 * library are free to define their own extensions of the HTTP 58 * standard and use those with MHD. 59 * 60 * All functions are guaranteed to be completely reentrant and 61 * thread-safe (with the exception of #MHD_set_connection_value, 62 * which must only be used in a particular context). 63 * 64 * 65 * @defgroup event event-loop control 66 * MHD API to start and stop the HTTP server and manage the event loop. 67 * @defgroup response generation of responses 68 * MHD API used to generate responses. 69 * @defgroup request handling of requests 70 * MHD API used to access information about requests. 71 * @defgroup authentication HTTP authentication 72 * MHD API related to basic and digest HTTP authentication. 73 * @defgroup logging logging 74 * MHD API to mange logging and error handling 75 * @defgroup specialized misc. specialized functions 76 * This group includes functions that do not fit into any particular 77 * category and that are rarely used. 78 */ 79 80 #ifndef MHD_MICROHTTPD_H 81 #define MHD_MICROHTTPD_H 82 83 #ifndef __cplusplus 84 # define MHD_C_DECLRATIONS_START_HERE_ /* Empty */ 85 # define MHD_C_DECLRATIONS_FINISH_HERE_ /* Empty */ 86 #else /* __cplusplus */ 87 /* *INDENT-OFF* */ 88 # define MHD_C_DECLRATIONS_START_HERE_ extern "C" { 89 # define MHD_C_DECLRATIONS_FINISH_HERE_ } 90 /* *INDENT-ON* */ 91 #endif /* __cplusplus */ 92 93 94 MHD_C_DECLRATIONS_START_HERE_ 95 96 97 /** 98 * Current version of the library in packed BCD form. 99 * @note Version number components are coded as Simple Binary-Coded Decimal 100 * (also called Natural BCD or BCD 8421). While they are hexadecimal numbers, 101 * they are parsed as decimal numbers. 102 * Example: 0x01093001 = 1.9.30-1. 103 */ 104 #define MHD_VERSION 0x01000200 105 106 /* If generic headers don't work on your platform, include headers 107 which define 'va_list', 'size_t', 'ssize_t', 'intptr_t', 'off_t', 108 'uint8_t', 'uint16_t', 'int32_t', 'uint32_t', 'int64_t', 'uint64_t', 109 'struct sockaddr', 'socklen_t', 'fd_set' and "#define MHD_PLATFORM_H" before 110 including "microhttpd.h". Then the following "standard" 111 includes won't be used (which might be a good idea, especially 112 on platforms where they do not exist). 113 */ 114 #ifndef MHD_PLATFORM_H 115 #if defined(_WIN32) && ! defined(__CYGWIN__) && \ 116 ! defined(_CRT_DECLARE_NONSTDC_NAMES) 117 /* Declare POSIX-compatible names */ 118 #define _CRT_DECLARE_NONSTDC_NAMES 1 119 #endif /* _WIN32 && ! __CYGWIN__ && ! _CRT_DECLARE_NONSTDC_NAMES */ 120 #include <stdarg.h> 121 #include <stdint.h> 122 #include <sys/types.h> 123 #if ! defined(_WIN32) || defined(__CYGWIN__) 124 #include <unistd.h> 125 #include <sys/time.h> 126 #include <sys/socket.h> 127 #else /* _WIN32 && ! __CYGWIN__ */ 128 #include <ws2tcpip.h> 129 #if defined(_MSC_FULL_VER) && ! defined(_SSIZE_T_DEFINED) 130 #define _SSIZE_T_DEFINED 131 typedef intptr_t ssize_t; 132 #endif /* !_SSIZE_T_DEFINED */ 133 #endif /* _WIN32 && ! __CYGWIN__ */ 134 #endif 135 136 #if defined(__CYGWIN__) && ! defined(_SYS_TYPES_FD_SET) 137 /* Do not define __USE_W32_SOCKETS under Cygwin! */ 138 #error Cygwin with winsock fd_set is not supported 139 #endif 140 141 #ifdef __has_attribute 142 #if __has_attribute (flag_enum) 143 #define _MHD_FLAGS_ENUM __attribute__((flag_enum)) 144 #endif /* flag_enum */ 145 #if __has_attribute (enum_extensibility) 146 #define _MHD_FIXED_ENUM __attribute__((enum_extensibility (closed))) 147 #endif /* enum_extensibility */ 148 #endif /* __has_attribute */ 149 150 #ifndef _MHD_FLAGS_ENUM 151 #define _MHD_FLAGS_ENUM 152 #endif /* _MHD_FLAGS_ENUM */ 153 #ifndef _MHD_FIXED_ENUM 154 #define _MHD_FIXED_ENUM 155 #endif /* _MHD_FIXED_ENUM */ 156 157 #define _MHD_FIXED_FLAGS_ENUM _MHD_FIXED_ENUM _MHD_FLAGS_ENUM 158 159 /** 160 * Operational results from MHD calls. 161 */ 162 enum MHD_Result 163 { 164 /** 165 * MHD result code for "NO". 166 */ 167 MHD_NO = 0, 168 169 /** 170 * MHD result code for "YES". 171 */ 172 MHD_YES = 1 173 174 } _MHD_FIXED_ENUM; 175 176 /** 177 * Constant used to indicate unknown size (use when 178 * creating a response). 179 */ 180 #ifdef UINT64_MAX 181 #define MHD_SIZE_UNKNOWN UINT64_MAX 182 #else 183 #define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) 184 #endif 185 186 #define MHD_CONTENT_READER_END_OF_STREAM ((ssize_t) -1) 187 #define MHD_CONTENT_READER_END_WITH_ERROR ((ssize_t) -2) 188 189 #ifndef _MHD_EXTERN 190 #if defined(_WIN32) && defined(MHD_W32LIB) 191 #define _MHD_EXTERN extern 192 #elif defined(_WIN32) && defined(MHD_W32DLL) 193 /* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ 194 #define _MHD_EXTERN __declspec(dllimport) 195 #else 196 #define _MHD_EXTERN extern 197 #endif 198 #endif 199 200 #ifndef MHD_SOCKET_DEFINED 201 /** 202 * MHD_socket is type for socket FDs 203 */ 204 #if ! defined(_WIN32) || defined(_SYS_TYPES_FD_SET) 205 #define MHD_POSIX_SOCKETS 1 206 typedef int MHD_socket; 207 #define MHD_INVALID_SOCKET (-1) 208 #else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 209 #define MHD_WINSOCK_SOCKETS 1 210 #include <winsock2.h> 211 typedef SOCKET MHD_socket; 212 #define MHD_INVALID_SOCKET (INVALID_SOCKET) 213 #endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 214 #define MHD_SOCKET_DEFINED 1 215 #endif /* MHD_SOCKET_DEFINED */ 216 217 /** 218 * Define MHD_NO_DEPRECATION before including "microhttpd.h" to disable deprecation messages 219 */ 220 #ifdef MHD_NO_DEPRECATION 221 #define _MHD_DEPR_MACRO(msg) 222 #define _MHD_NO_DEPR_IN_MACRO 1 223 #define _MHD_DEPR_IN_MACRO(msg) 224 #define _MHD_NO_DEPR_FUNC 1 225 #define _MHD_DEPR_FUNC(msg) 226 #endif /* MHD_NO_DEPRECATION */ 227 228 #ifndef _MHD_DEPR_MACRO 229 #if defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1500 230 /* VS 2008 or later */ 231 /* Stringify macros */ 232 #define _MHD_INSTRMACRO(a) #a 233 #define _MHD_STRMACRO(a) _MHD_INSTRMACRO (a) 234 /* deprecation message */ 235 #define _MHD_DEPR_MACRO(msg) \ 236 __pragma \ 237 (message (__FILE__ "(" _MHD_STRMACRO ( __LINE__) "): warning: " msg)) 238 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 239 #elif defined(__clang__) || defined(__GNUC_PATCHLEVEL__) 240 /* clang or GCC since 3.0 */ 241 #define _MHD_GCC_PRAG(x) _Pragma(#x) 242 #if (defined(__clang__) && \ 243 (__clang_major__ + 0 >= 5 || \ 244 (! defined(__apple_build_version__) && \ 245 (__clang_major__ + 0 > 3 || \ 246 (__clang_major__ + 0 == 3 && __clang_minor__ >= 3))))) || \ 247 __GNUC__ + 0 > 4 || (__GNUC__ + 0 == 4 && __GNUC_MINOR__ + 0 >= 8) 248 /* clang >= 3.3 (or XCode's clang >= 5.0) or 249 GCC >= 4.8 */ 250 #define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG (GCC warning msg) 251 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 252 #else /* older clang or GCC */ 253 /* clang < 3.3, XCode's clang < 5.0, 3.0 <= GCC < 4.8 */ 254 #define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG (message msg) 255 #if (defined(__clang__) && \ 256 (__clang_major__ + 0 > 2 || \ 257 (__clang_major__ + 0 == 2 && __clang_minor__ >= 9))) /* clang >= 2.9 */ 258 /* clang handles inline pragmas better than GCC */ 259 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 260 #endif /* clang >= 2.9 */ 261 #endif /* older clang or GCC */ 262 /* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ 263 #endif /* clang || GCC >= 3.0 */ 264 #endif /* !_MHD_DEPR_MACRO */ 265 266 #ifndef _MHD_DEPR_MACRO 267 #define _MHD_DEPR_MACRO(msg) 268 #endif /* !_MHD_DEPR_MACRO */ 269 270 #ifndef _MHD_DEPR_IN_MACRO 271 #define _MHD_NO_DEPR_IN_MACRO 1 272 #define _MHD_DEPR_IN_MACRO(msg) 273 #endif /* !_MHD_DEPR_IN_MACRO */ 274 275 #ifndef _MHD_DEPR_FUNC 276 #if defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1400 277 /* VS 2005 or later */ 278 #define _MHD_DEPR_FUNC(msg) __declspec(deprecated (msg)) 279 #elif defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1310 280 /* VS .NET 2003 deprecation does not support custom messages */ 281 #define _MHD_DEPR_FUNC(msg) __declspec(deprecated) 282 #elif (__GNUC__ + 0 >= 5) || (defined(__clang__) && \ 283 (__clang_major__ + 0 > 2 || \ 284 (__clang_major__ + 0 == 2 && __clang_minor__ >= 9))) 285 /* GCC >= 5.0 or clang >= 2.9 */ 286 #define _MHD_DEPR_FUNC(msg) __attribute__((deprecated (msg))) 287 #elif defined(__clang__) || __GNUC__ + 0 > 3 || \ 288 (__GNUC__ + 0 == 3 && __GNUC_MINOR__ + 0 >= 1) 289 /* 3.1 <= GCC < 5.0 or clang < 2.9 */ 290 /* old GCC-style deprecation does not support custom messages */ 291 #define _MHD_DEPR_FUNC(msg) __attribute__((__deprecated__)) 292 /* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ 293 #endif /* clang < 2.9 || GCC >= 3.1 */ 294 #endif /* !_MHD_DEPR_FUNC */ 295 296 #ifndef _MHD_DEPR_FUNC 297 #define _MHD_NO_DEPR_FUNC 1 298 #define _MHD_DEPR_FUNC(msg) 299 #endif /* !_MHD_DEPR_FUNC */ 300 301 /** 302 * Not all architectures and `printf()`'s support the `long long` type. 303 * This gives the ability to replace `long long` with just a `long`, 304 * standard `int` or a `short`. 305 */ 306 #ifndef MHD_LONG_LONG 307 /** 308 * @deprecated use #MHD_UNSIGNED_LONG_LONG instead! 309 */ 310 #define MHD_LONG_LONG long long 311 #define MHD_UNSIGNED_LONG_LONG unsigned long long 312 #else /* MHD_LONG_LONG */ 313 _MHD_DEPR_MACRO ( \ 314 "Macro MHD_LONG_LONG is deprecated, use MHD_UNSIGNED_LONG_LONG") 315 #endif 316 /** 317 * Format string for printing a variable of type #MHD_LONG_LONG. 318 * You should only redefine this if you also define #MHD_LONG_LONG. 319 */ 320 #ifndef MHD_LONG_LONG_PRINTF 321 /** 322 * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead! 323 */ 324 #define MHD_LONG_LONG_PRINTF "ll" 325 #define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" 326 #else /* MHD_LONG_LONG_PRINTF */ 327 _MHD_DEPR_MACRO ( \ 328 "Macro MHD_LONG_LONG_PRINTF is deprecated, use MHD_UNSIGNED_LONG_LONG_PRINTF") 329 #endif 330 331 332 /** 333 * @defgroup httpcode HTTP response codes. 334 * These are the status codes defined for HTTP responses. 335 * See: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 336 * Registry export date: 2023-09-29 337 * @{ 338 */ 339 340 /* 100 "Continue". RFC9110, Section 15.2.1. */ 341 #define MHD_HTTP_CONTINUE 100 342 /* 101 "Switching Protocols". RFC9110, Section 15.2.2. */ 343 #define MHD_HTTP_SWITCHING_PROTOCOLS 101 344 /* 102 "Processing". RFC2518. */ 345 #define MHD_HTTP_PROCESSING 102 346 /* 103 "Early Hints". RFC8297. */ 347 #define MHD_HTTP_EARLY_HINTS 103 348 349 /* 200 "OK". RFC9110, Section 15.3.1. */ 350 #define MHD_HTTP_OK 200 351 /* 201 "Created". RFC9110, Section 15.3.2. */ 352 #define MHD_HTTP_CREATED 201 353 /* 202 "Accepted". RFC9110, Section 15.3.3. */ 354 #define MHD_HTTP_ACCEPTED 202 355 /* 203 "Non-Authoritative Information". RFC9110, Section 15.3.4. */ 356 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 357 /* 204 "No Content". RFC9110, Section 15.3.5. */ 358 #define MHD_HTTP_NO_CONTENT 204 359 /* 205 "Reset Content". RFC9110, Section 15.3.6. */ 360 #define MHD_HTTP_RESET_CONTENT 205 361 /* 206 "Partial Content". RFC9110, Section 15.3.7. */ 362 #define MHD_HTTP_PARTIAL_CONTENT 206 363 /* 207 "Multi-Status". RFC4918. */ 364 #define MHD_HTTP_MULTI_STATUS 207 365 /* 208 "Already Reported". RFC5842. */ 366 #define MHD_HTTP_ALREADY_REPORTED 208 367 368 /* 226 "IM Used". RFC3229. */ 369 #define MHD_HTTP_IM_USED 226 370 371 /* 300 "Multiple Choices". RFC9110, Section 15.4.1. */ 372 #define MHD_HTTP_MULTIPLE_CHOICES 300 373 /* 301 "Moved Permanently". RFC9110, Section 15.4.2. */ 374 #define MHD_HTTP_MOVED_PERMANENTLY 301 375 /* 302 "Found". RFC9110, Section 15.4.3. */ 376 #define MHD_HTTP_FOUND 302 377 /* 303 "See Other". RFC9110, Section 15.4.4. */ 378 #define MHD_HTTP_SEE_OTHER 303 379 /* 304 "Not Modified". RFC9110, Section 15.4.5. */ 380 #define MHD_HTTP_NOT_MODIFIED 304 381 /* 305 "Use Proxy". RFC9110, Section 15.4.6. */ 382 #define MHD_HTTP_USE_PROXY 305 383 /* 306 "Switch Proxy". Not used! RFC9110, Section 15.4.7. */ 384 #define MHD_HTTP_SWITCH_PROXY 306 385 /* 307 "Temporary Redirect". RFC9110, Section 15.4.8. */ 386 #define MHD_HTTP_TEMPORARY_REDIRECT 307 387 /* 308 "Permanent Redirect". RFC9110, Section 15.4.9. */ 388 #define MHD_HTTP_PERMANENT_REDIRECT 308 389 390 /* 400 "Bad Request". RFC9110, Section 15.5.1. */ 391 #define MHD_HTTP_BAD_REQUEST 400 392 /* 401 "Unauthorized". RFC9110, Section 15.5.2. */ 393 #define MHD_HTTP_UNAUTHORIZED 401 394 /* 402 "Payment Required". RFC9110, Section 15.5.3. */ 395 #define MHD_HTTP_PAYMENT_REQUIRED 402 396 /* 403 "Forbidden". RFC9110, Section 15.5.4. */ 397 #define MHD_HTTP_FORBIDDEN 403 398 /* 404 "Not Found". RFC9110, Section 15.5.5. */ 399 #define MHD_HTTP_NOT_FOUND 404 400 /* 405 "Method Not Allowed". RFC9110, Section 15.5.6. */ 401 #define MHD_HTTP_METHOD_NOT_ALLOWED 405 402 /* 406 "Not Acceptable". RFC9110, Section 15.5.7. */ 403 #define MHD_HTTP_NOT_ACCEPTABLE 406 404 /* 407 "Proxy Authentication Required". RFC9110, Section 15.5.8. */ 405 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 406 /* 408 "Request Timeout". RFC9110, Section 15.5.9. */ 407 #define MHD_HTTP_REQUEST_TIMEOUT 408 408 /* 409 "Conflict". RFC9110, Section 15.5.10. */ 409 #define MHD_HTTP_CONFLICT 409 410 /* 410 "Gone". RFC9110, Section 15.5.11. */ 411 #define MHD_HTTP_GONE 410 412 /* 411 "Length Required". RFC9110, Section 15.5.12. */ 413 #define MHD_HTTP_LENGTH_REQUIRED 411 414 /* 412 "Precondition Failed". RFC9110, Section 15.5.13. */ 415 #define MHD_HTTP_PRECONDITION_FAILED 412 416 /* 413 "Content Too Large". RFC9110, Section 15.5.14. */ 417 #define MHD_HTTP_CONTENT_TOO_LARGE 413 418 /* 414 "URI Too Long". RFC9110, Section 15.5.15. */ 419 #define MHD_HTTP_URI_TOO_LONG 414 420 /* 415 "Unsupported Media Type". RFC9110, Section 15.5.16. */ 421 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 422 /* 416 "Range Not Satisfiable". RFC9110, Section 15.5.17. */ 423 #define MHD_HTTP_RANGE_NOT_SATISFIABLE 416 424 /* 417 "Expectation Failed". RFC9110, Section 15.5.18. */ 425 #define MHD_HTTP_EXPECTATION_FAILED 417 426 427 428 /* 421 "Misdirected Request". RFC9110, Section 15.5.20. */ 429 #define MHD_HTTP_MISDIRECTED_REQUEST 421 430 /* 422 "Unprocessable Content". RFC9110, Section 15.5.21. */ 431 #define MHD_HTTP_UNPROCESSABLE_CONTENT 422 432 /* 423 "Locked". RFC4918. */ 433 #define MHD_HTTP_LOCKED 423 434 /* 424 "Failed Dependency". RFC4918. */ 435 #define MHD_HTTP_FAILED_DEPENDENCY 424 436 /* 425 "Too Early". RFC8470. */ 437 #define MHD_HTTP_TOO_EARLY 425 438 /* 426 "Upgrade Required". RFC9110, Section 15.5.22. */ 439 #define MHD_HTTP_UPGRADE_REQUIRED 426 440 441 /* 428 "Precondition Required". RFC6585. */ 442 #define MHD_HTTP_PRECONDITION_REQUIRED 428 443 /* 429 "Too Many Requests". RFC6585. */ 444 #define MHD_HTTP_TOO_MANY_REQUESTS 429 445 446 /* 431 "Request Header Fields Too Large". RFC6585. */ 447 #define MHD_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE 431 448 449 /* 451 "Unavailable For Legal Reasons". RFC7725. */ 450 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 451 452 /* 500 "Internal Server Error". RFC9110, Section 15.6.1. */ 453 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500 454 /* 501 "Not Implemented". RFC9110, Section 15.6.2. */ 455 #define MHD_HTTP_NOT_IMPLEMENTED 501 456 /* 502 "Bad Gateway". RFC9110, Section 15.6.3. */ 457 #define MHD_HTTP_BAD_GATEWAY 502 458 /* 503 "Service Unavailable". RFC9110, Section 15.6.4. */ 459 #define MHD_HTTP_SERVICE_UNAVAILABLE 503 460 /* 504 "Gateway Timeout". RFC9110, Section 15.6.5. */ 461 #define MHD_HTTP_GATEWAY_TIMEOUT 504 462 /* 505 "HTTP Version Not Supported". RFC9110, Section 15.6.6. */ 463 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 464 /* 506 "Variant Also Negotiates". RFC2295. */ 465 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 466 /* 507 "Insufficient Storage". RFC4918. */ 467 #define MHD_HTTP_INSUFFICIENT_STORAGE 507 468 /* 508 "Loop Detected". RFC5842. */ 469 #define MHD_HTTP_LOOP_DETECTED 508 470 471 /* 510 "Not Extended". (OBSOLETED) RFC2774; status-change-http-experiments-to-historic. */ 472 #define MHD_HTTP_NOT_EXTENDED 510 473 /* 511 "Network Authentication Required". RFC6585. */ 474 #define MHD_HTTP_NETWORK_AUTHENTICATION_REQUIRED 511 475 476 477 /* Not registered non-standard codes */ 478 /* 449 "Reply With". MS IIS extension. */ 479 #define MHD_HTTP_RETRY_WITH 449 480 481 /* 450 "Blocked by Windows Parental Controls". MS extension. */ 482 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 483 484 /* 509 "Bandwidth Limit Exceeded". Apache extension. */ 485 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 486 487 /* Deprecated names and codes */ 488 /** @deprecated */ 489 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE _MHD_DEPR_IN_MACRO ( \ 490 "Value MHD_HTTP_METHOD_NOT_ACCEPTABLE is deprecated, use MHD_HTTP_NOT_ACCEPTABLE" \ 491 ) 406 492 493 /** @deprecated */ 494 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE _MHD_DEPR_IN_MACRO ( \ 495 "Value MHD_HTTP_REQUEST_ENTITY_TOO_LARGE is deprecated, use MHD_HTTP_CONTENT_TOO_LARGE" \ 496 ) 413 497 498 /** @deprecated */ 499 #define MHD_HTTP_PAYLOAD_TOO_LARGE _MHD_DEPR_IN_MACRO ( \ 500 "Value MHD_HTTP_PAYLOAD_TOO_LARGE is deprecated use MHD_HTTP_CONTENT_TOO_LARGE" \ 501 ) 413 502 503 /** @deprecated */ 504 #define MHD_HTTP_REQUEST_URI_TOO_LONG _MHD_DEPR_IN_MACRO ( \ 505 "Value MHD_HTTP_REQUEST_URI_TOO_LONG is deprecated, use MHD_HTTP_URI_TOO_LONG" \ 506 ) 414 507 508 /** @deprecated */ 509 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE _MHD_DEPR_IN_MACRO ( \ 510 "Value MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE is deprecated, use MHD_HTTP_RANGE_NOT_SATISFIABLE" \ 511 ) 416 512 513 /** @deprecated */ 514 #define MHD_HTTP_UNPROCESSABLE_ENTITY _MHD_DEPR_IN_MACRO ( \ 515 "Value MHD_HTTP_UNPROCESSABLE_ENTITY is deprecated, use MHD_HTTP_UNPROCESSABLE_CONTENT" \ 516 ) 422 517 518 /** @deprecated */ 519 #define MHD_HTTP_UNORDERED_COLLECTION _MHD_DEPR_IN_MACRO ( \ 520 "Value MHD_HTTP_UNORDERED_COLLECTION is deprecated as it was removed from RFC" \ 521 ) 425 522 523 /** @deprecated */ 524 #define MHD_HTTP_NO_RESPONSE _MHD_DEPR_IN_MACRO ( \ 525 "Value MHD_HTTP_NO_RESPONSE is deprecated as it is nginx internal code for logs only" \ 526 ) 444 527 528 529 /** @} */ /* end of group httpcode */ 530 531 /** 532 * Returns the string reason phrase for a response code. 533 * 534 * If message string is not available for a status code, 535 * "Unknown" string will be returned. 536 */ 537 _MHD_EXTERN const char * 538 MHD_get_reason_phrase_for (unsigned int code); 539 540 541 /** 542 * Returns the length of the string reason phrase for a response code. 543 * 544 * If message string is not available for a status code, 545 * 0 is returned. 546 */ 547 _MHD_EXTERN size_t 548 MHD_get_reason_phrase_len_for (unsigned int code); 549 550 /** 551 * Flag to be or-ed with MHD_HTTP status code for 552 * SHOUTcast. This will cause the response to begin 553 * with the SHOUTcast "ICY" line instead of "HTTP/1.x". 554 * @ingroup specialized 555 */ 556 #define MHD_ICY_FLAG ((uint32_t) (((uint32_t) 1) << 31)) 557 558 /** 559 * @defgroup headers HTTP headers 560 * The standard headers found in HTTP requests and responses. 561 * See: https://www.iana.org/assignments/http-fields/http-fields.xhtml 562 * Registry export date: 2023-10-02 563 * @{ 564 */ 565 566 /* Main HTTP headers. */ 567 /* Permanent. RFC9110, Section 12.5.1: HTTP Semantics */ 568 #define MHD_HTTP_HEADER_ACCEPT "Accept" 569 /* Deprecated. RFC9110, Section 12.5.2: HTTP Semantics */ 570 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" 571 /* Permanent. RFC9110, Section 12.5.3: HTTP Semantics */ 572 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" 573 /* Permanent. RFC9110, Section 12.5.4: HTTP Semantics */ 574 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" 575 /* Permanent. RFC9110, Section 14.3: HTTP Semantics */ 576 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" 577 /* Permanent. RFC9111, Section 5.1: HTTP Caching */ 578 #define MHD_HTTP_HEADER_AGE "Age" 579 /* Permanent. RFC9110, Section 10.2.1: HTTP Semantics */ 580 #define MHD_HTTP_HEADER_ALLOW "Allow" 581 /* Permanent. RFC9110, Section 11.6.3: HTTP Semantics */ 582 #define MHD_HTTP_HEADER_AUTHENTICATION_INFO "Authentication-Info" 583 /* Permanent. RFC9110, Section 11.6.2: HTTP Semantics */ 584 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" 585 /* Permanent. RFC9111, Section 5.2 */ 586 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" 587 /* Permanent. RFC9112, Section 9.6: HTTP/1.1 */ 588 #define MHD_HTTP_HEADER_CLOSE "Close" 589 /* Permanent. RFC9110, Section 7.6.1: HTTP Semantics */ 590 #define MHD_HTTP_HEADER_CONNECTION "Connection" 591 /* Permanent. RFC9110, Section 8.4: HTTP Semantics */ 592 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" 593 /* Permanent. RFC9110, Section 8.5: HTTP Semantics */ 594 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" 595 /* Permanent. RFC9110, Section 8.6: HTTP Semantics */ 596 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" 597 /* Permanent. RFC9110, Section 8.7: HTTP Semantics */ 598 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" 599 /* Permanent. RFC9110, Section 14.4: HTTP Semantics */ 600 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" 601 /* Permanent. RFC9110, Section 8.3: HTTP Semantics */ 602 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" 603 /* Permanent. RFC9110, Section 6.6.1: HTTP Semantics */ 604 #define MHD_HTTP_HEADER_DATE "Date" 605 /* Permanent. RFC9110, Section 8.8.3: HTTP Semantics */ 606 #define MHD_HTTP_HEADER_ETAG "ETag" 607 /* Permanent. RFC9110, Section 10.1.1: HTTP Semantics */ 608 #define MHD_HTTP_HEADER_EXPECT "Expect" 609 /* Permanent. RFC9111, Section 5.3: HTTP Caching */ 610 #define MHD_HTTP_HEADER_EXPIRES "Expires" 611 /* Permanent. RFC9110, Section 10.1.2: HTTP Semantics */ 612 #define MHD_HTTP_HEADER_FROM "From" 613 /* Permanent. RFC9110, Section 7.2: HTTP Semantics */ 614 #define MHD_HTTP_HEADER_HOST "Host" 615 /* Permanent. RFC9110, Section 13.1.1: HTTP Semantics */ 616 #define MHD_HTTP_HEADER_IF_MATCH "If-Match" 617 /* Permanent. RFC9110, Section 13.1.3: HTTP Semantics */ 618 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" 619 /* Permanent. RFC9110, Section 13.1.2: HTTP Semantics */ 620 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" 621 /* Permanent. RFC9110, Section 13.1.5: HTTP Semantics */ 622 #define MHD_HTTP_HEADER_IF_RANGE "If-Range" 623 /* Permanent. RFC9110, Section 13.1.4: HTTP Semantics */ 624 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" 625 /* Permanent. RFC9110, Section 8.8.2: HTTP Semantics */ 626 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" 627 /* Permanent. RFC9110, Section 10.2.2: HTTP Semantics */ 628 #define MHD_HTTP_HEADER_LOCATION "Location" 629 /* Permanent. RFC9110, Section 7.6.2: HTTP Semantics */ 630 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" 631 /* Permanent. RFC9112, Appendix B.1: HTTP/1.1 */ 632 #define MHD_HTTP_HEADER_MIME_VERSION "MIME-Version" 633 /* Deprecated. RFC9111, Section 5.4: HTTP Caching */ 634 #define MHD_HTTP_HEADER_PRAGMA "Pragma" 635 /* Permanent. RFC9110, Section 11.7.1: HTTP Semantics */ 636 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" 637 /* Permanent. RFC9110, Section 11.7.3: HTTP Semantics */ 638 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATION_INFO "Proxy-Authentication-Info" 639 /* Permanent. RFC9110, Section 11.7.2: HTTP Semantics */ 640 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" 641 /* Permanent. RFC9110, Section 14.2: HTTP Semantics */ 642 #define MHD_HTTP_HEADER_RANGE "Range" 643 /* Permanent. RFC9110, Section 10.1.3: HTTP Semantics */ 644 #define MHD_HTTP_HEADER_REFERER "Referer" 645 /* Permanent. RFC9110, Section 10.2.3: HTTP Semantics */ 646 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" 647 /* Permanent. RFC9110, Section 10.2.4: HTTP Semantics */ 648 #define MHD_HTTP_HEADER_SERVER "Server" 649 /* Permanent. RFC9110, Section 10.1.4: HTTP Semantics */ 650 #define MHD_HTTP_HEADER_TE "TE" 651 /* Permanent. RFC9110, Section 6.6.2: HTTP Semantics */ 652 #define MHD_HTTP_HEADER_TRAILER "Trailer" 653 /* Permanent. RFC9112, Section 6.1: HTTP Semantics */ 654 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" 655 /* Permanent. RFC9110, Section 7.8: HTTP Semantics */ 656 #define MHD_HTTP_HEADER_UPGRADE "Upgrade" 657 /* Permanent. RFC9110, Section 10.1.5: HTTP Semantics */ 658 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent" 659 /* Permanent. RFC9110, Section 12.5.5: HTTP Semantics */ 660 #define MHD_HTTP_HEADER_VARY "Vary" 661 /* Permanent. RFC9110, Section 7.6.3: HTTP Semantics */ 662 #define MHD_HTTP_HEADER_VIA "Via" 663 /* Permanent. RFC9110, Section 11.6.1: HTTP Semantics */ 664 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" 665 /* Permanent. RFC9110, Section 12.5.5: HTTP Semantics */ 666 #define MHD_HTTP_HEADER_ASTERISK "*" 667 668 /* Additional HTTP headers. */ 669 /* Permanent. RFC 3229: Delta encoding in HTTP */ 670 #define MHD_HTTP_HEADER_A_IM "A-IM" 671 /* Permanent. RFC 2324: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) */ 672 #define MHD_HTTP_HEADER_ACCEPT_ADDITIONS "Accept-Additions" 673 /* Permanent. RFC 8942, Section 3.1: HTTP Client Hints */ 674 #define MHD_HTTP_HEADER_ACCEPT_CH "Accept-CH" 675 /* Permanent. RFC 7089: HTTP Framework for Time-Based Access to Resource States -- Memento */ 676 #define MHD_HTTP_HEADER_ACCEPT_DATETIME "Accept-Datetime" 677 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 678 #define MHD_HTTP_HEADER_ACCEPT_FEATURES "Accept-Features" 679 /* Permanent. RFC 5789: PATCH Method for HTTP */ 680 #define MHD_HTTP_HEADER_ACCEPT_PATCH "Accept-Patch" 681 /* Permanent. Linked Data Platform 1.0 */ 682 #define MHD_HTTP_HEADER_ACCEPT_POST "Accept-Post" 683 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 5.1: HTTP Message Signatures */ 684 #define MHD_HTTP_HEADER_ACCEPT_SIGNATURE "Accept-Signature" 685 /* Permanent. Fetch */ 686 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS \ 687 "Access-Control-Allow-Credentials" 688 /* Permanent. Fetch */ 689 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_HEADERS \ 690 "Access-Control-Allow-Headers" 691 /* Permanent. Fetch */ 692 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_METHODS \ 693 "Access-Control-Allow-Methods" 694 /* Permanent. Fetch */ 695 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN \ 696 "Access-Control-Allow-Origin" 697 /* Permanent. Fetch */ 698 #define MHD_HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS \ 699 "Access-Control-Expose-Headers" 700 /* Permanent. Fetch */ 701 #define MHD_HTTP_HEADER_ACCESS_CONTROL_MAX_AGE "Access-Control-Max-Age" 702 /* Permanent. Fetch */ 703 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_HEADERS \ 704 "Access-Control-Request-Headers" 705 /* Permanent. Fetch */ 706 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_METHOD \ 707 "Access-Control-Request-Method" 708 /* Permanent. RFC 7639, Section 2: The ALPN HTTP Header Field */ 709 #define MHD_HTTP_HEADER_ALPN "ALPN" 710 /* Permanent. RFC 7838: HTTP Alternative Services */ 711 #define MHD_HTTP_HEADER_ALT_SVC "Alt-Svc" 712 /* Permanent. RFC 7838: HTTP Alternative Services */ 713 #define MHD_HTTP_HEADER_ALT_USED "Alt-Used" 714 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 715 #define MHD_HTTP_HEADER_ALTERNATES "Alternates" 716 /* Permanent. RFC 4437: Web Distributed Authoring and Versioning (WebDAV) Redirect Reference Resources */ 717 #define MHD_HTTP_HEADER_APPLY_TO_REDIRECT_REF "Apply-To-Redirect-Ref" 718 /* Permanent. RFC 8053, Section 4: HTTP Authentication Extensions for Interactive Clients */ 719 #define MHD_HTTP_HEADER_AUTHENTICATION_CONTROL "Authentication-Control" 720 /* Permanent. RFC9211: The Cache-Status HTTP Response Header Field */ 721 #define MHD_HTTP_HEADER_CACHE_STATUS "Cache-Status" 722 /* Permanent. RFC 8607, Section 5.1: Calendaring Extensions to WebDAV (CalDAV): Managed Attachments */ 723 #define MHD_HTTP_HEADER_CAL_MANAGED_ID "Cal-Managed-ID" 724 /* Permanent. RFC 7809, Section 7.1: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference */ 725 #define MHD_HTTP_HEADER_CALDAV_TIMEZONES "CalDAV-Timezones" 726 /* Permanent. RFC9297 */ 727 #define MHD_HTTP_HEADER_CAPSULE_PROTOCOL "Capsule-Protocol" 728 /* Permanent. RFC9213: Targeted HTTP Cache Control */ 729 #define MHD_HTTP_HEADER_CDN_CACHE_CONTROL "CDN-Cache-Control" 730 /* Permanent. RFC 8586: Loop Detection in Content Delivery Networks (CDNs) */ 731 #define MHD_HTTP_HEADER_CDN_LOOP "CDN-Loop" 732 /* Permanent. RFC 8739, Section 3.3: Support for Short-Term, Automatically Renewed (STAR) Certificates in the Automated Certificate Management Environment (ACME) */ 733 #define MHD_HTTP_HEADER_CERT_NOT_AFTER "Cert-Not-After" 734 /* Permanent. RFC 8739, Section 3.3: Support for Short-Term, Automatically Renewed (STAR) Certificates in the Automated Certificate Management Environment (ACME) */ 735 #define MHD_HTTP_HEADER_CERT_NOT_BEFORE "Cert-Not-Before" 736 /* Permanent. Clear Site Data */ 737 #define MHD_HTTP_HEADER_CLEAR_SITE_DATA "Clear-Site-Data" 738 /* Permanent. RFC9440, Section 2: Client-Cert HTTP Header Field */ 739 #define MHD_HTTP_HEADER_CLIENT_CERT "Client-Cert" 740 /* Permanent. RFC9440, Section 2: Client-Cert HTTP Header Field */ 741 #define MHD_HTTP_HEADER_CLIENT_CERT_CHAIN "Client-Cert-Chain" 742 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 2: Digest Fields */ 743 #define MHD_HTTP_HEADER_CONTENT_DIGEST "Content-Digest" 744 /* Permanent. RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) */ 745 #define MHD_HTTP_HEADER_CONTENT_DISPOSITION "Content-Disposition" 746 /* Permanent. The HTTP Distribution and Replication Protocol */ 747 #define MHD_HTTP_HEADER_CONTENT_ID "Content-ID" 748 /* Permanent. Content Security Policy Level 3 */ 749 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY "Content-Security-Policy" 750 /* Permanent. Content Security Policy Level 3 */ 751 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY_REPORT_ONLY \ 752 "Content-Security-Policy-Report-Only" 753 /* Permanent. RFC 6265: HTTP State Management Mechanism */ 754 #define MHD_HTTP_HEADER_COOKIE "Cookie" 755 /* Permanent. HTML */ 756 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY \ 757 "Cross-Origin-Embedder-Policy" 758 /* Permanent. HTML */ 759 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY \ 760 "Cross-Origin-Embedder-Policy-Report-Only" 761 /* Permanent. HTML */ 762 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY "Cross-Origin-Opener-Policy" 763 /* Permanent. HTML */ 764 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY \ 765 "Cross-Origin-Opener-Policy-Report-Only" 766 /* Permanent. Fetch */ 767 #define MHD_HTTP_HEADER_CROSS_ORIGIN_RESOURCE_POLICY \ 768 "Cross-Origin-Resource-Policy" 769 /* Permanent. RFC 5323: Web Distributed Authoring and Versioning (WebDAV) SEARCH */ 770 #define MHD_HTTP_HEADER_DASL "DASL" 771 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 772 #define MHD_HTTP_HEADER_DAV "DAV" 773 /* Permanent. RFC 3229: Delta encoding in HTTP */ 774 #define MHD_HTTP_HEADER_DELTA_BASE "Delta-Base" 775 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 776 #define MHD_HTTP_HEADER_DEPTH "Depth" 777 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 778 #define MHD_HTTP_HEADER_DESTINATION "Destination" 779 /* Permanent. The HTTP Distribution and Replication Protocol */ 780 #define MHD_HTTP_HEADER_DIFFERENTIAL_ID "Differential-ID" 781 /* Permanent. RFC9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) */ 782 #define MHD_HTTP_HEADER_DPOP "DPoP" 783 /* Permanent. RFC9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) */ 784 #define MHD_HTTP_HEADER_DPOP_NONCE "DPoP-Nonce" 785 /* Permanent. RFC 8470: Using Early Data in HTTP */ 786 #define MHD_HTTP_HEADER_EARLY_DATA "Early-Data" 787 /* Permanent. RFC9163: Expect-CT Extension for HTTP */ 788 #define MHD_HTTP_HEADER_EXPECT_CT "Expect-CT" 789 /* Permanent. RFC 7239: Forwarded HTTP Extension */ 790 #define MHD_HTTP_HEADER_FORWARDED "Forwarded" 791 /* Permanent. RFC 7486, Section 6.1.1: HTTP Origin-Bound Authentication (HOBA) */ 792 #define MHD_HTTP_HEADER_HOBAREG "Hobareg" 793 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 794 #define MHD_HTTP_HEADER_IF "If" 795 /* Permanent. RFC 6338: Scheduling Extensions to CalDAV */ 796 #define MHD_HTTP_HEADER_IF_SCHEDULE_TAG_MATCH "If-Schedule-Tag-Match" 797 /* Permanent. RFC 3229: Delta encoding in HTTP */ 798 #define MHD_HTTP_HEADER_IM "IM" 799 /* Permanent. RFC 8473: Token Binding over HTTP */ 800 #define MHD_HTTP_HEADER_INCLUDE_REFERRED_TOKEN_BINDING_ID \ 801 "Include-Referred-Token-Binding-ID" 802 /* Permanent. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 803 #define MHD_HTTP_HEADER_KEEP_ALIVE "Keep-Alive" 804 /* Permanent. RFC 3253: Versioning Extensions to WebDAV: (Web Distributed Authoring and Versioning) */ 805 #define MHD_HTTP_HEADER_LABEL "Label" 806 /* Permanent. HTML */ 807 #define MHD_HTTP_HEADER_LAST_EVENT_ID "Last-Event-ID" 808 /* Permanent. RFC 8288: Web Linking */ 809 #define MHD_HTTP_HEADER_LINK "Link" 810 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 811 #define MHD_HTTP_HEADER_LOCK_TOKEN "Lock-Token" 812 /* Permanent. RFC 7089: HTTP Framework for Time-Based Access to Resource States -- Memento */ 813 #define MHD_HTTP_HEADER_MEMENTO_DATETIME "Memento-Datetime" 814 /* Permanent. RFC 2227: Simple Hit-Metering and Usage-Limiting for HTTP */ 815 #define MHD_HTTP_HEADER_METER "Meter" 816 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 817 #define MHD_HTTP_HEADER_NEGOTIATE "Negotiate" 818 /* Permanent. Network Error Logging */ 819 #define MHD_HTTP_HEADER_NEL "NEL" 820 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 821 #define MHD_HTTP_HEADER_ODATA_ENTITYID "OData-EntityId" 822 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 823 #define MHD_HTTP_HEADER_ODATA_ISOLATION "OData-Isolation" 824 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 825 #define MHD_HTTP_HEADER_ODATA_MAXVERSION "OData-MaxVersion" 826 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 827 #define MHD_HTTP_HEADER_ODATA_VERSION "OData-Version" 828 /* Permanent. RFC 8053, Section 3: HTTP Authentication Extensions for Interactive Clients */ 829 #define MHD_HTTP_HEADER_OPTIONAL_WWW_AUTHENTICATE "Optional-WWW-Authenticate" 830 /* Permanent. RFC 3648: Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol */ 831 #define MHD_HTTP_HEADER_ORDERING_TYPE "Ordering-Type" 832 /* Permanent. RFC 6454: The Web Origin Concept */ 833 #define MHD_HTTP_HEADER_ORIGIN "Origin" 834 /* Permanent. HTML */ 835 #define MHD_HTTP_HEADER_ORIGIN_AGENT_CLUSTER "Origin-Agent-Cluster" 836 /* Permanent. RFC 8613, Section 11.1: Object Security for Constrained RESTful Environments (OSCORE) */ 837 #define MHD_HTTP_HEADER_OSCORE "OSCORE" 838 /* Permanent. OASIS Project Specification 01; OASIS; Chet_Ensign */ 839 #define MHD_HTTP_HEADER_OSLC_CORE_VERSION "OSLC-Core-Version" 840 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 841 #define MHD_HTTP_HEADER_OVERWRITE "Overwrite" 842 /* Permanent. HTML */ 843 #define MHD_HTTP_HEADER_PING_FROM "Ping-From" 844 /* Permanent. HTML */ 845 #define MHD_HTTP_HEADER_PING_TO "Ping-To" 846 /* Permanent. RFC 3648: Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol */ 847 #define MHD_HTTP_HEADER_POSITION "Position" 848 /* Permanent. RFC 7240: Prefer Header for HTTP */ 849 #define MHD_HTTP_HEADER_PREFER "Prefer" 850 /* Permanent. RFC 7240: Prefer Header for HTTP */ 851 #define MHD_HTTP_HEADER_PREFERENCE_APPLIED "Preference-Applied" 852 /* Permanent. RFC9218: Extensible Prioritization Scheme for HTTP */ 853 #define MHD_HTTP_HEADER_PRIORITY "Priority" 854 /* Permanent. RFC9209: The Proxy-Status HTTP Response Header Field */ 855 #define MHD_HTTP_HEADER_PROXY_STATUS "Proxy-Status" 856 /* Permanent. RFC 7469: Public Key Pinning Extension for HTTP */ 857 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS "Public-Key-Pins" 858 /* Permanent. RFC 7469: Public Key Pinning Extension for HTTP */ 859 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS_REPORT_ONLY \ 860 "Public-Key-Pins-Report-Only" 861 /* Permanent. RFC 4437: Web Distributed Authoring and Versioning (WebDAV) Redirect Reference Resources */ 862 #define MHD_HTTP_HEADER_REDIRECT_REF "Redirect-Ref" 863 /* Permanent. HTML */ 864 #define MHD_HTTP_HEADER_REFRESH "Refresh" 865 /* Permanent. RFC 8555, Section 6.5.1: Automatic Certificate Management Environment (ACME) */ 866 #define MHD_HTTP_HEADER_REPLAY_NONCE "Replay-Nonce" 867 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 3: Digest Fields */ 868 #define MHD_HTTP_HEADER_REPR_DIGEST "Repr-Digest" 869 /* Permanent. RFC 6638: Scheduling Extensions to CalDAV */ 870 #define MHD_HTTP_HEADER_SCHEDULE_REPLY "Schedule-Reply" 871 /* Permanent. RFC 6338: Scheduling Extensions to CalDAV */ 872 #define MHD_HTTP_HEADER_SCHEDULE_TAG "Schedule-Tag" 873 /* Permanent. Fetch */ 874 #define MHD_HTTP_HEADER_SEC_PURPOSE "Sec-Purpose" 875 /* Permanent. RFC 8473: Token Binding over HTTP */ 876 #define MHD_HTTP_HEADER_SEC_TOKEN_BINDING "Sec-Token-Binding" 877 /* Permanent. RFC 6455: The WebSocket Protocol */ 878 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT "Sec-WebSocket-Accept" 879 /* Permanent. RFC 6455: The WebSocket Protocol */ 880 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_EXTENSIONS "Sec-WebSocket-Extensions" 881 /* Permanent. RFC 6455: The WebSocket Protocol */ 882 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY "Sec-WebSocket-Key" 883 /* Permanent. RFC 6455: The WebSocket Protocol */ 884 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_PROTOCOL "Sec-WebSocket-Protocol" 885 /* Permanent. RFC 6455: The WebSocket Protocol */ 886 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION "Sec-WebSocket-Version" 887 /* Permanent. Server Timing */ 888 #define MHD_HTTP_HEADER_SERVER_TIMING "Server-Timing" 889 /* Permanent. RFC 6265: HTTP State Management Mechanism */ 890 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" 891 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 4.2: HTTP Message Signatures */ 892 #define MHD_HTTP_HEADER_SIGNATURE "Signature" 893 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 4.1: HTTP Message Signatures */ 894 #define MHD_HTTP_HEADER_SIGNATURE_INPUT "Signature-Input" 895 /* Permanent. RFC 5023: The Atom Publishing Protocol */ 896 #define MHD_HTTP_HEADER_SLUG "SLUG" 897 /* Permanent. Simple Object Access Protocol (SOAP) 1.1 */ 898 #define MHD_HTTP_HEADER_SOAPACTION "SoapAction" 899 /* Permanent. RFC 2518: HTTP Extensions for Distributed Authoring -- WEBDAV */ 900 #define MHD_HTTP_HEADER_STATUS_URI "Status-URI" 901 /* Permanent. RFC 6797: HTTP Strict Transport Security (HSTS) */ 902 #define MHD_HTTP_HEADER_STRICT_TRANSPORT_SECURITY "Strict-Transport-Security" 903 /* Permanent. RFC 8594: The Sunset HTTP Header Field */ 904 #define MHD_HTTP_HEADER_SUNSET "Sunset" 905 /* Permanent. Edge Architecture Specification */ 906 #define MHD_HTTP_HEADER_SURROGATE_CAPABILITY "Surrogate-Capability" 907 /* Permanent. Edge Architecture Specification */ 908 #define MHD_HTTP_HEADER_SURROGATE_CONTROL "Surrogate-Control" 909 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 910 #define MHD_HTTP_HEADER_TCN "TCN" 911 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 912 #define MHD_HTTP_HEADER_TIMEOUT "Timeout" 913 /* Permanent. RFC 8030, Section 5.4: Generic Event Delivery Using HTTP Push */ 914 #define MHD_HTTP_HEADER_TOPIC "Topic" 915 /* Permanent. Trace Context */ 916 #define MHD_HTTP_HEADER_TRACEPARENT "Traceparent" 917 /* Permanent. Trace Context */ 918 #define MHD_HTTP_HEADER_TRACESTATE "Tracestate" 919 /* Permanent. RFC 8030, Section 5.2: Generic Event Delivery Using HTTP Push */ 920 #define MHD_HTTP_HEADER_TTL "TTL" 921 /* Permanent. RFC 8030, Section 5.3: Generic Event Delivery Using HTTP Push */ 922 #define MHD_HTTP_HEADER_URGENCY "Urgency" 923 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 924 #define MHD_HTTP_HEADER_VARIANT_VARY "Variant-Vary" 925 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 4: Digest Fields */ 926 #define MHD_HTTP_HEADER_WANT_CONTENT_DIGEST "Want-Content-Digest" 927 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 4: Digest Fields */ 928 #define MHD_HTTP_HEADER_WANT_REPR_DIGEST "Want-Repr-Digest" 929 /* Permanent. Fetch */ 930 #define MHD_HTTP_HEADER_X_CONTENT_TYPE_OPTIONS "X-Content-Type-Options" 931 /* Permanent. HTML */ 932 #define MHD_HTTP_HEADER_X_FRAME_OPTIONS "X-Frame-Options" 933 /* Provisional. AMP-Cache-Transform HTTP request header */ 934 #define MHD_HTTP_HEADER_AMP_CACHE_TRANSFORM "AMP-Cache-Transform" 935 /* Provisional. OSLC Configuration Management Version 1.0. Part 3: Configuration Specification */ 936 #define MHD_HTTP_HEADER_CONFIGURATION_CONTEXT "Configuration-Context" 937 /* Provisional. RFC 6017: Electronic Data Interchange - Internet Integration (EDIINT) Features Header Field */ 938 #define MHD_HTTP_HEADER_EDIINT_FEATURES "EDIINT-Features" 939 /* Provisional. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 940 #define MHD_HTTP_HEADER_ISOLATION "Isolation" 941 /* Provisional. Permissions Policy */ 942 #define MHD_HTTP_HEADER_PERMISSIONS_POLICY "Permissions-Policy" 943 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 944 #define MHD_HTTP_HEADER_REPEATABILITY_CLIENT_ID "Repeatability-Client-ID" 945 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 946 #define MHD_HTTP_HEADER_REPEATABILITY_FIRST_SENT "Repeatability-First-Sent" 947 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 948 #define MHD_HTTP_HEADER_REPEATABILITY_REQUEST_ID "Repeatability-Request-ID" 949 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 950 #define MHD_HTTP_HEADER_REPEATABILITY_RESULT "Repeatability-Result" 951 /* Provisional. Reporting API */ 952 #define MHD_HTTP_HEADER_REPORTING_ENDPOINTS "Reporting-Endpoints" 953 /* Provisional. Global Privacy Control (GPC) */ 954 #define MHD_HTTP_HEADER_SEC_GPC "Sec-GPC" 955 /* Provisional. Resource Timing Level 1 */ 956 #define MHD_HTTP_HEADER_TIMING_ALLOW_ORIGIN "Timing-Allow-Origin" 957 /* Deprecated. PEP - an Extension Mechanism for HTTP; status-change-http-experiments-to-historic */ 958 #define MHD_HTTP_HEADER_C_PEP_INFO "C-PEP-Info" 959 /* Deprecated. White Paper: Joint Electronic Payment Initiative */ 960 #define MHD_HTTP_HEADER_PROTOCOL_INFO "Protocol-Info" 961 /* Deprecated. White Paper: Joint Electronic Payment Initiative */ 962 #define MHD_HTTP_HEADER_PROTOCOL_QUERY "Protocol-Query" 963 /* Obsoleted. Access Control for Cross-site Requests */ 964 #define MHD_HTTP_HEADER_ACCESS_CONTROL "Access-Control" 965 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 966 #define MHD_HTTP_HEADER_C_EXT "C-Ext" 967 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 968 #define MHD_HTTP_HEADER_C_MAN "C-Man" 969 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 970 #define MHD_HTTP_HEADER_C_OPT "C-Opt" 971 /* Obsoleted. PEP - an Extension Mechanism for HTTP; status-change-http-experiments-to-historic */ 972 #define MHD_HTTP_HEADER_C_PEP "C-PEP" 973 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1; RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 */ 974 #define MHD_HTTP_HEADER_CONTENT_BASE "Content-Base" 975 /* Obsoleted. RFC 2616, Section 14.15: Hypertext Transfer Protocol -- HTTP/1.1; RFC 7231, Appendix B: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content */ 976 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" 977 /* Obsoleted. HTML 4.01 Specification */ 978 #define MHD_HTTP_HEADER_CONTENT_SCRIPT_TYPE "Content-Script-Type" 979 /* Obsoleted. HTML 4.01 Specification */ 980 #define MHD_HTTP_HEADER_CONTENT_STYLE_TYPE "Content-Style-Type" 981 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 982 #define MHD_HTTP_HEADER_CONTENT_VERSION "Content-Version" 983 /* Obsoleted. RFC 2965: HTTP State Management Mechanism; RFC 6265: HTTP State Management Mechanism */ 984 #define MHD_HTTP_HEADER_COOKIE2 "Cookie2" 985 /* Obsoleted. HTML 4.01 Specification */ 986 #define MHD_HTTP_HEADER_DEFAULT_STYLE "Default-Style" 987 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 988 #define MHD_HTTP_HEADER_DERIVED_FROM "Derived-From" 989 /* Obsoleted. RFC 3230: Instance Digests in HTTP; RFC-ietf-httpbis-digest-headers-13, Section 1.3: Digest Fields */ 990 #define MHD_HTTP_HEADER_DIGEST "Digest" 991 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 992 #define MHD_HTTP_HEADER_EXT "Ext" 993 /* Obsoleted. Implementation of OPS Over HTTP */ 994 #define MHD_HTTP_HEADER_GETPROFILE "GetProfile" 995 /* Obsoleted. RFC 7540, Section 3.2.1: Hypertext Transfer Protocol Version 2 (HTTP/2) */ 996 #define MHD_HTTP_HEADER_HTTP2_SETTINGS "HTTP2-Settings" 997 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 998 #define MHD_HTTP_HEADER_MAN "Man" 999 /* Obsoleted. Access Control for Cross-site Requests */ 1000 #define MHD_HTTP_HEADER_METHOD_CHECK "Method-Check" 1001 /* Obsoleted. Access Control for Cross-site Requests */ 1002 #define MHD_HTTP_HEADER_METHOD_CHECK_EXPIRES "Method-Check-Expires" 1003 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 1004 #define MHD_HTTP_HEADER_OPT "Opt" 1005 /* Obsoleted. The Platform for Privacy Preferences 1.0 (P3P1.0) Specification */ 1006 #define MHD_HTTP_HEADER_P3P "P3P" 1007 /* Obsoleted. PEP - an Extension Mechanism for HTTP */ 1008 #define MHD_HTTP_HEADER_PEP "PEP" 1009 /* Obsoleted. PEP - an Extension Mechanism for HTTP */ 1010 #define MHD_HTTP_HEADER_PEP_INFO "Pep-Info" 1011 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1012 #define MHD_HTTP_HEADER_PICS_LABEL "PICS-Label" 1013 /* Obsoleted. Implementation of OPS Over HTTP */ 1014 #define MHD_HTTP_HEADER_PROFILEOBJECT "ProfileObject" 1015 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1016 #define MHD_HTTP_HEADER_PROTOCOL "Protocol" 1017 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1018 #define MHD_HTTP_HEADER_PROTOCOL_REQUEST "Protocol-Request" 1019 /* Obsoleted. Notification for Proxy Caches */ 1020 #define MHD_HTTP_HEADER_PROXY_FEATURES "Proxy-Features" 1021 /* Obsoleted. Notification for Proxy Caches */ 1022 #define MHD_HTTP_HEADER_PROXY_INSTRUCTION "Proxy-Instruction" 1023 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 1024 #define MHD_HTTP_HEADER_PUBLIC "Public" 1025 /* Obsoleted. Access Control for Cross-site Requests */ 1026 #define MHD_HTTP_HEADER_REFERER_ROOT "Referer-Root" 1027 /* Obsoleted. RFC 2310: The Safe Response Header Field; status-change-http-experiments-to-historic */ 1028 #define MHD_HTTP_HEADER_SAFE "Safe" 1029 /* Obsoleted. RFC 2660: The Secure HyperText Transfer Protocol; status-change-http-experiments-to-historic */ 1030 #define MHD_HTTP_HEADER_SECURITY_SCHEME "Security-Scheme" 1031 /* Obsoleted. RFC 2965: HTTP State Management Mechanism; RFC 6265: HTTP State Management Mechanism */ 1032 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" 1033 /* Obsoleted. Implementation of OPS Over HTTP */ 1034 #define MHD_HTTP_HEADER_SETPROFILE "SetProfile" 1035 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 1036 #define MHD_HTTP_HEADER_URI "URI" 1037 /* Obsoleted. RFC 3230: Instance Digests in HTTP; RFC-ietf-httpbis-digest-headers-13, Section 1.3: Digest Fields */ 1038 #define MHD_HTTP_HEADER_WANT_DIGEST "Want-Digest" 1039 /* Obsoleted. RFC9111, Section 5.5: HTTP Caching */ 1040 #define MHD_HTTP_HEADER_WARNING "Warning" 1041 1042 /* Headers removed from the registry. Do not use! */ 1043 /* Obsoleted. RFC4229 */ 1044 #define MHD_HTTP_HEADER_COMPLIANCE "Compliance" 1045 /* Obsoleted. RFC4229 */ 1046 #define MHD_HTTP_HEADER_CONTENT_TRANSFER_ENCODING "Content-Transfer-Encoding" 1047 /* Obsoleted. RFC4229 */ 1048 #define MHD_HTTP_HEADER_COST "Cost" 1049 /* Obsoleted. RFC4229 */ 1050 #define MHD_HTTP_HEADER_MESSAGE_ID "Message-ID" 1051 /* Obsoleted. RFC4229 */ 1052 #define MHD_HTTP_HEADER_NON_COMPLIANCE "Non-Compliance" 1053 /* Obsoleted. RFC4229 */ 1054 #define MHD_HTTP_HEADER_OPTIONAL "Optional" 1055 /* Obsoleted. RFC4229 */ 1056 #define MHD_HTTP_HEADER_RESOLUTION_HINT "Resolution-Hint" 1057 /* Obsoleted. RFC4229 */ 1058 #define MHD_HTTP_HEADER_RESOLVER_LOCATION "Resolver-Location" 1059 /* Obsoleted. RFC4229 */ 1060 #define MHD_HTTP_HEADER_SUBOK "SubOK" 1061 /* Obsoleted. RFC4229 */ 1062 #define MHD_HTTP_HEADER_SUBST "Subst" 1063 /* Obsoleted. RFC4229 */ 1064 #define MHD_HTTP_HEADER_TITLE "Title" 1065 /* Obsoleted. RFC4229 */ 1066 #define MHD_HTTP_HEADER_UA_COLOR "UA-Color" 1067 /* Obsoleted. RFC4229 */ 1068 #define MHD_HTTP_HEADER_UA_MEDIA "UA-Media" 1069 /* Obsoleted. RFC4229 */ 1070 #define MHD_HTTP_HEADER_UA_PIXELS "UA-Pixels" 1071 /* Obsoleted. RFC4229 */ 1072 #define MHD_HTTP_HEADER_UA_RESOLUTION "UA-Resolution" 1073 /* Obsoleted. RFC4229 */ 1074 #define MHD_HTTP_HEADER_UA_WINDOWPIXELS "UA-Windowpixels" 1075 /* Obsoleted. RFC4229 */ 1076 #define MHD_HTTP_HEADER_VERSION "Version" 1077 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1078 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT "X-Device-Accept" 1079 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1080 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_CHARSET "X-Device-Accept-Charset" 1081 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1082 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_ENCODING "X-Device-Accept-Encoding" 1083 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1084 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_LANGUAGE "X-Device-Accept-Language" 1085 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1086 #define MHD_HTTP_HEADER_X_DEVICE_USER_AGENT "X-Device-User-Agent" 1087 1088 /** @} */ /* end of group headers */ 1089 1090 /** 1091 * @defgroup versions HTTP versions 1092 * These strings should be used to match against the first line of the 1093 * HTTP header. 1094 * @{ 1095 */ 1096 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0" 1097 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1" 1098 1099 /** @} */ /* end of group versions */ 1100 1101 /** 1102 * @defgroup methods HTTP methods 1103 * HTTP methods (as strings). 1104 * See: https://www.iana.org/assignments/http-methods/http-methods.xml 1105 * Registry export date: 2023-10-02 1106 * @{ 1107 */ 1108 1109 /* Main HTTP methods. */ 1110 /* Safe. Idempotent. RFC9110, Section 9.3.1. */ 1111 #define MHD_HTTP_METHOD_GET "GET" 1112 /* Safe. Idempotent. RFC9110, Section 9.3.2. */ 1113 #define MHD_HTTP_METHOD_HEAD "HEAD" 1114 /* Not safe. Not idempotent. RFC9110, Section 9.3.3. */ 1115 #define MHD_HTTP_METHOD_POST "POST" 1116 /* Not safe. Idempotent. RFC9110, Section 9.3.4. */ 1117 #define MHD_HTTP_METHOD_PUT "PUT" 1118 /* Not safe. Idempotent. RFC9110, Section 9.3.5. */ 1119 #define MHD_HTTP_METHOD_DELETE "DELETE" 1120 /* Not safe. Not idempotent. RFC9110, Section 9.3.6. */ 1121 #define MHD_HTTP_METHOD_CONNECT "CONNECT" 1122 /* Safe. Idempotent. RFC9110, Section 9.3.7. */ 1123 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS" 1124 /* Safe. Idempotent. RFC9110, Section 9.3.8. */ 1125 #define MHD_HTTP_METHOD_TRACE "TRACE" 1126 1127 /* Additional HTTP methods. */ 1128 /* Not safe. Idempotent. RFC3744, Section 8.1. */ 1129 #define MHD_HTTP_METHOD_ACL "ACL" 1130 /* Not safe. Idempotent. RFC3253, Section 12.6. */ 1131 #define MHD_HTTP_METHOD_BASELINE_CONTROL "BASELINE-CONTROL" 1132 /* Not safe. Idempotent. RFC5842, Section 4. */ 1133 #define MHD_HTTP_METHOD_BIND "BIND" 1134 /* Not safe. Idempotent. RFC3253, Section 4.4, Section 9.4. */ 1135 #define MHD_HTTP_METHOD_CHECKIN "CHECKIN" 1136 /* Not safe. Idempotent. RFC3253, Section 4.3, Section 8.8. */ 1137 #define MHD_HTTP_METHOD_CHECKOUT "CHECKOUT" 1138 /* Not safe. Idempotent. RFC4918, Section 9.8. */ 1139 #define MHD_HTTP_METHOD_COPY "COPY" 1140 /* Not safe. Idempotent. RFC3253, Section 8.2. */ 1141 #define MHD_HTTP_METHOD_LABEL "LABEL" 1142 /* Not safe. Idempotent. RFC2068, Section 19.6.1.2. */ 1143 #define MHD_HTTP_METHOD_LINK "LINK" 1144 /* Not safe. Not idempotent. RFC4918, Section 9.10. */ 1145 #define MHD_HTTP_METHOD_LOCK "LOCK" 1146 /* Not safe. Idempotent. RFC3253, Section 11.2. */ 1147 #define MHD_HTTP_METHOD_MERGE "MERGE" 1148 /* Not safe. Idempotent. RFC3253, Section 13.5. */ 1149 #define MHD_HTTP_METHOD_MKACTIVITY "MKACTIVITY" 1150 /* Not safe. Idempotent. RFC4791, Section 5.3.1; RFC8144, Section 2.3. */ 1151 #define MHD_HTTP_METHOD_MKCALENDAR "MKCALENDAR" 1152 /* Not safe. Idempotent. RFC4918, Section 9.3; RFC5689, Section 3; RFC8144, Section 2.3. */ 1153 #define MHD_HTTP_METHOD_MKCOL "MKCOL" 1154 /* Not safe. Idempotent. RFC4437, Section 6. */ 1155 #define MHD_HTTP_METHOD_MKREDIRECTREF "MKREDIRECTREF" 1156 /* Not safe. Idempotent. RFC3253, Section 6.3. */ 1157 #define MHD_HTTP_METHOD_MKWORKSPACE "MKWORKSPACE" 1158 /* Not safe. Idempotent. RFC4918, Section 9.9. */ 1159 #define MHD_HTTP_METHOD_MOVE "MOVE" 1160 /* Not safe. Idempotent. RFC3648, Section 7. */ 1161 #define MHD_HTTP_METHOD_ORDERPATCH "ORDERPATCH" 1162 /* Not safe. Not idempotent. RFC5789, Section 2. */ 1163 #define MHD_HTTP_METHOD_PATCH "PATCH" 1164 /* Safe. Idempotent. RFC9113, Section 3.4. */ 1165 #define MHD_HTTP_METHOD_PRI "PRI" 1166 /* Safe. Idempotent. RFC4918, Section 9.1; RFC8144, Section 2.1. */ 1167 #define MHD_HTTP_METHOD_PROPFIND "PROPFIND" 1168 /* Not safe. Idempotent. RFC4918, Section 9.2; RFC8144, Section 2.2. */ 1169 #define MHD_HTTP_METHOD_PROPPATCH "PROPPATCH" 1170 /* Not safe. Idempotent. RFC5842, Section 6. */ 1171 #define MHD_HTTP_METHOD_REBIND "REBIND" 1172 /* Safe. Idempotent. RFC3253, Section 3.6; RFC8144, Section 2.1. */ 1173 #define MHD_HTTP_METHOD_REPORT "REPORT" 1174 /* Safe. Idempotent. RFC5323, Section 2. */ 1175 #define MHD_HTTP_METHOD_SEARCH "SEARCH" 1176 /* Not safe. Idempotent. RFC5842, Section 5. */ 1177 #define MHD_HTTP_METHOD_UNBIND "UNBIND" 1178 /* Not safe. Idempotent. RFC3253, Section 4.5. */ 1179 #define MHD_HTTP_METHOD_UNCHECKOUT "UNCHECKOUT" 1180 /* Not safe. Idempotent. RFC2068, Section 19.6.1.3. */ 1181 #define MHD_HTTP_METHOD_UNLINK "UNLINK" 1182 /* Not safe. Idempotent. RFC4918, Section 9.11. */ 1183 #define MHD_HTTP_METHOD_UNLOCK "UNLOCK" 1184 /* Not safe. Idempotent. RFC3253, Section 7.1. */ 1185 #define MHD_HTTP_METHOD_UPDATE "UPDATE" 1186 /* Not safe. Idempotent. RFC4437, Section 7. */ 1187 #define MHD_HTTP_METHOD_UPDATEREDIRECTREF "UPDATEREDIRECTREF" 1188 /* Not safe. Idempotent. RFC3253, Section 3.5. */ 1189 #define MHD_HTTP_METHOD_VERSION_CONTROL "VERSION-CONTROL" 1190 /* Not safe. Not idempotent. RFC9110, Section 18.2. */ 1191 #define MHD_HTTP_METHOD_ASTERISK "*" 1192 1193 /** @} */ /* end of group methods */ 1194 1195 /** 1196 * @defgroup postenc HTTP POST encodings 1197 * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 1198 * @{ 1199 */ 1200 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED \ 1201 "application/x-www-form-urlencoded" 1202 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" 1203 1204 /** @} */ /* end of group postenc */ 1205 1206 1207 /** 1208 * @brief Handle for the daemon (listening on a socket for HTTP traffic). 1209 * @ingroup event 1210 */ 1211 struct MHD_Daemon; 1212 1213 /** 1214 * @brief Handle for a connection / HTTP request. 1215 * 1216 * With HTTP/1.1, multiple requests can be run over the same 1217 * connection. However, MHD will only show one request per TCP 1218 * connection to the client at any given time. 1219 * @ingroup request 1220 */ 1221 struct MHD_Connection; 1222 1223 /** 1224 * @brief Handle for a response. 1225 * @ingroup response 1226 */ 1227 struct MHD_Response; 1228 1229 /** 1230 * @brief Handle for POST processing. 1231 * @ingroup response 1232 */ 1233 struct MHD_PostProcessor; 1234 1235 1236 /** 1237 * @brief Flags for the `struct MHD_Daemon`. 1238 * 1239 * Note that MHD will run automatically in background thread(s) only 1240 * if #MHD_USE_INTERNAL_POLLING_THREAD is used. Otherwise caller (application) 1241 * must use #MHD_run() or #MHD_run_from_select() to have MHD processed 1242 * network connections and data. 1243 * 1244 * Starting the daemon may also fail if a particular option is not 1245 * implemented or not supported on the target platform (i.e. no 1246 * support for TLS, epoll or IPv6). 1247 */ 1248 enum MHD_FLAG 1249 { 1250 /** 1251 * No options selected. 1252 */ 1253 MHD_NO_FLAG = 0, 1254 1255 /** 1256 * Print errors messages to custom error logger or to `stderr` if 1257 * custom error logger is not set. 1258 * @sa ::MHD_OPTION_EXTERNAL_LOGGER 1259 */ 1260 MHD_USE_ERROR_LOG = 1, 1261 1262 /** 1263 * Run in debug mode. If this flag is used, the library should 1264 * print error messages and warnings to `stderr`. 1265 */ 1266 MHD_USE_DEBUG = 1, 1267 1268 /** 1269 * Run in HTTPS mode. The modern protocol is called TLS. 1270 */ 1271 MHD_USE_TLS = 2, 1272 1273 /** @deprecated */ 1274 MHD_USE_SSL = 2, 1275 #if 0 1276 /* let's do this later once versions that define MHD_USE_TLS a more widely deployed. */ 1277 #define MHD_USE_SSL \ 1278 _MHD_DEPR_IN_MACRO ("Value MHD_USE_SSL is deprecated, use MHD_USE_TLS") \ 1279 MHD_USE_TLS 1280 #endif 1281 1282 /** 1283 * Run using one thread per connection. 1284 * Must be used only with #MHD_USE_INTERNAL_POLLING_THREAD. 1285 * 1286 * If #MHD_USE_ITC is also not used, closed and expired connections may only 1287 * be cleaned up internally when a new connection is received. 1288 * Consider adding of #MHD_USE_ITC flag to have faster internal cleanups 1289 * at very minor increase in system resources usage. 1290 */ 1291 MHD_USE_THREAD_PER_CONNECTION = 4, 1292 1293 /** 1294 * Run using an internal thread (or thread pool) for sockets sending 1295 * and receiving and data processing. Without this flag MHD will not 1296 * run automatically in background thread(s). 1297 * If this flag is set, #MHD_run() and #MHD_run_from_select() couldn't 1298 * be used. 1299 * This flag is set explicitly by #MHD_USE_POLL_INTERNAL_THREAD and 1300 * by #MHD_USE_EPOLL_INTERNAL_THREAD. 1301 * When this flag is not set, MHD run in "external" polling mode. 1302 */ 1303 MHD_USE_INTERNAL_POLLING_THREAD = 8, 1304 1305 /** @deprecated */ 1306 MHD_USE_SELECT_INTERNALLY = 8, 1307 #if 0 /* Will be marked for real deprecation later. */ 1308 #define MHD_USE_SELECT_INTERNALLY \ 1309 _MHD_DEPR_IN_MACRO ( \ 1310 "Value MHD_USE_SELECT_INTERNALLY is deprecated, use MHD_USE_INTERNAL_POLLING_THREAD instead") \ 1311 MHD_USE_INTERNAL_POLLING_THREAD 1312 #endif /* 0 */ 1313 1314 /** 1315 * Run using the IPv6 protocol (otherwise, MHD will just support 1316 * IPv4). If you want MHD to support IPv4 and IPv6 using a single 1317 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass 1318 * this option, MHD will try to bind to IPv6-only (resulting in 1319 * no IPv4 support). 1320 */ 1321 MHD_USE_IPv6 = 16, 1322 1323 /** 1324 * Be pedantic about the protocol (as opposed to as tolerant as 1325 * possible). 1326 * This flag is equivalent to setting 1 as #MHD_OPTION_CLIENT_DISCIPLINE_LVL 1327 * value. 1328 * @sa #MHD_OPTION_CLIENT_DISCIPLINE_LVL 1329 */ 1330 MHD_USE_PEDANTIC_CHECKS = 32, 1331 #if 0 /* Will be marked for real deprecation later. */ 1332 #define MHD_USE_PEDANTIC_CHECKS \ 1333 _MHD_DEPR_IN_MACRO ( \ 1334 "Flag MHD_USE_PEDANTIC_CHECKS is deprecated, " \ 1335 "use option MHD_OPTION_CLIENT_DISCIPLINE_LVL instead") \ 1336 32 1337 #endif /* 0 */ 1338 1339 /** 1340 * Use `poll()` instead of `select()` for polling sockets. 1341 * This allows sockets with `fd >= FD_SETSIZE`. 1342 * This option is not compatible with an "external" polling mode 1343 * (as there is no API to get the file descriptors for the external 1344 * poll() from MHD) and must also not be used in combination 1345 * with #MHD_USE_EPOLL. 1346 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL_INTERNAL_THREAD 1347 */ 1348 MHD_USE_POLL = 64, 1349 1350 /** 1351 * Run using an internal thread (or thread pool) doing `poll()`. 1352 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL, #MHD_USE_INTERNAL_POLLING_THREAD 1353 */ 1354 MHD_USE_POLL_INTERNAL_THREAD = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1355 1356 /** @deprecated */ 1357 MHD_USE_POLL_INTERNALLY = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1358 #if 0 /* Will be marked for real deprecation later. */ 1359 #define MHD_USE_POLL_INTERNALLY \ 1360 _MHD_DEPR_IN_MACRO ( \ 1361 "Value MHD_USE_POLL_INTERNALLY is deprecated, use MHD_USE_POLL_INTERNAL_THREAD instead") \ 1362 MHD_USE_POLL_INTERNAL_THREAD 1363 #endif /* 0 */ 1364 1365 /** 1366 * Suppress (automatically) adding the 'Date:' header to HTTP responses. 1367 * This option should ONLY be used on systems that do not have a clock 1368 * and that DO provide other mechanisms for cache control. See also 1369 * RFC 2616, section 14.18 (exception 3). 1370 */ 1371 MHD_USE_SUPPRESS_DATE_NO_CLOCK = 128, 1372 1373 /** @deprecated */ 1374 MHD_SUPPRESS_DATE_NO_CLOCK = 128, 1375 #if 0 /* Will be marked for real deprecation later. */ 1376 #define MHD_SUPPRESS_DATE_NO_CLOCK \ 1377 _MHD_DEPR_IN_MACRO ( \ 1378 "Value MHD_SUPPRESS_DATE_NO_CLOCK is deprecated, use MHD_USE_SUPPRESS_DATE_NO_CLOCK instead") \ 1379 MHD_USE_SUPPRESS_DATE_NO_CLOCK 1380 #endif /* 0 */ 1381 1382 /** 1383 * Run without a listen socket. This option only makes sense if 1384 * #MHD_add_connection is to be used exclusively to connect HTTP 1385 * clients to the HTTP server. This option is incompatible with 1386 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE 1387 * is ignored. 1388 */ 1389 MHD_USE_NO_LISTEN_SOCKET = 256, 1390 1391 /** 1392 * Use `epoll()` instead of `select()` or `poll()` for the event loop. 1393 * This option is only available on some systems; using the option on 1394 * systems without epoll will cause #MHD_start_daemon to fail. Using 1395 * this option is not supported with #MHD_USE_THREAD_PER_CONNECTION. 1396 * @sa ::MHD_FEATURE_EPOLL 1397 */ 1398 MHD_USE_EPOLL = 512, 1399 1400 /** @deprecated */ 1401 MHD_USE_EPOLL_LINUX_ONLY = 512, 1402 #if 0 /* Will be marked for real deprecation later. */ 1403 #define MHD_USE_EPOLL_LINUX_ONLY \ 1404 _MHD_DEPR_IN_MACRO ( \ 1405 "Value MHD_USE_EPOLL_LINUX_ONLY is deprecated, use MHD_USE_EPOLL") \ 1406 MHD_USE_EPOLL 1407 #endif /* 0 */ 1408 1409 /** 1410 * Run using an internal thread (or thread pool) doing `epoll` polling. 1411 * This option is only available on certain platforms; using the option on 1412 * platform without `epoll` support will cause #MHD_start_daemon to fail. 1413 * @sa ::MHD_FEATURE_EPOLL, #MHD_USE_EPOLL, #MHD_USE_INTERNAL_POLLING_THREAD 1414 */ 1415 MHD_USE_EPOLL_INTERNAL_THREAD = MHD_USE_EPOLL 1416 | MHD_USE_INTERNAL_POLLING_THREAD, 1417 1418 /** @deprecated */ 1419 MHD_USE_EPOLL_INTERNALLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, 1420 /** @deprecated */ 1421 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_EPOLL 1422 | MHD_USE_INTERNAL_POLLING_THREAD, 1423 #if 0 /* Will be marked for real deprecation later. */ 1424 #define MHD_USE_EPOLL_INTERNALLY \ 1425 _MHD_DEPR_IN_MACRO ( \ 1426 "Value MHD_USE_EPOLL_INTERNALLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1427 MHD_USE_EPOLL_INTERNAL_THREAD 1428 /** @deprecated */ 1429 #define MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY \ 1430 _MHD_DEPR_IN_MACRO ( \ 1431 "Value MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1432 MHD_USE_EPOLL_INTERNAL_THREAD 1433 #endif /* 0 */ 1434 1435 /** 1436 * Use inter-thread communication channel. 1437 * #MHD_USE_ITC can be used with #MHD_USE_INTERNAL_POLLING_THREAD 1438 * and is ignored with any "external" sockets polling. 1439 * It's required for use of #MHD_quiesce_daemon 1440 * or #MHD_add_connection. 1441 * This option is enforced by #MHD_ALLOW_SUSPEND_RESUME or 1442 * #MHD_USE_NO_LISTEN_SOCKET. 1443 * #MHD_USE_ITC is always used automatically on platforms 1444 * where select()/poll()/other ignore shutdown of listen 1445 * socket. 1446 */ 1447 MHD_USE_ITC = 1024, 1448 1449 /** @deprecated */ 1450 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 1451 #if 0 /* Will be marked for real deprecation later. */ 1452 #define MHD_USE_PIPE_FOR_SHUTDOWN \ 1453 _MHD_DEPR_IN_MACRO ( \ 1454 "Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ 1455 MHD_USE_ITC 1456 #endif /* 0 */ 1457 1458 /** 1459 * Use a single socket for IPv4 and IPv6. 1460 */ 1461 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 1462 1463 /** 1464 * Enable `turbo`. Disables certain calls to `shutdown()`, 1465 * enables aggressive non-blocking optimistic reads and 1466 * other potentially unsafe optimizations. 1467 * Most effects only happen with #MHD_USE_EPOLL. 1468 */ 1469 MHD_USE_TURBO = 4096, 1470 1471 /** @deprecated */ 1472 MHD_USE_EPOLL_TURBO = 4096, 1473 #if 0 /* Will be marked for real deprecation later. */ 1474 #define MHD_USE_EPOLL_TURBO \ 1475 _MHD_DEPR_IN_MACRO ( \ 1476 "Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ 1477 MHD_USE_TURBO 1478 #endif /* 0 */ 1479 1480 /** 1481 * Enable suspend/resume functions, which also implies setting up 1482 * ITC to signal resume. 1483 */ 1484 MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1485 1486 /** @deprecated */ 1487 MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1488 #if 0 /* Will be marked for real deprecation later. */ 1489 #define MHD_USE_SUSPEND_RESUME \ 1490 _MHD_DEPR_IN_MACRO ( \ 1491 "Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ 1492 MHD_ALLOW_SUSPEND_RESUME 1493 #endif /* 0 */ 1494 1495 /** 1496 * Enable TCP_FASTOPEN option. This option is only available on Linux with a 1497 * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon 1498 * to fail. 1499 */ 1500 MHD_USE_TCP_FASTOPEN = 16384, 1501 1502 /** 1503 * You need to set this option if you want to use HTTP "Upgrade". 1504 * "Upgrade" may require usage of additional internal resources, 1505 * which we do not want to use unless necessary. 1506 */ 1507 MHD_ALLOW_UPGRADE = 32768, 1508 1509 /** 1510 * Automatically use best available polling function. 1511 * Choice of polling function is also depend on other daemon options. 1512 * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or 1513 * select() will be used (listed in decreasing preference order, first 1514 * function available on system will be used). 1515 * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() 1516 * will be used. 1517 * If those flags are not specified then epoll or select() will be 1518 * used (as the only suitable for MHD_get_fdset()) 1519 */ 1520 MHD_USE_AUTO = 65536, 1521 1522 /** 1523 * Run using an internal thread (or thread pool) with best available on 1524 * system polling function. 1525 * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD 1526 * flags. 1527 */ 1528 MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD, 1529 1530 /** 1531 * Flag set to enable post-handshake client authentication 1532 * (only useful in combination with #MHD_USE_TLS). 1533 */ 1534 MHD_USE_POST_HANDSHAKE_AUTH_SUPPORT = 1U << 17, 1535 1536 /** 1537 * Flag set to enable TLS 1.3 early data. This has 1538 * security implications, be VERY careful when using this. 1539 */ 1540 MHD_USE_INSECURE_TLS_EARLY_DATA = 1U << 18, 1541 1542 /** 1543 * Indicates that MHD daemon will be used by application in single-threaded 1544 * mode only. When this flag is set then application must call any MHD 1545 * function only within a single thread. 1546 * This flag turns off some internal thread-safety and allows MHD making 1547 * some of the internal optimisations suitable only for single-threaded 1548 * environment. 1549 * Not compatible with #MHD_USE_INTERNAL_POLLING_THREAD. 1550 * @note Available since #MHD_VERSION 0x00097707 1551 */ 1552 MHD_USE_NO_THREAD_SAFETY = 1U << 19 1553 1554 }; 1555 1556 1557 /** 1558 * Type of a callback function used for logging by MHD. 1559 * 1560 * @param cls closure 1561 * @param fm format string (`printf()`-style) 1562 * @param ap arguments to @a fm 1563 * @ingroup logging 1564 */ 1565 typedef void 1566 (*MHD_LogCallback)(void *cls, 1567 const char *fm, 1568 va_list ap); 1569 1570 1571 /** 1572 * Function called to lookup the pre shared key (@a psk) for a given 1573 * HTTP connection based on the @a username. 1574 * 1575 * @param cls closure 1576 * @param connection the HTTPS connection 1577 * @param username the user name claimed by the other side 1578 * @param[out] psk to be set to the pre-shared-key; should be allocated with malloc(), 1579 * will be freed by MHD 1580 * @param[out] psk_size to be set to the number of bytes in @a psk 1581 * @return 0 on success, -1 on errors 1582 */ 1583 typedef int 1584 (*MHD_PskServerCredentialsCallback)(void *cls, 1585 const struct MHD_Connection *connection, 1586 const char *username, 1587 void **psk, 1588 size_t *psk_size); 1589 1590 /** 1591 * Values for #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE. 1592 * 1593 * These values can limit the scope of validity of MHD-generated nonces. 1594 * Values can be combined with bitwise OR. 1595 * Any value, except #MHD_DAUTH_BIND_NONCE_NONE, enforce function 1596 * #MHD_digest_auth_check3() (and similar functions) to check nonce by 1597 * re-generating it again with the same parameters, which is CPU-intensive 1598 * operation. 1599 * @note Available since #MHD_VERSION 0x00097701 1600 */ 1601 enum MHD_DAuthBindNonce 1602 { 1603 /** 1604 * Generated nonces are valid for any request from any client until expired. 1605 * This is default and recommended value. 1606 * #MHD_digest_auth_check3() (and similar functions) would check only whether 1607 * the nonce value that is used by client has been generated by MHD and not 1608 * expired yet. 1609 * It is recommended because RFC 7616 allows clients to use the same nonce 1610 * for any request in the same "protection space". 1611 * When checking client's authorisation requests CPU is loaded less if this 1612 * value is used. 1613 * This mode gives MHD maximum flexibility for nonces generation and can 1614 * prevent possible nonce collisions (and corresponding log warning messages) 1615 * when clients' requests are intensive. 1616 * This value cannot be biwise-OR combined with other values. 1617 */ 1618 MHD_DAUTH_BIND_NONCE_NONE = 0, 1619 1620 /** 1621 * Generated nonces are valid only for the same realm. 1622 */ 1623 MHD_DAUTH_BIND_NONCE_REALM = 1 << 0, 1624 1625 /** 1626 * Generated nonces are valid only for the same URI (excluding parameters 1627 * after '?' in URI) and request method (GET, POST etc). 1628 * Not recommended unless "protection space" is limited to a single URI as 1629 * RFC 7616 allows clients to re-use server-generated nonces for any URI 1630 * in the same "protection space" which by default consists of all server 1631 * URIs. 1632 * Before #MHD_VERSION 0x00097701 this was default (and only supported) 1633 * nonce bind type. 1634 */ 1635 MHD_DAUTH_BIND_NONCE_URI = 1 << 1, 1636 1637 /** 1638 * Generated nonces are valid only for the same URI including URI parameters 1639 * and request method (GET, POST etc). 1640 * This value implies #MHD_DAUTH_BIND_NONCE_URI. 1641 * Not recommended for that same reasons as #MHD_DAUTH_BIND_NONCE_URI. 1642 */ 1643 MHD_DAUTH_BIND_NONCE_URI_PARAMS = 1 << 2, 1644 1645 /** 1646 * Generated nonces are valid only for the single client's IP. 1647 * While it looks like security improvement, in practice the same client may 1648 * jump from one IP to another (mobile or Wi-Fi handover, DHCP re-assignment, 1649 * Multi-NAT, different proxy chain and other reasons), while IP address 1650 * spoofing could be used relatively easily. 1651 */ 1652 MHD_DAUTH_BIND_NONCE_CLIENT_IP = 1 << 3 1653 } _MHD_FLAGS_ENUM; 1654 1655 /** 1656 * @brief MHD options. 1657 * 1658 * Passed in the varargs portion of #MHD_start_daemon. 1659 */ 1660 enum MHD_OPTION 1661 { 1662 1663 /** 1664 * No more options / last option. This is used 1665 * to terminate the VARARGs list. 1666 */ 1667 MHD_OPTION_END = 0, 1668 1669 /** 1670 * Maximum memory size per connection (followed by a `size_t`). 1671 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 1672 * Values above 128k are unlikely to result in much benefit, as half 1673 * of the memory will be typically used for IO, and TCP buffers are 1674 * unlikely to support window sizes above 64k on most systems. 1675 * Values below 64 bytes are completely unusable. 1676 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1677 */ 1678 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 1679 1680 /** 1681 * Maximum number of concurrent connections to 1682 * accept (followed by an `unsigned int`). 1683 */ 1684 MHD_OPTION_CONNECTION_LIMIT = 2, 1685 1686 /** 1687 * After how many seconds of inactivity should a 1688 * connection automatically be timed out? (followed 1689 * by an `unsigned int`; use zero for no timeout). 1690 * Values larger than (UINT64_MAX / 2000 - 1) will 1691 * be clipped to this number. 1692 */ 1693 MHD_OPTION_CONNECTION_TIMEOUT = 3, 1694 1695 /** 1696 * Register a function that should be called whenever a request has 1697 * been completed (this can be used for application-specific clean 1698 * up). Requests that have never been presented to the application 1699 * (via #MHD_AccessHandlerCallback) will not result in 1700 * notifications. 1701 * 1702 * This option should be followed by TWO pointers. First a pointer 1703 * to a function of type #MHD_RequestCompletedCallback and second a 1704 * pointer to a closure to pass to the request completed callback. 1705 * The second pointer may be NULL. 1706 */ 1707 MHD_OPTION_NOTIFY_COMPLETED = 4, 1708 1709 /** 1710 * Limit on the number of (concurrent) connections made to the 1711 * server from the same IP address. Can be used to prevent one 1712 * IP from taking over all of the allowed connections. If the 1713 * same IP tries to establish more than the specified number of 1714 * connections, they will be immediately rejected. The option 1715 * should be followed by an `unsigned int`. The default is 1716 * zero, which means no limit on the number of connections 1717 * from the same IP address. 1718 */ 1719 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 1720 1721 /** 1722 * Bind daemon to the supplied `struct sockaddr`. This option should 1723 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is 1724 * specified, the `struct sockaddr*` should point to a `struct 1725 * sockaddr_in6`, otherwise to a `struct sockaddr_in`. 1726 * Silently ignored if followed by NULL pointer. 1727 * @deprecated Use #MHD_OPTION_SOCK_ADDR_LEN 1728 */ 1729 MHD_OPTION_SOCK_ADDR = 6, 1730 1731 /** 1732 * Specify a function that should be called before parsing the URI from 1733 * the client. The specified callback function can be used for processing 1734 * the URI (including the options) before it is parsed. The URI after 1735 * parsing will no longer contain the options, which maybe inconvenient for 1736 * logging. This option should be followed by two arguments, the first 1737 * one must be of the form 1738 * 1739 * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) 1740 * 1741 * where the return value will be passed as 1742 * (`* req_cls`) in calls to the #MHD_AccessHandlerCallback 1743 * when this request is processed later; returning a 1744 * value of NULL has no special significance (however, 1745 * note that if you return non-NULL, you can no longer 1746 * rely on the first call to the access handler having 1747 * `NULL == *req_cls` on entry;) 1748 * "cls" will be set to the second argument following 1749 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 1750 * be the 0-terminated URI of the request. 1751 * 1752 * Note that during the time of this call, most of the connection's 1753 * state is not initialized (as we have not yet parsed the headers). 1754 * However, information about the connecting client (IP, socket) 1755 * is available. 1756 * 1757 * The specified function is called only once per request, therefore some 1758 * programmers may use it to instantiate their own request objects, freeing 1759 * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. 1760 */ 1761 MHD_OPTION_URI_LOG_CALLBACK = 7, 1762 1763 /** 1764 * Memory pointer for the private key (key.pem) to be used by the 1765 * HTTPS daemon. This option should be followed by a 1766 * `const char *` argument. 1767 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 1768 */ 1769 MHD_OPTION_HTTPS_MEM_KEY = 8, 1770 1771 /** 1772 * Memory pointer for the certificate (cert.pem) to be used by the 1773 * HTTPS daemon. This option should be followed by a 1774 * `const char *` argument. 1775 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1776 */ 1777 MHD_OPTION_HTTPS_MEM_CERT = 9, 1778 1779 /** 1780 * Daemon credentials type. 1781 * Followed by an argument of type 1782 * `gnutls_credentials_type_t`. 1783 */ 1784 MHD_OPTION_HTTPS_CRED_TYPE = 10, 1785 1786 /** 1787 * Memory pointer to a `const char *` specifying the GnuTLS priorities string. 1788 * If this options is not specified, then MHD will try the following strings: 1789 * * "@LIBMICROHTTPD" (application-specific system-wide configuration) 1790 * * "@SYSTEM" (system-wide configuration) 1791 * * default GnuTLS priorities string 1792 * * "NORMAL" 1793 * The first configuration accepted by GnuTLS will be used. 1794 * For more details see GnuTLS documentation for "Application-specific 1795 * priority strings". 1796 */ 1797 MHD_OPTION_HTTPS_PRIORITIES = 11, 1798 1799 /** 1800 * Pass a listen socket for MHD to use (systemd-style). If this 1801 * option is used, MHD will not open its own listen socket(s). The 1802 * argument passed must be of type `MHD_socket` and refer to an 1803 * existing socket that has been bound to a port and is listening. 1804 * If followed by MHD_INVALID_SOCKET value, MHD ignores this option 1805 * and creates socket by itself. 1806 */ 1807 MHD_OPTION_LISTEN_SOCKET = 12, 1808 1809 /** 1810 * Use the given function for logging error messages. This option 1811 * must be followed by two arguments; the first must be a pointer to 1812 * a function of type #MHD_LogCallback and the second a pointer 1813 * `void *` which will be passed as the first argument to the log 1814 * callback. 1815 * Should be specified as the first option, otherwise some messages 1816 * may be printed by standard MHD logger during daemon startup. 1817 * 1818 * Note that MHD will not generate any log messages 1819 * if it was compiled without the "--enable-messages" 1820 * flag being set. 1821 */ 1822 MHD_OPTION_EXTERNAL_LOGGER = 13, 1823 1824 /** 1825 * Number (`unsigned int`) of threads in thread pool. Enable 1826 * thread pooling by setting this value to to something 1827 * greater than 1. 1828 * Can be used only for daemons started with #MHD_USE_INTERNAL_POLLING_THREAD. 1829 * Ignored if followed by zero value. 1830 */ 1831 MHD_OPTION_THREAD_POOL_SIZE = 14, 1832 1833 /** 1834 * Additional options given in an array of `struct MHD_OptionItem`. 1835 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 1836 * An example for code using #MHD_OPTION_ARRAY is: 1837 * 1838 * struct MHD_OptionItem ops[] = { 1839 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 1840 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 1841 * { MHD_OPTION_END, 0, NULL } 1842 * }; 1843 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, 1844 * MHD_OPTION_ARRAY, ops, 1845 * MHD_OPTION_END); 1846 * 1847 * For options that expect a single pointer argument, the 1848 * 'value' member of the `struct MHD_OptionItem` is ignored. 1849 * For options that expect two pointer arguments, the first 1850 * argument must be cast to `intptr_t`. 1851 */ 1852 MHD_OPTION_ARRAY = 15, 1853 1854 /** 1855 * Specify a function that should be called for unescaping escape 1856 * sequences in URIs and URI arguments. Note that this function 1857 * will NOT be used by the `struct MHD_PostProcessor`. If this 1858 * option is not specified, the default method will be used which 1859 * decodes escape sequences of the form "%HH". This option should 1860 * be followed by two arguments, the first one must be of the form 1861 * 1862 * size_t my_unescaper(void *cls, 1863 * struct MHD_Connection *c, 1864 * char *s) 1865 * 1866 * where the return value must be the length of the value left in 1867 * "s" (without the 0-terminator) and "s" should be updated. Note 1868 * that the unescape function must not lengthen "s" (the result must 1869 * be shorter than the input and must still be 0-terminated). 1870 * However, it may also include binary zeros before the 1871 * 0-termination. "cls" will be set to the second argument 1872 * following #MHD_OPTION_UNESCAPE_CALLBACK. 1873 */ 1874 MHD_OPTION_UNESCAPE_CALLBACK = 16, 1875 1876 /** 1877 * Memory pointer for the random values to be used by the Digest 1878 * Auth module. This option should be followed by two arguments. 1879 * First an integer of type `size_t` which specifies the size 1880 * of the buffer pointed to by the second argument in bytes. 1881 * The recommended size is between 8 and 32. If size is four or less 1882 * then security could be lowered. Sizes more then 32 (or, probably 1883 * more than 16 - debatable) will not increase security. 1884 * Note that the application must ensure that the buffer of the 1885 * second argument remains allocated and unmodified while the 1886 * daemon is running. 1887 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM_COPY 1888 */ 1889 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 1890 1891 /** 1892 * Size of the internal array holding the map of the nonce and 1893 * the nonce counter. This option should be followed by an `unsigend int` 1894 * argument. 1895 * The map size is 4 by default, which is enough to communicate with 1896 * a single client at any given moment of time, but not enough to 1897 * handle several clients simultaneously. 1898 * If Digest Auth is not used, this option can be set to zero to minimise 1899 * memory allocation. 1900 */ 1901 MHD_OPTION_NONCE_NC_SIZE = 18, 1902 1903 /** 1904 * Desired size of the stack for threads created by MHD. Followed 1905 * by an argument of type `size_t`. Use 0 for system default. 1906 */ 1907 MHD_OPTION_THREAD_STACK_SIZE = 19, 1908 1909 /** 1910 * Memory pointer for the certificate (ca.pem) to be used by the 1911 * HTTPS daemon for client authentication. 1912 * This option should be followed by a `const char *` argument. 1913 */ 1914 MHD_OPTION_HTTPS_MEM_TRUST = 20, 1915 1916 /** 1917 * Increment to use for growing the read buffer (followed by a 1918 * `size_t`). 1919 * Must not be higher than 1/4 of #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 1920 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1921 */ 1922 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, 1923 1924 /** 1925 * Use a callback to determine which X.509 certificate should be 1926 * used for a given HTTPS connection. This option should be 1927 * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. 1928 * This option provides an 1929 * alternative to #MHD_OPTION_HTTPS_MEM_KEY, 1930 * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if 1931 * multiple domains are to be hosted at the same IP address using 1932 * TLS's Server Name Indication (SNI) extension. In this case, 1933 * the callback is expected to select the correct certificate 1934 * based on the SNI information provided. The callback is expected 1935 * to access the SNI data using `gnutls_server_name_get()`. 1936 * Using this option requires GnuTLS 3.0 or higher. 1937 */ 1938 MHD_OPTION_HTTPS_CERT_CALLBACK = 22, 1939 1940 /** 1941 * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP 1942 * fastopen queue length of 50. Note that having a larger queue size can 1943 * cause resource exhaustion attack as the TCP stack has to now allocate 1944 * resources for the SYN packet along with its DATA. This option should be 1945 * followed by an `unsigned int` argument. 1946 */ 1947 MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, 1948 1949 /** 1950 * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the 1951 * HTTPS daemon for key exchange. 1952 * This option must be followed by a `const char *` argument. 1953 */ 1954 MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, 1955 1956 /** 1957 * If present and set to true, allow reusing address:port socket 1958 * (by using SO_REUSEPORT on most platform, or platform-specific ways). 1959 * If present and set to false, disallow reusing address:port socket 1960 * (does nothing on most platform, but uses SO_EXCLUSIVEADDRUSE on Windows). 1961 * This option must be followed by a `unsigned int` argument. 1962 */ 1963 MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, 1964 1965 /** 1966 * Memory pointer for a password that decrypts the private key (key.pem) 1967 * to be used by the HTTPS daemon. This option should be followed by a 1968 * `const char *` argument. 1969 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1970 * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD 1971 */ 1972 MHD_OPTION_HTTPS_KEY_PASSWORD = 26, 1973 1974 /** 1975 * Register a function that should be called whenever a connection is 1976 * started or closed. 1977 * 1978 * This option should be followed by TWO pointers. First a pointer 1979 * to a function of type #MHD_NotifyConnectionCallback and second a 1980 * pointer to a closure to pass to the request completed callback. 1981 * The second pointer may be NULL. 1982 */ 1983 MHD_OPTION_NOTIFY_CONNECTION = 27, 1984 1985 /** 1986 * Allow to change maximum length of the queue of pending connections on 1987 * listen socket. If not present than default platform-specific SOMAXCONN 1988 * value is used. This option should be followed by an `unsigned int` 1989 * argument. 1990 */ 1991 MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, 1992 1993 /** 1994 * If set to 1 - be strict about the protocol. Use -1 to be 1995 * as tolerant as possible. 1996 * 1997 * The more flexible option #MHD_OPTION_CLIENT_DISCIPLINE_LVL is recommended 1998 * instead of this option. 1999 * 2000 * The values mapping table: 2001 * #MHD_OPTION_STRICT_FOR_CLIENT | #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2002 * -----------------------------:|:--------------------------------- 2003 * 1 | 1 2004 * 0 | 0 2005 * -1 | -3 2006 * 2007 * This option should be followed by an `int` argument. 2008 * @sa #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2009 */ 2010 MHD_OPTION_STRICT_FOR_CLIENT = 29, 2011 2012 /** 2013 * This should be a pointer to callback of type 2014 * gnutls_psk_server_credentials_function that will be given to 2015 * gnutls_psk_set_server_credentials_function. It is used to 2016 * retrieve the shared key for a given username. 2017 */ 2018 MHD_OPTION_GNUTLS_PSK_CRED_HANDLER = 30, 2019 2020 /** 2021 * Use a callback to determine which X.509 certificate should be 2022 * used for a given HTTPS connection. This option should be 2023 * followed by a argument of type `gnutls_certificate_retrieve_function3 *`. 2024 * This option provides an 2025 * alternative/extension to #MHD_OPTION_HTTPS_CERT_CALLBACK. 2026 * You must use this version if you want to use OCSP stapling. 2027 * Using this option requires GnuTLS 3.6.3 or higher. 2028 */ 2029 MHD_OPTION_HTTPS_CERT_CALLBACK2 = 31, 2030 2031 /** 2032 * Allows the application to disable certain sanity precautions 2033 * in MHD. With these, the client can break the HTTP protocol, 2034 * so this should never be used in production. The options are, 2035 * however, useful for testing HTTP clients against "broken" 2036 * server implementations. 2037 * This argument must be followed by an "unsigned int", corresponding 2038 * to an `enum MHD_DisableSanityCheck`. 2039 */ 2040 MHD_OPTION_SERVER_INSANITY = 32, 2041 2042 /** 2043 * If followed by value '1' informs MHD that SIGPIPE is suppressed or 2044 * handled by application. Allows MHD to use network functions that could 2045 * generate SIGPIPE, like `sendfile()`. 2046 * Valid only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD as 2047 * MHD automatically suppresses SIGPIPE for threads started by MHD. 2048 * This option should be followed by an `int` argument. 2049 * @note Available since #MHD_VERSION 0x00097205 2050 */ 2051 MHD_OPTION_SIGPIPE_HANDLED_BY_APP = 33, 2052 2053 /** 2054 * If followed by 'int' with value '1' disables usage of ALPN for TLS 2055 * connections even if supported by TLS library. 2056 * Valid only for daemons with #MHD_USE_TLS. 2057 * This option should be followed by an `int` argument. 2058 * @note Available since #MHD_VERSION 0x00097207 2059 */ 2060 MHD_OPTION_TLS_NO_ALPN = 34, 2061 2062 /** 2063 * Memory pointer for the random values to be used by the Digest 2064 * Auth module. This option should be followed by two arguments. 2065 * First an integer of type `size_t` which specifies the size 2066 * of the buffer pointed to by the second argument in bytes. 2067 * The recommended size is between 8 and 32. If size is four or less 2068 * then security could be lowered. Sizes more then 32 (or, probably 2069 * more than 16 - debatable) will not increase security. 2070 * An internal copy of the buffer will be made, the data do not 2071 * need to be static. 2072 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM 2073 * @note Available since #MHD_VERSION 0x00097701 2074 */ 2075 MHD_OPTION_DIGEST_AUTH_RANDOM_COPY = 35, 2076 2077 /** 2078 * Allow to controls the scope of validity of MHD-generated nonces. 2079 * This regulates how "nonces" are generated and how "nonces" are checked by 2080 * #MHD_digest_auth_check3() and similar functions. 2081 * This option should be followed by an 'unsigned int` argument with value 2082 * formed as bitwise OR combination of #MHD_DAuthBindNonce values. 2083 * When not specified, default value #MHD_DAUTH_BIND_NONCE_NONE is used. 2084 * @note Available since #MHD_VERSION 0x00097701 2085 */ 2086 MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE = 36, 2087 2088 /** 2089 * Memory pointer to a `const char *` specifying the GnuTLS priorities to be 2090 * appended to default priorities. 2091 * This allow some specific options to be enabled/disabled, while leaving 2092 * the rest of the settings to their defaults. 2093 * The string does not have to start with a colon ':' character. 2094 * See #MHD_OPTION_HTTPS_PRIORITIES description for details of automatic 2095 * default priorities. 2096 * @note Available since #MHD_VERSION 0x00097701 2097 */ 2098 MHD_OPTION_HTTPS_PRIORITIES_APPEND = 37, 2099 2100 /** 2101 * Sets specified client discipline level (i.e. HTTP protocol parsing 2102 * strictness level). 2103 * 2104 * The following basic values are supported: 2105 * 0 - default MHD level, a balance between extra security and broader 2106 * compatibility, as allowed by RFCs for HTTP servers; 2107 * 1 - more strict protocol interpretation, within the limits set by 2108 * RFCs for HTTP servers; 2109 * -1 - more lenient protocol interpretation, within the limits set by 2110 * RFCs for HTTP servers. 2111 * The following extended values could be used as well: 2112 * 2 - stricter protocol interpretation, even stricter then allowed 2113 * by RFCs for HTTP servers, however it should be absolutely compatible 2114 * with clients following at least RFCs' "MUST" type of requirements 2115 * for HTTP clients; 2116 * 3 - strictest protocol interpretation, even stricter then allowed 2117 * by RFCs for HTTP servers, however it should be absolutely compatible 2118 * with clients following RFCs' "SHOULD" and "MUST" types of requirements 2119 * for HTTP clients; 2120 * -2 - more relaxed protocol interpretation, violating RFCs' "SHOULD" type 2121 * of requirements for HTTP servers; 2122 * -3 - the most flexible protocol interpretation, beyond RFCs' "MUST" type of 2123 * requirements for HTTP server. 2124 * Values higher than "3" or lower than "-3" are interpreted as "3" or "-3" 2125 * respectively. 2126 * 2127 * Higher values are more secure, lower values are more compatible with 2128 * various HTTP clients. 2129 * 2130 * The default value ("0") could be used in most cases. 2131 * Value "1" is suitable for highly loaded public servers. 2132 * Values "2" and "3" are generally recommended only for testing of HTTP 2133 * clients against MHD. 2134 * Value "2" may be used for security-centric application, however it is 2135 * slight violation of RFCs' requirements. 2136 * Negative values are not recommended for public servers. 2137 * Values "-1" and "-2" could be used for servers in isolated environment. 2138 * Value "-3" is not recommended unless it is absolutely necessary to 2139 * communicate with some client(s) with badly broken HTTP implementation. 2140 * 2141 * This option should be followed by an `int` argument. 2142 * @note Available since #MHD_VERSION 0x00097701 2143 */ 2144 MHD_OPTION_CLIENT_DISCIPLINE_LVL = 38, 2145 2146 /** 2147 * Specifies value of FD_SETSIZE used by application. Only For external 2148 * polling modes (without MHD internal threads). 2149 * Some platforms (FreeBSD, Solaris, W32 etc.) allow overriding of FD_SETSIZE 2150 * value. When polling by select() is used, MHD rejects sockets with numbers 2151 * equal or higher than FD_SETSIZE. If this option is used, MHD treats this 2152 * value as a limitation for socket number instead of FD_SETSIZE value which 2153 * was used for building MHD. 2154 * When external polling is used with #MHD_get_fdset2() (or #MHD_get_fdset() 2155 * macro) and #MHD_run_from_select() interfaces, it is recommended to always 2156 * use this option. 2157 * It is safe to use this option on platforms with fixed FD_SETSIZE (like 2158 * GNU/Linux) if system value of FD_SETSIZE is used as the argument. 2159 * Can be used only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD, i.e. 2160 * only when external sockets polling is used. 2161 * On W32 it is silently ignored, as W32 does not limit the socket number in 2162 * fd_sets. 2163 * This option should be followed by a positive 'int' argument. 2164 * @note Available since #MHD_VERSION 0x00097705 2165 */ 2166 MHD_OPTION_APP_FD_SETSIZE = 39, 2167 2168 /** 2169 * Bind daemon to the supplied 'struct sockaddr'. This option should 2170 * be followed by two parameters: 'socklen_t' the size of memory at the next 2171 * pointer and the pointer 'const struct sockaddr *'. 2172 * Note: the order of the arguments is not the same as for system bind() and 2173 * other network functions. 2174 * If #MHD_USE_IPv6 is specified, the 'struct sockaddr*' should 2175 * point to a 'struct sockaddr_in6'. 2176 * The socket domain (protocol family) is detected from provided 2177 * 'struct sockaddr'. IP, IPv6 and UNIX sockets are supported (if supported 2178 * by the platform). Other types may work occasionally. 2179 * Silently ignored if followed by zero size and NULL pointer. 2180 * @note Available since #MHD_VERSION 0x00097706 2181 */ 2182 MHD_OPTION_SOCK_ADDR_LEN = 40 2183 , 2184 /** 2185 * Default nonce timeout value used for Digest Auth. 2186 * This option should be followed by an 'unsigned int' argument. 2187 * Silently ignored if followed by zero value. 2188 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2189 * @note Available since #MHD_VERSION 0x00097709 2190 */ 2191 MHD_OPTION_DIGEST_AUTH_DEFAULT_NONCE_TIMEOUT = 41 2192 , 2193 /** 2194 * Default maximum nc (nonce count) value used for Digest Auth. 2195 * This option should be followed by an 'uint32_t' argument. 2196 * Silently ignored if followed by zero value. 2197 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2198 * @note Available since #MHD_VERSION 0x00097709 2199 */ 2200 MHD_OPTION_DIGEST_AUTH_DEFAULT_MAX_NC = 42 2201 2202 } _MHD_FIXED_ENUM; 2203 2204 2205 /** 2206 * Bitfield for the #MHD_OPTION_SERVER_INSANITY specifying 2207 * which santiy checks should be disabled. 2208 */ 2209 enum MHD_DisableSanityCheck 2210 { 2211 /** 2212 * All sanity checks are enabled. 2213 */ 2214 MHD_DSC_SANE = 0 2215 2216 } _MHD_FIXED_FLAGS_ENUM; 2217 2218 2219 /** 2220 * Entry in an #MHD_OPTION_ARRAY. 2221 */ 2222 struct MHD_OptionItem 2223 { 2224 /** 2225 * Which option is being given. Use #MHD_OPTION_END 2226 * to terminate the array. 2227 */ 2228 enum MHD_OPTION option; 2229 2230 /** 2231 * Option value (for integer arguments, and for options requiring 2232 * two pointer arguments); should be 0 for options that take no 2233 * arguments or only a single pointer argument. 2234 */ 2235 intptr_t value; 2236 2237 /** 2238 * Pointer option value (use NULL for options taking no arguments 2239 * or only an integer option). 2240 */ 2241 void *ptr_value; 2242 2243 }; 2244 2245 2246 /** 2247 * The `enum MHD_ValueKind` specifies the source of 2248 * the key-value pairs in the HTTP protocol. 2249 */ 2250 enum MHD_ValueKind 2251 { 2252 2253 /** 2254 * Response header 2255 * @deprecated 2256 */ 2257 MHD_RESPONSE_HEADER_KIND = 0, 2258 #define MHD_RESPONSE_HEADER_KIND \ 2259 _MHD_DEPR_IN_MACRO ( \ 2260 "Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ 2261 MHD_RESPONSE_HEADER_KIND 2262 2263 /** 2264 * HTTP header (request/response). 2265 */ 2266 MHD_HEADER_KIND = 1, 2267 2268 /** 2269 * Cookies. Note that the original HTTP header containing 2270 * the cookie(s) will still be available and intact. 2271 */ 2272 MHD_COOKIE_KIND = 2, 2273 2274 /** 2275 * POST data. This is available only if a content encoding 2276 * supported by MHD is used (currently only URL encoding), 2277 * and only if the posted content fits within the available 2278 * memory pool. Note that in that case, the upload data 2279 * given to the #MHD_AccessHandlerCallback will be 2280 * empty (since it has already been processed). 2281 */ 2282 MHD_POSTDATA_KIND = 4, 2283 2284 /** 2285 * GET (URI) arguments. 2286 */ 2287 MHD_GET_ARGUMENT_KIND = 8, 2288 2289 /** 2290 * HTTP footer (only for HTTP 1.1 chunked encodings). 2291 */ 2292 MHD_FOOTER_KIND = 16 2293 } _MHD_FIXED_ENUM; 2294 2295 2296 /** 2297 * The `enum MHD_RequestTerminationCode` specifies reasons 2298 * why a request has been terminated (or completed). 2299 * @ingroup request 2300 */ 2301 enum MHD_RequestTerminationCode 2302 { 2303 2304 /** 2305 * We finished sending the response. 2306 * @ingroup request 2307 */ 2308 MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, 2309 2310 /** 2311 * Error handling the connection (resources 2312 * exhausted, application error accepting request, 2313 * decrypt error (for HTTPS), connection died when 2314 * sending the response etc.) 2315 * @ingroup request 2316 */ 2317 MHD_REQUEST_TERMINATED_WITH_ERROR = 1, 2318 2319 /** 2320 * No activity on the connection for the number 2321 * of seconds specified using 2322 * #MHD_OPTION_CONNECTION_TIMEOUT. 2323 * @ingroup request 2324 */ 2325 MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, 2326 2327 /** 2328 * We had to close the session since MHD was being 2329 * shut down. 2330 * @ingroup request 2331 */ 2332 MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, 2333 2334 /** 2335 * We tried to read additional data, but the connection became broken or 2336 * the other side hard closed the connection. 2337 * This error is similar to #MHD_REQUEST_TERMINATED_WITH_ERROR, but 2338 * specific to the case where the connection died before request completely 2339 * received. 2340 * @ingroup request 2341 */ 2342 MHD_REQUEST_TERMINATED_READ_ERROR = 4, 2343 2344 /** 2345 * The client terminated the connection by closing the socket 2346 * for writing (TCP half-closed) while still sending request. 2347 * @ingroup request 2348 */ 2349 MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 2350 2351 } _MHD_FIXED_ENUM; 2352 2353 2354 /** 2355 * The `enum MHD_ConnectionNotificationCode` specifies types 2356 * of connection notifications. 2357 * @ingroup request 2358 */ 2359 enum MHD_ConnectionNotificationCode 2360 { 2361 2362 /** 2363 * A new connection has been started. 2364 * @ingroup request 2365 */ 2366 MHD_CONNECTION_NOTIFY_STARTED = 0, 2367 2368 /** 2369 * A connection is closed. 2370 * @ingroup request 2371 */ 2372 MHD_CONNECTION_NOTIFY_CLOSED = 1 2373 2374 } _MHD_FIXED_ENUM; 2375 2376 2377 /** 2378 * Information about a connection. 2379 */ 2380 union MHD_ConnectionInfo 2381 { 2382 2383 /** 2384 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". 2385 */ 2386 int /* enum gnutls_cipher_algorithm */ cipher_algorithm; 2387 2388 /** 2389 * Protocol used, of type "enum gnutls_protocol". 2390 */ 2391 int /* enum gnutls_protocol */ protocol; 2392 2393 /** 2394 * The suspended status of a connection. 2395 */ 2396 int /* MHD_YES or MHD_NO */ suspended; 2397 2398 /** 2399 * Amount of second that connection could spend in idle state 2400 * before automatically disconnected. 2401 * Zero for no timeout (unlimited idle time). 2402 */ 2403 unsigned int connection_timeout; 2404 2405 /** 2406 * HTTP status queued with the response, for #MHD_CONNECTION_INFO_HTTP_STATUS. 2407 */ 2408 unsigned int http_status; 2409 2410 /** 2411 * Connect socket 2412 */ 2413 MHD_socket connect_fd; 2414 2415 /** 2416 * Size of the client's HTTP header. 2417 * It includes the request line, all request headers, the header section 2418 * terminating empty line, with all CRLF (or LF) characters. 2419 */ 2420 size_t header_size; 2421 2422 /** 2423 * GNUtls session handle, of type "gnutls_session_t". 2424 */ 2425 void * /* gnutls_session_t */ tls_session; 2426 2427 /** 2428 * GNUtls client certificate handle, of type "gnutls_x509_crt_t". 2429 */ 2430 void * /* gnutls_x509_crt_t */ client_cert; 2431 2432 /** 2433 * Address information for the client. 2434 */ 2435 struct sockaddr *client_addr; 2436 2437 /** 2438 * Which daemon manages this connection (useful in case there are many 2439 * daemons running). 2440 */ 2441 struct MHD_Daemon *daemon; 2442 2443 /** 2444 * Socket-specific client context. Points to the same address as 2445 * the "socket_context" of the #MHD_NotifyConnectionCallback. 2446 */ 2447 void *socket_context; 2448 }; 2449 2450 2451 /** 2452 * I/O vector type. Provided for use with #MHD_create_response_from_iovec(). 2453 * @note Available since #MHD_VERSION 0x00097204 2454 */ 2455 struct MHD_IoVec 2456 { 2457 /** 2458 * The pointer to the memory region for I/O. 2459 */ 2460 const void *iov_base; 2461 2462 /** 2463 * The size in bytes of the memory region for I/O. 2464 */ 2465 size_t iov_len; 2466 }; 2467 2468 2469 /** 2470 * Values of this enum are used to specify what 2471 * information about a connection is desired. 2472 * @ingroup request 2473 */ 2474 enum MHD_ConnectionInfoType 2475 { 2476 /** 2477 * What cipher algorithm is being used. 2478 * Takes no extra arguments. 2479 * @ingroup request 2480 */ 2481 MHD_CONNECTION_INFO_CIPHER_ALGO, 2482 2483 /** 2484 * 2485 * Takes no extra arguments. 2486 * @ingroup request 2487 */ 2488 MHD_CONNECTION_INFO_PROTOCOL, 2489 2490 /** 2491 * Obtain IP address of the client. Takes no extra arguments. 2492 * Returns essentially a `struct sockaddr **` (since the API returns 2493 * a `union MHD_ConnectionInfo *` and that union contains a `struct 2494 * sockaddr *`). 2495 * @ingroup request 2496 */ 2497 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 2498 2499 /** 2500 * Get the gnuTLS session handle. 2501 * @ingroup request 2502 */ 2503 MHD_CONNECTION_INFO_GNUTLS_SESSION, 2504 2505 /** 2506 * Get the gnuTLS client certificate handle. Dysfunctional (never 2507 * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION 2508 * to get the `gnutls_session_t` and then call 2509 * gnutls_certificate_get_peers(). 2510 */ 2511 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, 2512 2513 /** 2514 * Get the `struct MHD_Daemon *` responsible for managing this connection. 2515 * @ingroup request 2516 */ 2517 MHD_CONNECTION_INFO_DAEMON, 2518 2519 /** 2520 * Request the file descriptor for the connection socket. 2521 * MHD sockets are always in non-blocking mode. 2522 * No extra arguments should be passed. 2523 * @ingroup request 2524 */ 2525 MHD_CONNECTION_INFO_CONNECTION_FD, 2526 2527 /** 2528 * Returns the client-specific pointer to a `void *` that was (possibly) 2529 * set during a #MHD_NotifyConnectionCallback when the socket was 2530 * first accepted. 2531 * Note that this is NOT the same as the "req_cls" argument of 2532 * the #MHD_AccessHandlerCallback. The "req_cls" is fresh for each 2533 * HTTP request, while the "socket_context" is fresh for each socket. 2534 */ 2535 MHD_CONNECTION_INFO_SOCKET_CONTEXT, 2536 2537 /** 2538 * Check whether the connection is suspended. 2539 * @ingroup request 2540 */ 2541 MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, 2542 2543 /** 2544 * Get connection timeout 2545 * @ingroup request 2546 */ 2547 MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, 2548 2549 /** 2550 * Return length of the client's HTTP request header. 2551 * @ingroup request 2552 */ 2553 MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE, 2554 2555 /** 2556 * Return HTTP status queued with the response. NULL 2557 * if no HTTP response has been queued yet. 2558 */ 2559 MHD_CONNECTION_INFO_HTTP_STATUS 2560 2561 } _MHD_FIXED_ENUM; 2562 2563 2564 /** 2565 * Values of this enum are used to specify what 2566 * information about a daemon is desired. 2567 */ 2568 enum MHD_DaemonInfoType 2569 { 2570 /** 2571 * No longer supported (will return NULL). 2572 */ 2573 MHD_DAEMON_INFO_KEY_SIZE, 2574 2575 /** 2576 * No longer supported (will return NULL). 2577 */ 2578 MHD_DAEMON_INFO_MAC_KEY_SIZE, 2579 2580 /** 2581 * Request the file descriptor for the listening socket. 2582 * No extra arguments should be passed. 2583 */ 2584 MHD_DAEMON_INFO_LISTEN_FD, 2585 2586 /** 2587 * Request the file descriptor for the "external" sockets polling 2588 * when 'epoll' mode is used. 2589 * No extra arguments should be passed. 2590 * 2591 * Waiting on epoll FD must not block longer than value 2592 * returned by #MHD_get_timeout() otherwise connections 2593 * will "hung" with unprocessed data in network buffers 2594 * and timed-out connections will not be closed. 2595 * 2596 * @sa #MHD_get_timeout(), #MHD_run() 2597 */ 2598 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2599 MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2600 2601 /** 2602 * Request the number of current connections handled by the daemon. 2603 * No extra arguments should be passed. 2604 * Note: when using MHD in "external" polling mode, this type of request 2605 * could be used only when #MHD_run()/#MHD_run_from_select is not 2606 * working in other thread at the same time. 2607 */ 2608 MHD_DAEMON_INFO_CURRENT_CONNECTIONS, 2609 2610 /** 2611 * Request the daemon flags. 2612 * No extra arguments should be passed. 2613 * Note: flags may differ from original 'flags' specified for 2614 * daemon, especially if #MHD_USE_AUTO was set. 2615 */ 2616 MHD_DAEMON_INFO_FLAGS, 2617 2618 /** 2619 * Request the port number of daemon's listen socket. 2620 * No extra arguments should be passed. 2621 * Note: if port '0' was specified for #MHD_start_daemon(), returned 2622 * value will be real port number. 2623 */ 2624 MHD_DAEMON_INFO_BIND_PORT 2625 } _MHD_FIXED_ENUM; 2626 2627 2628 /** 2629 * Callback for serious error condition. The default action is to print 2630 * an error message and `abort()`. 2631 * 2632 * @param cls user specified value 2633 * @param file where the error occurred, may be NULL if MHD was built without 2634 * messages support 2635 * @param line where the error occurred 2636 * @param reason error detail, may be NULL 2637 * @ingroup logging 2638 */ 2639 typedef void 2640 (*MHD_PanicCallback) (void *cls, 2641 const char *file, 2642 unsigned int line, 2643 const char *reason); 2644 2645 /** 2646 * Allow or deny a client to connect. 2647 * 2648 * @param cls closure 2649 * @param addr address information from the client 2650 * @param addrlen length of @a addr 2651 * @return #MHD_YES if connection is allowed, #MHD_NO if not 2652 */ 2653 typedef enum MHD_Result 2654 (*MHD_AcceptPolicyCallback)(void *cls, 2655 const struct sockaddr *addr, 2656 socklen_t addrlen); 2657 2658 2659 /** 2660 * A client has requested the given @a url using the given @a method 2661 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, #MHD_HTTP_METHOD_DELETE, 2662 * #MHD_HTTP_METHOD_POST, etc). 2663 * 2664 * The callback must call MHD function MHD_queue_response() to provide content 2665 * to give back to the client and return an HTTP status code (i.e. 2666 * #MHD_HTTP_OK, #MHD_HTTP_NOT_FOUND, etc.). The response can be created 2667 * in this callback or prepared in advance. 2668 * Alternatively, callback may call MHD_suspend_connection() to temporarily 2669 * suspend data processing for this connection. 2670 * 2671 * As soon as response is provided this callback will not be called anymore 2672 * for the current request. 2673 * 2674 * For each HTTP request this callback is called several times: 2675 * * after request headers are fully received and decoded, 2676 * * for each received part of request body (optional, if request has body), 2677 * * when request is fully received. 2678 * 2679 * If response is provided before request is fully received, the rest 2680 * of the request is discarded and connection is automatically closed 2681 * after sending response. 2682 * 2683 * If the request is fully received, but response hasn't been provided and 2684 * connection is not suspended, the callback can be called again immediately. 2685 * 2686 * The response cannot be queued when this callback is called to process 2687 * the client upload data (when @a upload_data is not NULL). 2688 * 2689 * @param cls argument given together with the function 2690 * pointer when the handler was registered with MHD 2691 * @param connection the connection handle 2692 * @param url the requested url 2693 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, 2694 * #MHD_HTTP_METHOD_PUT, etc.) 2695 * @param version the HTTP version string (i.e. 2696 * #MHD_HTTP_VERSION_1_1) 2697 * @param upload_data the data being uploaded (excluding HEADERS, 2698 * for a POST that fits into memory and that is encoded 2699 * with a supported encoding, the POST data will NOT be 2700 * given in upload_data and is instead available as 2701 * part of #MHD_get_connection_values; very large POST 2702 * data *will* be made available incrementally in 2703 * @a upload_data) 2704 * @param[in,out] upload_data_size set initially to the size of the 2705 * @a upload_data provided; the method must update this 2706 * value to the number of bytes NOT processed; 2707 * @param[in,out] req_cls pointer that the callback can set to some 2708 * address and that will be preserved by MHD for future 2709 * calls for this request; since the access handler may 2710 * be called many times (i.e., for a PUT/POST operation 2711 * with plenty of upload data) this allows the application 2712 * to easily associate some request-specific state. 2713 * If necessary, this state can be cleaned up in the 2714 * global #MHD_RequestCompletedCallback (which 2715 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 2716 * Initially, `*req_cls` will be NULL. 2717 * @return #MHD_YES if the connection was handled successfully, 2718 * #MHD_NO if the socket must be closed due to a serious 2719 * error while handling the request 2720 * 2721 * @sa #MHD_queue_response() 2722 */ 2723 typedef enum MHD_Result 2724 (*MHD_AccessHandlerCallback)(void *cls, 2725 struct MHD_Connection *connection, 2726 const char *url, 2727 const char *method, 2728 const char *version, 2729 const char *upload_data, 2730 size_t *upload_data_size, 2731 void **req_cls); 2732 2733 2734 /** 2735 * Signature of the callback used by MHD to notify the 2736 * application about completed requests. 2737 * 2738 * @param cls client-defined closure 2739 * @param connection connection handle 2740 * @param req_cls value as set by the last call to 2741 * the #MHD_AccessHandlerCallback 2742 * @param toe reason for request termination 2743 * @see #MHD_OPTION_NOTIFY_COMPLETED 2744 * @ingroup request 2745 */ 2746 typedef void 2747 (*MHD_RequestCompletedCallback) (void *cls, 2748 struct MHD_Connection *connection, 2749 void **req_cls, 2750 enum MHD_RequestTerminationCode toe); 2751 2752 2753 /** 2754 * Signature of the callback used by MHD to notify the 2755 * application about started/stopped connections 2756 * 2757 * @param cls client-defined closure 2758 * @param connection connection handle 2759 * @param socket_context socket-specific pointer where the 2760 * client can associate some state specific 2761 * to the TCP connection; note that this is 2762 * different from the "req_cls" which is per 2763 * HTTP request. The client can initialize 2764 * during #MHD_CONNECTION_NOTIFY_STARTED and 2765 * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED 2766 * and access in the meantime using 2767 * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. 2768 * @param toe reason for connection notification 2769 * @see #MHD_OPTION_NOTIFY_CONNECTION 2770 * @ingroup request 2771 */ 2772 typedef void 2773 (*MHD_NotifyConnectionCallback) (void *cls, 2774 struct MHD_Connection *connection, 2775 void **socket_context, 2776 enum MHD_ConnectionNotificationCode toe); 2777 2778 2779 /** 2780 * Iterator over key-value pairs. This iterator 2781 * can be used to iterate over all of the cookies, 2782 * headers, or POST-data fields of a request, and 2783 * also to iterate over the headers that have been 2784 * added to a response. 2785 * 2786 * @param cls closure 2787 * @param kind kind of the header we are looking at 2788 * @param key key for the value, can be an empty string 2789 * @param value corresponding value, can be NULL 2790 * @return #MHD_YES to continue iterating, 2791 * #MHD_NO to abort the iteration 2792 * @ingroup request 2793 */ 2794 typedef enum MHD_Result 2795 (*MHD_KeyValueIterator)(void *cls, 2796 enum MHD_ValueKind kind, 2797 const char *key, 2798 const char *value); 2799 2800 2801 /** 2802 * Iterator over key-value pairs with size parameters. 2803 * This iterator can be used to iterate over all of 2804 * the cookies, headers, or POST-data fields of a 2805 * request, and also to iterate over the headers that 2806 * have been added to a response. 2807 * @note Available since #MHD_VERSION 0x00096303 2808 * 2809 * @param cls closure 2810 * @param kind kind of the header we are looking at 2811 * @param key key for the value, can be an empty string 2812 * @param value corresponding value, can be NULL 2813 * @param value_size number of bytes in @a value; 2814 * for C-strings, the length excludes the 0-terminator 2815 * @return #MHD_YES to continue iterating, 2816 * #MHD_NO to abort the iteration 2817 * @ingroup request 2818 */ 2819 typedef enum MHD_Result 2820 (*MHD_KeyValueIteratorN)(void *cls, 2821 enum MHD_ValueKind kind, 2822 const char *key, 2823 size_t key_size, 2824 const char *value, 2825 size_t value_size); 2826 2827 2828 /** 2829 * Callback used by libmicrohttpd in order to obtain content. 2830 * 2831 * The callback is to copy at most @a max bytes of content into @a buf. 2832 * The total number of bytes that has been placed into @a buf should be 2833 * returned. 2834 * 2835 * Note that returning zero will cause libmicrohttpd to try again. 2836 * Thus, returning zero should only be used in conjunction 2837 * with MHD_suspend_connection() to avoid busy waiting. 2838 * 2839 * @param cls extra argument to the callback 2840 * @param pos position in the datastream to access; 2841 * note that if a `struct MHD_Response` object is re-used, 2842 * it is possible for the same content reader to 2843 * be queried multiple times for the same data; 2844 * however, if a `struct MHD_Response` is not re-used, 2845 * libmicrohttpd guarantees that "pos" will be 2846 * the sum of all non-negative return values 2847 * obtained from the content reader so far. 2848 * @param buf where to copy the data 2849 * @param max maximum number of bytes to copy to @a buf (size of @a buf) 2850 * @return number of bytes written to @a buf; 2851 * 0 is legal unless MHD is started in "internal" sockets polling mode 2852 * (since this would cause busy-waiting); 0 in "external" sockets 2853 * polling mode will cause this function to be called again once 2854 * any MHD_run*() function is called; 2855 * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular 2856 * end of transmission (with chunked encoding, MHD will then 2857 * terminate the chunk and send any HTTP footers that might be 2858 * present; without chunked encoding and given an unknown 2859 * response size, MHD will simply close the connection; note 2860 * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically 2861 * legal if a response size was specified, MHD accepts this 2862 * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; 2863 * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server 2864 * error generating the response; this will cause MHD to simply 2865 * close the connection immediately. If a response size was 2866 * given or if chunked encoding is in use, this will indicate 2867 * an error to the client. Note, however, that if the client 2868 * does not know a response size and chunked encoding is not in 2869 * use, then clients will not be able to tell the difference between 2870 * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. 2871 * This is not a limitation of MHD but rather of the HTTP protocol. 2872 */ 2873 typedef ssize_t 2874 (*MHD_ContentReaderCallback) (void *cls, 2875 uint64_t pos, 2876 char *buf, 2877 size_t max); 2878 2879 2880 /** 2881 * This method is called by libmicrohttpd if we 2882 * are done with a content reader. It should 2883 * be used to free resources associated with the 2884 * content reader. 2885 * 2886 * @param cls closure 2887 * @ingroup response 2888 */ 2889 typedef void 2890 (*MHD_ContentReaderFreeCallback) (void *cls); 2891 2892 2893 /** 2894 * Iterator over key-value pairs where the value 2895 * may be made available in increments and/or may 2896 * not be zero-terminated. Used for processing 2897 * POST data. 2898 * 2899 * @param cls user-specified closure 2900 * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD 2901 * @param key 0-terminated key for the value, NULL if not known. This value 2902 * is never NULL for url-encoded POST data. 2903 * @param filename name of the uploaded file, NULL if not known 2904 * @param content_type mime-type of the data, NULL if not known 2905 * @param transfer_encoding encoding of the data, NULL if not known 2906 * @param data pointer to @a size bytes of data at the 2907 * specified offset 2908 * @param off offset of data in the overall value 2909 * @param size number of bytes in @a data available 2910 * @return #MHD_YES to continue iterating, 2911 * #MHD_NO to abort the iteration 2912 */ 2913 typedef enum MHD_Result 2914 (*MHD_PostDataIterator)(void *cls, 2915 enum MHD_ValueKind kind, 2916 const char *key, 2917 const char *filename, 2918 const char *content_type, 2919 const char *transfer_encoding, 2920 const char *data, 2921 uint64_t off, 2922 size_t size); 2923 2924 /* **************** Daemon handling functions ***************** */ 2925 2926 /** 2927 * Start a webserver on the given port. 2928 * 2929 * @param flags combination of `enum MHD_FLAG` values 2930 * @param port port to bind to (in host byte order), 2931 * use '0' to bind to random free port, 2932 * ignored if MHD_OPTION_SOCK_ADDR or 2933 * MHD_OPTION_LISTEN_SOCKET is provided 2934 * or MHD_USE_NO_LISTEN_SOCKET is specified 2935 * @param apc callback to call to check which clients 2936 * will be allowed to connect; you can pass NULL 2937 * in which case connections from any IP will be 2938 * accepted 2939 * @param apc_cls extra argument to apc 2940 * @param dh handler called for all requests (repeatedly) 2941 * @param dh_cls extra argument to @a dh 2942 * @param ap list of options (type-value pairs, 2943 * terminated with #MHD_OPTION_END). 2944 * @return NULL on error, handle to daemon on success 2945 * @ingroup event 2946 */ 2947 _MHD_EXTERN struct MHD_Daemon * 2948 MHD_start_daemon_va (unsigned int flags, 2949 uint16_t port, 2950 MHD_AcceptPolicyCallback apc, void *apc_cls, 2951 MHD_AccessHandlerCallback dh, void *dh_cls, 2952 va_list ap); 2953 2954 2955 /** 2956 * Start a webserver on the given port. Variadic version of 2957 * #MHD_start_daemon_va. 2958 * 2959 * @param flags combination of `enum MHD_FLAG` values 2960 * @param port port to bind to (in host byte order), 2961 * use '0' to bind to random free port, 2962 * ignored if MHD_OPTION_SOCK_ADDR or 2963 * MHD_OPTION_LISTEN_SOCKET is provided 2964 * or MHD_USE_NO_LISTEN_SOCKET is specified 2965 * @param apc callback to call to check which clients 2966 * will be allowed to connect; you can pass NULL 2967 * in which case connections from any IP will be 2968 * accepted 2969 * @param apc_cls extra argument to apc 2970 * @param dh handler called for all requests (repeatedly) 2971 * @param dh_cls extra argument to @a dh 2972 * @return NULL on error, handle to daemon on success 2973 * @ingroup event 2974 */ 2975 _MHD_EXTERN struct MHD_Daemon * 2976 MHD_start_daemon (unsigned int flags, 2977 uint16_t port, 2978 MHD_AcceptPolicyCallback apc, void *apc_cls, 2979 MHD_AccessHandlerCallback dh, void *dh_cls, 2980 ...); 2981 2982 2983 /** 2984 * Stop accepting connections from the listening socket. Allows 2985 * clients to continue processing, but stops accepting new 2986 * connections. Note that the caller is responsible for closing the 2987 * returned socket; however, if MHD is run using threads (anything but 2988 * "external" sockets polling mode), it must not be closed until AFTER 2989 * #MHD_stop_daemon has been called (as it is theoretically possible 2990 * that an existing thread is still using it). 2991 * 2992 * Note that some thread modes require the caller to have passed 2993 * #MHD_USE_ITC when using this API. If this daemon is 2994 * in one of those modes and this option was not given to 2995 * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. 2996 * 2997 * @param daemon daemon to stop accepting new connections for 2998 * @return old listen socket on success, #MHD_INVALID_SOCKET if 2999 * the daemon was already not listening anymore 3000 * @ingroup specialized 3001 */ 3002 _MHD_EXTERN MHD_socket 3003 MHD_quiesce_daemon (struct MHD_Daemon *daemon); 3004 3005 3006 /** 3007 * Shutdown an HTTP daemon. 3008 * 3009 * @param daemon daemon to stop 3010 * @ingroup event 3011 */ 3012 _MHD_EXTERN void 3013 MHD_stop_daemon (struct MHD_Daemon *daemon); 3014 3015 3016 /** 3017 * Add another client connection to the set of connections managed by 3018 * MHD. This API is usually not needed (since MHD will accept inbound 3019 * connections on the server socket). Use this API in special cases, 3020 * for example if your HTTP server is behind NAT and needs to connect 3021 * out to the HTTP client, or if you are building a proxy. 3022 * 3023 * If you use this API in conjunction with an "internal" socket polling, 3024 * you must set the option #MHD_USE_ITC to ensure that the freshly added 3025 * connection is immediately processed by MHD. 3026 * 3027 * The given client socket will be managed (and closed!) by MHD after 3028 * this call and must no longer be used directly by the application 3029 * afterwards. 3030 * 3031 * @param daemon daemon that manages the connection 3032 * @param client_socket socket to manage (MHD will expect 3033 * to receive an HTTP request from this socket next). 3034 * @param addr IP address of the client 3035 * @param addrlen number of bytes in @a addr 3036 * @return #MHD_YES on success, #MHD_NO if this daemon could 3037 * not handle the connection (i.e. `malloc()` failed, etc). 3038 * The socket will be closed in any case; `errno` is 3039 * set to indicate further details about the error. 3040 * @ingroup specialized 3041 */ 3042 _MHD_EXTERN enum MHD_Result 3043 MHD_add_connection (struct MHD_Daemon *daemon, 3044 MHD_socket client_socket, 3045 const struct sockaddr *addr, 3046 socklen_t addrlen); 3047 3048 3049 /** 3050 * Obtain the `select()` sets for this daemon. 3051 * Daemon's FDs will be added to fd_sets. To get only 3052 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3053 * before calling this function. FD_SETSIZE is assumed 3054 * to be platform's default. 3055 * 3056 * This function should be called only when MHD is configured to 3057 * use "external" sockets polling with 'select()' or with 'epoll'. 3058 * In the latter case, it will only add the single 'epoll' file 3059 * descriptor used by MHD to the sets. 3060 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3061 * value for `select()`. Usage of `select()` with indefinite timeout 3062 * (or timeout larger than returned by #MHD_get_timeout()) will 3063 * violate MHD API and may results in pending unprocessed data. 3064 * 3065 * This function must be called only for daemon started 3066 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3067 * 3068 * @param daemon daemon to get sets from 3069 * @param read_fd_set read set 3070 * @param write_fd_set write set 3071 * @param except_fd_set except set 3072 * @param max_fd increased to largest FD added (if larger 3073 * than existing value); can be NULL 3074 * @return #MHD_YES on success, #MHD_NO if this 3075 * daemon was not started with the right 3076 * options for this call or any FD didn't 3077 * fit fd_set. 3078 * @ingroup event 3079 */ 3080 _MHD_EXTERN enum MHD_Result 3081 MHD_get_fdset (struct MHD_Daemon *daemon, 3082 fd_set *read_fd_set, 3083 fd_set *write_fd_set, 3084 fd_set *except_fd_set, 3085 MHD_socket *max_fd); 3086 3087 3088 /** 3089 * Obtain the `select()` sets for this daemon. 3090 * Daemon's FDs will be added to fd_sets. To get only 3091 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3092 * before calling this function. 3093 * 3094 * Passing custom FD_SETSIZE as @a fd_setsize allow usage of 3095 * larger/smaller than platform's default fd_sets. 3096 * 3097 * This function should be called only when MHD is configured to 3098 * use "external" sockets polling with 'select()' or with 'epoll'. 3099 * In the latter case, it will only add the single 'epoll' file 3100 * descriptor used by MHD to the sets. 3101 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3102 * value for `select()`. Usage of `select()` with indefinite timeout 3103 * (or timeout larger than returned by #MHD_get_timeout()) will 3104 * violate MHD API and may results in pending unprocessed data. 3105 * 3106 * This function must be called only for daemon started 3107 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3108 * 3109 * @param daemon daemon to get sets from 3110 * @param read_fd_set read set 3111 * @param write_fd_set write set 3112 * @param except_fd_set except set 3113 * @param max_fd increased to largest FD added (if larger 3114 * than existing value); can be NULL 3115 * @param fd_setsize value of FD_SETSIZE 3116 * @return #MHD_YES on success, #MHD_NO if this 3117 * daemon was not started with the right 3118 * options for this call or any FD didn't 3119 * fit fd_set. 3120 * @ingroup event 3121 */ 3122 _MHD_EXTERN enum MHD_Result 3123 MHD_get_fdset2 (struct MHD_Daemon *daemon, 3124 fd_set *read_fd_set, 3125 fd_set *write_fd_set, 3126 fd_set *except_fd_set, 3127 MHD_socket *max_fd, 3128 unsigned int fd_setsize); 3129 3130 3131 /** 3132 * Obtain the `select()` sets for this daemon. 3133 * Daemon's FDs will be added to fd_sets. To get only 3134 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3135 * before calling this function. Size of fd_set is 3136 * determined by current value of FD_SETSIZE. 3137 * 3138 * This function should be called only when MHD is configured to 3139 * use "external" sockets polling with 'select()' or with 'epoll'. 3140 * In the latter case, it will only add the single 'epoll' file 3141 * descriptor used by MHD to the sets. 3142 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3143 * value for `select()`. Usage of `select()` with indefinite timeout 3144 * (or timeout larger than returned by #MHD_get_timeout()) will 3145 * violate MHD API and may results in pending unprocessed data. 3146 * 3147 * This function must be called only for daemon started 3148 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3149 * 3150 * @param daemon daemon to get sets from 3151 * @param read_fd_set read set 3152 * @param write_fd_set write set 3153 * @param except_fd_set except set 3154 * @param max_fd increased to largest FD added (if larger 3155 * than existing value); can be NULL 3156 * @return #MHD_YES on success, #MHD_NO if this 3157 * daemon was not started with the right 3158 * options for this call or any FD didn't 3159 * fit fd_set. 3160 * @ingroup event 3161 */ 3162 #define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ 3163 MHD_get_fdset2 ((daemon),(read_fd_set),(write_fd_set),(except_fd_set), \ 3164 (max_fd),FD_SETSIZE) 3165 3166 3167 /** 3168 * Obtain timeout value for polling function for this daemon. 3169 * 3170 * This function set value to the amount of milliseconds for which polling 3171 * function (`select()`, `poll()` or epoll) should at most block, not the 3172 * timeout value set for connections. 3173 * 3174 * Any "external" sockets polling function must be called with the timeout 3175 * value provided by this function. Smaller timeout values can be used for 3176 * polling function if it is required for any reason, but using larger 3177 * timeout value or no timeout (indefinite timeout) when this function 3178 * return #MHD_YES will break MHD processing logic and result in "hung" 3179 * connections with data pending in network buffers and other problems. 3180 * 3181 * It is important to always use this function (or #MHD_get_timeout64(), 3182 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3183 * polling is used. 3184 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3185 * must be called right after return from polling function, regardless of 3186 * the states of MHD FDs. 3187 * 3188 * In practice, if #MHD_YES is returned then #MHD_run() (or 3189 * #MHD_run_from_select()) must be called not later than @a timeout 3190 * millisecond even if no activity is detected on sockets by sockets 3191 * polling function. 3192 * 3193 * @param daemon daemon to query for timeout 3194 * @param[out] timeout set to the timeout (in milliseconds) 3195 * @return #MHD_YES on success, #MHD_NO if timeouts are 3196 * not used and no data processing is pending. 3197 * @ingroup event 3198 */ 3199 _MHD_EXTERN enum MHD_Result 3200 MHD_get_timeout (struct MHD_Daemon *daemon, 3201 MHD_UNSIGNED_LONG_LONG *timeout); 3202 3203 3204 /** 3205 * Free the memory allocated by MHD. 3206 * 3207 * If any MHD function explicitly mentions that returned pointer must be 3208 * freed by this function, then no other method must be used to free 3209 * the memory. 3210 * 3211 * @param ptr the pointer to free. 3212 * @sa #MHD_digest_auth_get_username(), #MHD_basic_auth_get_username_password3() 3213 * @sa #MHD_basic_auth_get_username_password() 3214 * @note Available since #MHD_VERSION 0x00095600 3215 * @ingroup specialized 3216 */ 3217 _MHD_EXTERN void 3218 MHD_free (void *ptr); 3219 3220 /** 3221 * Obtain timeout value for external polling function for this daemon. 3222 * 3223 * This function set value to the amount of milliseconds for which polling 3224 * function (`select()`, `poll()` or epoll) should at most block, not the 3225 * timeout value set for connections. 3226 * 3227 * Any "external" sockets polling function must be called with the timeout 3228 * value provided by this function. Smaller timeout values can be used for 3229 * polling function if it is required for any reason, but using larger 3230 * timeout value or no timeout (indefinite timeout) when this function 3231 * return #MHD_YES will break MHD processing logic and result in "hung" 3232 * connections with data pending in network buffers and other problems. 3233 * 3234 * It is important to always use this function (or #MHD_get_timeout(), 3235 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3236 * polling is used. 3237 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3238 * must be called right after return from polling function, regardless of 3239 * the states of MHD FDs. 3240 * 3241 * In practice, if #MHD_YES is returned then #MHD_run() (or 3242 * #MHD_run_from_select()) must be called not later than @a timeout 3243 * millisecond even if no activity is detected on sockets by sockets 3244 * polling function. 3245 * 3246 * @param daemon daemon to query for timeout 3247 * @param[out] timeout64 the pointer to the variable to be set to the 3248 * timeout (in milliseconds) 3249 * @return #MHD_YES if timeout value has been set, 3250 * #MHD_NO if timeouts are not used and no data processing is pending. 3251 * @note Available since #MHD_VERSION 0x00097701 3252 * @ingroup event 3253 */ 3254 _MHD_EXTERN enum MHD_Result 3255 MHD_get_timeout64 (struct MHD_Daemon *daemon, 3256 uint64_t *timeout); 3257 3258 3259 /** 3260 * Obtain timeout value for external polling function for this daemon. 3261 * 3262 * This function set value to the amount of milliseconds for which polling 3263 * function (`select()`, `poll()` or epoll) should at most block, not the 3264 * timeout value set for connections. 3265 * 3266 * Any "external" sockets polling function must be called with the timeout 3267 * value provided by this function (if returned value is non-negative). 3268 * Smaller timeout values can be used for polling function if it is required 3269 * for any reason, but using larger timeout value or no timeout (indefinite 3270 * timeout) when this function returns non-negative value will break MHD 3271 * processing logic and result in "hung" connections with data pending in 3272 * network buffers and other problems. 3273 * 3274 * It is important to always use this function (or #MHD_get_timeout(), 3275 * #MHD_get_timeout64(), #MHD_get_timeout_i() functions) when "external" 3276 * polling is used. 3277 * If this function returns non-negative value then #MHD_run() (or 3278 * #MHD_run_from_select()) must be called right after return from polling 3279 * function, regardless of the states of MHD FDs. 3280 * 3281 * In practice, if zero or positive value is returned then #MHD_run() (or 3282 * #MHD_run_from_select()) must be called not later than returned amount of 3283 * millisecond even if no activity is detected on sockets by sockets 3284 * polling function. 3285 * 3286 * @param daemon the daemon to query for timeout 3287 * @return -1 if connections' timeouts are not set and no data processing 3288 * is pending, so external polling function may wait for sockets 3289 * activity for indefinite amount of time, 3290 * otherwise returned value is the the maximum amount of millisecond 3291 * that external polling function must wait for the activity of FDs. 3292 * @note Available since #MHD_VERSION 0x00097701 3293 * @ingroup event 3294 */ 3295 _MHD_EXTERN int64_t 3296 MHD_get_timeout64s (struct MHD_Daemon *daemon); 3297 3298 3299 /** 3300 * Obtain timeout value for external polling function for this daemon. 3301 * 3302 * This function set value to the amount of milliseconds for which polling 3303 * function (`select()`, `poll()` or epoll) should at most block, not the 3304 * timeout value set for connections. 3305 * 3306 * Any "external" sockets polling function must be called with the timeout 3307 * value provided by this function (if returned value is non-negative). 3308 * Smaller timeout values can be used for polling function if it is required 3309 * for any reason, but using larger timeout value or no timeout (indefinite 3310 * timeout) when this function returns non-negative value will break MHD 3311 * processing logic and result in "hung" connections with data pending in 3312 * network buffers and other problems. 3313 * 3314 * It is important to always use this function (or #MHD_get_timeout(), 3315 * #MHD_get_timeout64(), #MHD_get_timeout64s() functions) when "external" 3316 * polling is used. 3317 * If this function returns non-negative value then #MHD_run() (or 3318 * #MHD_run_from_select()) must be called right after return from polling 3319 * function, regardless of the states of MHD FDs. 3320 * 3321 * In practice, if zero or positive value is returned then #MHD_run() (or 3322 * #MHD_run_from_select()) must be called not later than returned amount of 3323 * millisecond even if no activity is detected on sockets by sockets 3324 * polling function. 3325 * 3326 * @param daemon the daemon to query for timeout 3327 * @return -1 if connections' timeouts are not set and no data processing 3328 * is pending, so external polling function may wait for sockets 3329 * activity for indefinite amount of time, 3330 * otherwise returned value is the the maximum amount of millisecond 3331 * (capped at INT_MAX) that external polling function must wait 3332 * for the activity of FDs. 3333 * @note Available since #MHD_VERSION 0x00097701 3334 * @ingroup event 3335 */ 3336 _MHD_EXTERN int 3337 MHD_get_timeout_i (struct MHD_Daemon *daemon); 3338 3339 3340 /** 3341 * Run webserver operations (without blocking unless in client callbacks). 3342 * 3343 * This method should be called by clients in combination with 3344 * #MHD_get_fdset() (or #MHD_get_daemon_info() with MHD_DAEMON_INFO_EPOLL_FD 3345 * if epoll is used) and #MHD_get_timeout() if the client-controlled 3346 * connection polling method is used (i.e. daemon was started without 3347 * #MHD_USE_INTERNAL_POLLING_THREAD flag). 3348 * 3349 * This function is a convenience method, which is useful if the 3350 * fd_sets from #MHD_get_fdset were not directly passed to `select()`; 3351 * with this function, MHD will internally do the appropriate `select()` 3352 * call itself again. While it is acceptable to call #MHD_run (if 3353 * #MHD_USE_INTERNAL_POLLING_THREAD is not set) at any moment, you should 3354 * call #MHD_run_from_select() if performance is important (as it saves an 3355 * expensive call to `select()`). 3356 * 3357 * If #MHD_get_timeout() returned #MHD_YES, than this function must be called 3358 * right after polling function returns regardless of detected activity on 3359 * the daemon's FDs. 3360 * 3361 * @param daemon daemon to run 3362 * @return #MHD_YES on success, #MHD_NO if this 3363 * daemon was not started with the right 3364 * options for this call. 3365 * @ingroup event 3366 */ 3367 _MHD_EXTERN enum MHD_Result 3368 MHD_run (struct MHD_Daemon *daemon); 3369 3370 3371 /** 3372 * Run websever operation with possible blocking. 3373 * 3374 * This function does the following: waits for any network event not more than 3375 * specified number of milliseconds, processes all incoming and outgoing data, 3376 * processes new connections, processes any timed-out connection, and does 3377 * other things required to run webserver. 3378 * Once all connections are processed, function returns. 3379 * 3380 * This function is useful for quick and simple (lazy) webserver implementation 3381 * if application needs to run a single thread only and does not have any other 3382 * network activity. 3383 * 3384 * This function calls MHD_get_timeout() internally and use returned value as 3385 * maximum wait time if it less than value of @a millisec parameter. 3386 * 3387 * It is expected that the "external" socket polling function is not used in 3388 * conjunction with this function unless the @a millisec is set to zero. 3389 * 3390 * @param daemon the daemon to run 3391 * @param millisec the maximum time in milliseconds to wait for network and 3392 * other events. Note: there is no guarantee that function 3393 * blocks for the specified amount of time. The real processing 3394 * time can be shorter (if some data or connection timeout 3395 * comes earlier) or longer (if data processing requires more 3396 * time, especially in user callbacks). 3397 * If set to '0' then function does not block and processes 3398 * only already available data (if any). 3399 * If set to '-1' then function waits for events 3400 * indefinitely (blocks until next network activity or 3401 * connection timeout). 3402 * @return #MHD_YES on success, #MHD_NO if this 3403 * daemon was not started with the right 3404 * options for this call or some serious 3405 * unrecoverable error occurs. 3406 * @note Available since #MHD_VERSION 0x00097206 3407 * @ingroup event 3408 */ 3409 _MHD_EXTERN enum MHD_Result 3410 MHD_run_wait (struct MHD_Daemon *daemon, 3411 int32_t millisec); 3412 3413 3414 /** 3415 * Run webserver operations. This method should be called by clients 3416 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3417 * client-controlled select method is used. 3418 * 3419 * You can use this function instead of #MHD_run if you called 3420 * `select()` on the result from #MHD_get_fdset. File descriptors in 3421 * the sets that are not controlled by MHD will be ignored. Calling 3422 * this function instead of #MHD_run is more efficient as MHD will 3423 * not have to call `select()` again to determine which operations are 3424 * ready. 3425 * 3426 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3427 * called right after `select()` returns regardless of detected activity 3428 * on the daemon's FDs. 3429 * 3430 * This function cannot be used with daemon started with 3431 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3432 * 3433 * @param daemon daemon to run select loop for 3434 * @param read_fd_set read set 3435 * @param write_fd_set write set 3436 * @param except_fd_set except set 3437 * @return #MHD_NO on serious errors, #MHD_YES on success 3438 * @ingroup event 3439 */ 3440 _MHD_EXTERN enum MHD_Result 3441 MHD_run_from_select (struct MHD_Daemon *daemon, 3442 const fd_set *read_fd_set, 3443 const fd_set *write_fd_set, 3444 const fd_set *except_fd_set); 3445 3446 3447 /** 3448 * Run webserver operations. This method should be called by clients 3449 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3450 * client-controlled select method is used. 3451 * This function specifies FD_SETSIZE used when provided fd_sets were 3452 * created. It is important on platforms where FD_SETSIZE can be 3453 * overridden. 3454 * 3455 * You can use this function instead of #MHD_run if you called 3456 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3457 * the sets that are not controlled by MHD will be ignored. Calling 3458 * this function instead of #MHD_run() is more efficient as MHD will 3459 * not have to call 'select()' again to determine which operations are 3460 * ready. 3461 * 3462 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3463 * called right after 'select()' returns regardless of detected activity 3464 * on the daemon's FDs. 3465 * 3466 * This function cannot be used with daemon started with 3467 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3468 * 3469 * @param daemon the daemon to run select loop for 3470 * @param read_fd_set the read set 3471 * @param write_fd_set the write set 3472 * @param except_fd_set the except set 3473 * @param fd_setsize the value of FD_SETSIZE 3474 * @return #MHD_NO on serious errors, #MHD_YES on success 3475 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3476 * @ingroup event 3477 */ 3478 _MHD_EXTERN enum MHD_Result 3479 MHD_run_from_select2 (struct MHD_Daemon *daemon, 3480 const fd_set *read_fd_set, 3481 const fd_set *write_fd_set, 3482 const fd_set *except_fd_set, 3483 unsigned int fd_setsize); 3484 3485 3486 /** 3487 * Run webserver operations. This method should be called by clients 3488 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3489 * client-controlled select method is used. 3490 * This macro automatically substitutes current FD_SETSIZE value. 3491 * It is important on platforms where FD_SETSIZE can be overridden. 3492 * 3493 * You can use this function instead of #MHD_run if you called 3494 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3495 * the sets that are not controlled by MHD will be ignored. Calling 3496 * this function instead of #MHD_run() is more efficient as MHD will 3497 * not have to call 'select()' again to determine which operations are 3498 * ready. 3499 * 3500 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3501 * called right after 'select()' returns regardless of detected activity 3502 * on the daemon's FDs. 3503 * 3504 * This function cannot be used with daemon started with 3505 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3506 * 3507 * @param daemon the daemon to run select loop for 3508 * @param read_fd_set the read set 3509 * @param write_fd_set the write set 3510 * @param except_fd_set the except set 3511 * @param fd_setsize the value of FD_SETSIZE 3512 * @return #MHD_NO on serious errors, #MHD_YES on success 3513 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3514 * @ingroup event 3515 */ 3516 #define MHD_run_from_select(d,r,w,e) \ 3517 MHD_run_from_select2 ((d),(r),(w),(e),(unsigned int) (FD_SETSIZE)) 3518 3519 /* **************** Connection handling functions ***************** */ 3520 3521 /** 3522 * Get all of the headers from the request. 3523 * 3524 * @param connection connection to get values from 3525 * @param kind types of values to iterate over, can be a bitmask 3526 * @param iterator callback to call on each header; 3527 * may be NULL (then just count headers) 3528 * @param iterator_cls extra argument to @a iterator 3529 * @return number of entries iterated over, 3530 * -1 if connection is NULL. 3531 * @ingroup request 3532 */ 3533 _MHD_EXTERN int 3534 MHD_get_connection_values (struct MHD_Connection *connection, 3535 enum MHD_ValueKind kind, 3536 MHD_KeyValueIterator iterator, 3537 void *iterator_cls); 3538 3539 3540 /** 3541 * Get all of the headers from the request. 3542 * 3543 * @param connection connection to get values from 3544 * @param kind types of values to iterate over, can be a bitmask 3545 * @param iterator callback to call on each header; 3546 * may be NULL (then just count headers) 3547 * @param iterator_cls extra argument to @a iterator 3548 * @return number of entries iterated over, 3549 * -1 if connection is NULL. 3550 * @note Available since #MHD_VERSION 0x00096400 3551 * @ingroup request 3552 */ 3553 _MHD_EXTERN int 3554 MHD_get_connection_values_n (struct MHD_Connection *connection, 3555 enum MHD_ValueKind kind, 3556 MHD_KeyValueIteratorN iterator, 3557 void *iterator_cls); 3558 3559 3560 /** 3561 * This function can be used to add an entry to the HTTP headers of a 3562 * connection (so that the #MHD_get_connection_values function will 3563 * return them -- and the `struct MHD_PostProcessor` will also see 3564 * them). This maybe required in certain situations (see Mantis 3565 * #1399) where (broken) HTTP implementations fail to supply values 3566 * needed by the post processor (or other parts of the application). 3567 * 3568 * This function MUST only be called from within the 3569 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3570 * synchronized). Furthermore, the client must guarantee that the key 3571 * and value arguments are 0-terminated strings that are NOT freed 3572 * until the connection is closed. (The easiest way to do this is by 3573 * passing only arguments to permanently allocated strings.). 3574 * 3575 * @param connection the connection for which a 3576 * value should be set 3577 * @param kind kind of the value 3578 * @param key key for the value 3579 * @param value the value itself 3580 * @return #MHD_NO if the operation could not be 3581 * performed due to insufficient memory; 3582 * #MHD_YES on success 3583 * @ingroup request 3584 */ 3585 _MHD_EXTERN enum MHD_Result 3586 MHD_set_connection_value (struct MHD_Connection *connection, 3587 enum MHD_ValueKind kind, 3588 const char *key, 3589 const char *value); 3590 3591 3592 /** 3593 * This function can be used to add an arbitrary entry to connection. 3594 * This function could add entry with binary zero, which is allowed 3595 * for #MHD_GET_ARGUMENT_KIND. For other kind on entries it is 3596 * recommended to use #MHD_set_connection_value. 3597 * 3598 * This function MUST only be called from within the 3599 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3600 * synchronized). Furthermore, the client must guarantee that the key 3601 * and value arguments are 0-terminated strings that are NOT freed 3602 * until the connection is closed. (The easiest way to do this is by 3603 * passing only arguments to permanently allocated strings.). 3604 * 3605 * @param connection the connection for which a 3606 * value should be set 3607 * @param kind kind of the value 3608 * @param key key for the value, must be zero-terminated 3609 * @param key_size number of bytes in @a key (excluding 0-terminator) 3610 * @param value the value itself, must be zero-terminated 3611 * @param value_size number of bytes in @a value (excluding 0-terminator) 3612 * @return #MHD_NO if the operation could not be 3613 * performed due to insufficient memory; 3614 * #MHD_YES on success 3615 * @note Available since #MHD_VERSION 0x00096400 3616 * @ingroup request 3617 */ 3618 _MHD_EXTERN enum MHD_Result 3619 MHD_set_connection_value_n (struct MHD_Connection *connection, 3620 enum MHD_ValueKind kind, 3621 const char *key, 3622 size_t key_size, 3623 const char *value, 3624 size_t value_size); 3625 3626 3627 /** 3628 * Sets the global error handler to a different implementation. 3629 * 3630 * @a cb will only be called in the case of typically fatal, serious internal 3631 * consistency issues or serious system failures like failed lock of mutex. 3632 * 3633 * These issues should only arise in the case of serious memory corruption or 3634 * similar problems with the architecture, there is no safe way to continue 3635 * even for closing of the application. 3636 * 3637 * The default implementation that is used if no panic function is set simply 3638 * prints an error message and calls `abort()`. 3639 * Alternative implementations might call `exit()` or other similar functions. 3640 * 3641 * @param cb new error handler or NULL to use default handler 3642 * @param cls passed to @a cb 3643 * @ingroup logging 3644 */ 3645 _MHD_EXTERN void 3646 MHD_set_panic_func (MHD_PanicCallback cb, void *cls); 3647 3648 3649 /** 3650 * Process escape sequences ('%HH') Updates val in place; the 3651 * result cannot be larger than the input. 3652 * The result is still be 0-terminated. 3653 * 3654 * @param val value to unescape (modified in the process) 3655 * @return length of the resulting val (`strlen(val)` may be 3656 * shorter afterwards due to elimination of escape sequences) 3657 */ 3658 _MHD_EXTERN size_t 3659 MHD_http_unescape (char *val); 3660 3661 3662 /** 3663 * Get a particular header value. If multiple 3664 * values match the kind, return any one of them. 3665 * 3666 * @param connection connection to get values from 3667 * @param kind what kind of value are we looking for 3668 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3669 * @return NULL if no such item was found 3670 * @ingroup request 3671 */ 3672 _MHD_EXTERN const char * 3673 MHD_lookup_connection_value (struct MHD_Connection *connection, 3674 enum MHD_ValueKind kind, 3675 const char *key); 3676 3677 3678 /** 3679 * Get a particular header value. If multiple 3680 * values match the kind, return any one of them. 3681 * @note Since MHD_VERSION 0x00096304 3682 * 3683 * @param connection connection to get values from 3684 * @param kind what kind of value are we looking for 3685 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3686 * @param key_size the length of @a key in bytes 3687 * @param[out] value_ptr the pointer to variable, which will be set to found value, 3688 * will not be updated if key not found, 3689 * could be NULL to just check for presence of @a key 3690 * @param[out] value_size_ptr the pointer variable, which will set to found value, 3691 * will not be updated if key not found, 3692 * could be NULL 3693 * @return #MHD_YES if key is found, 3694 * #MHD_NO otherwise. 3695 * @ingroup request 3696 */ 3697 _MHD_EXTERN enum MHD_Result 3698 MHD_lookup_connection_value_n (struct MHD_Connection *connection, 3699 enum MHD_ValueKind kind, 3700 const char *key, 3701 size_t key_size, 3702 const char **value_ptr, 3703 size_t *value_size_ptr); 3704 3705 3706 /** 3707 * Queue a response to be transmitted to the client (as soon as 3708 * possible but after #MHD_AccessHandlerCallback returns). 3709 * 3710 * For any active connection this function must be called 3711 * only by #MHD_AccessHandlerCallback callback. 3712 * 3713 * For suspended connection this function can be called at any moment (this 3714 * behaviour is deprecated and will be removed!). Response will be sent 3715 * as soon as connection is resumed. 3716 * 3717 * For single thread environment, when MHD is used in "external polling" mode 3718 * (without MHD_USE_SELECT_INTERNALLY) this function can be called any 3719 * time (this behaviour is deprecated and will be removed!). 3720 * 3721 * If HTTP specifications require use no body in reply, like @a status_code with 3722 * value 1xx, the response body is automatically not sent even if it is present 3723 * in the response. No "Content-Length" or "Transfer-Encoding" headers are 3724 * generated and added. 3725 * 3726 * When the response is used to respond HEAD request or used with @a status_code 3727 * #MHD_HTTP_NOT_MODIFIED, then response body is not sent, but "Content-Length" 3728 * header is added automatically based the size of the body in the response. 3729 * If body size it set to #MHD_SIZE_UNKNOWN or chunked encoding is enforced 3730 * then "Transfer-Encoding: chunked" header (for HTTP/1.1 only) is added instead 3731 * of "Content-Length" header. For example, if response with zero-size body is 3732 * used for HEAD request, then "Content-Length: 0" is added automatically to 3733 * reply headers. 3734 * @sa #MHD_RF_HEAD_ONLY_RESPONSE 3735 * 3736 * In situations, where reply body is required, like answer for the GET request 3737 * with @a status_code #MHD_HTTP_OK, headers "Content-Length" (for known body 3738 * size) or "Transfer-Encoding: chunked" (for #MHD_SIZE_UNKNOWN with HTTP/1.1) 3739 * are added automatically. 3740 * In practice, the same response object can be used to respond to both HEAD and 3741 * GET requests. 3742 * 3743 * @param connection the connection identifying the client 3744 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) 3745 * @param response response to transmit, the NULL is tolerated 3746 * @return #MHD_NO on error (reply already sent, response is NULL), 3747 * #MHD_YES on success or if message has been queued 3748 * @ingroup response 3749 * @sa #MHD_AccessHandlerCallback 3750 */ 3751 _MHD_EXTERN enum MHD_Result 3752 MHD_queue_response (struct MHD_Connection *connection, 3753 unsigned int status_code, 3754 struct MHD_Response *response); 3755 3756 3757 /** 3758 * Suspend handling of network data for a given connection. 3759 * This can be used to dequeue a connection from MHD's event loop 3760 * (not applicable to thread-per-connection!) for a while. 3761 * 3762 * If you use this API in conjunction with an "internal" socket polling, 3763 * you must set the option #MHD_USE_ITC to ensure that a resumed 3764 * connection is immediately processed by MHD. 3765 * 3766 * Suspended connections continue to count against the total number of 3767 * connections allowed (per daemon, as well as per IP, if such limits 3768 * are set). Suspended connections will NOT time out; timeouts will 3769 * restart when the connection handling is resumed. While a 3770 * connection is suspended, MHD will not detect disconnects by the 3771 * client. 3772 * 3773 * The only safe way to call this function is to call it from the 3774 * #MHD_AccessHandlerCallback or #MHD_ContentReaderCallback. 3775 * 3776 * Finally, it is an API violation to call #MHD_stop_daemon while 3777 * having suspended connections (this will at least create memory and 3778 * socket leaks or lead to undefined behavior). You must explicitly 3779 * resume all connections before stopping the daemon. 3780 * 3781 * @param connection the connection to suspend 3782 * 3783 * @sa #MHD_AccessHandlerCallback 3784 */ 3785 _MHD_EXTERN void 3786 MHD_suspend_connection (struct MHD_Connection *connection); 3787 3788 3789 /** 3790 * Resume handling of network data for suspended connection. It is 3791 * safe to resume a suspended connection at any time. Calling this 3792 * function on a connection that was not previously suspended will 3793 * result in undefined behavior. 3794 * 3795 * If you are using this function in "external" sockets polling mode, you must 3796 * make sure to run #MHD_run() and #MHD_get_timeout() afterwards (before 3797 * again calling #MHD_get_fdset()), as otherwise the change may not be 3798 * reflected in the set returned by #MHD_get_fdset() and you may end up 3799 * with a connection that is stuck until the next network activity. 3800 * 3801 * @param connection the connection to resume 3802 */ 3803 _MHD_EXTERN void 3804 MHD_resume_connection (struct MHD_Connection *connection); 3805 3806 3807 /* **************** Response manipulation functions ***************** */ 3808 3809 3810 /** 3811 * Flags for special handling of responses. 3812 */ 3813 enum MHD_ResponseFlags 3814 { 3815 /** 3816 * Default: no special flags. 3817 * @note Available since #MHD_VERSION 0x00093701 3818 */ 3819 MHD_RF_NONE = 0, 3820 3821 /** 3822 * Only respond in conservative (dumb) HTTP/1.0-compatible mode. 3823 * Response still use HTTP/1.1 version in header, but always close 3824 * the connection after sending the response and do not use chunked 3825 * encoding for the response. 3826 * You can also set the #MHD_RF_HTTP_1_0_SERVER flag to force 3827 * HTTP/1.0 version in the response. 3828 * Responses are still compatible with HTTP/1.1. 3829 * This option can be used to communicate with some broken client, which 3830 * does not implement HTTP/1.1 features, but advertises HTTP/1.1 support. 3831 * @note Available since #MHD_VERSION 0x00097308 3832 */ 3833 MHD_RF_HTTP_1_0_COMPATIBLE_STRICT = 1 << 0, 3834 /** 3835 * The same as #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT 3836 * @note Available since #MHD_VERSION 0x00093701 3837 */ 3838 MHD_RF_HTTP_VERSION_1_0_ONLY = 1 << 0, 3839 3840 /** 3841 * Only respond in HTTP 1.0-mode. 3842 * Contrary to the #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT flag, the response's 3843 * HTTP version will always be set to 1.0 and keep-alive connections 3844 * will be used if explicitly requested by the client. 3845 * The "Connection:" header will be added for both "close" and "keep-alive" 3846 * connections. 3847 * Chunked encoding will not be used for the response. 3848 * Due to backward compatibility, responses still can be used with 3849 * HTTP/1.1 clients. 3850 * This option can be used to emulate HTTP/1.0 server (for response part 3851 * only as chunked encoding in requests (if any) is processed by MHD). 3852 * @note Available since #MHD_VERSION 0x00097308 3853 */ 3854 MHD_RF_HTTP_1_0_SERVER = 1 << 1, 3855 /** 3856 * The same as #MHD_RF_HTTP_1_0_SERVER 3857 * @note Available since #MHD_VERSION 0x00096000 3858 */ 3859 MHD_RF_HTTP_VERSION_1_0_RESPONSE = 1 << 1, 3860 3861 /** 3862 * Disable sanity check preventing clients from manually 3863 * setting the HTTP content length option. 3864 * Allow to set several "Content-Length" headers. These headers will 3865 * be used even with replies without body. 3866 * @note Available since #MHD_VERSION 0x00096702 3867 */ 3868 MHD_RF_INSANITY_HEADER_CONTENT_LENGTH = 1 << 2, 3869 3870 /** 3871 * Enable sending of "Connection: keep-alive" header even for 3872 * HTTP/1.1 clients when "Keep-Alive" connection is used. 3873 * Disabled by default for HTTP/1.1 clients as per RFC. 3874 * @note Available since #MHD_VERSION 0x00097310 3875 */ 3876 MHD_RF_SEND_KEEP_ALIVE_HEADER = 1 << 3, 3877 3878 /** 3879 * Enable special processing of the response as body-less (with undefined 3880 * body size). No automatic "Content-Length" or "Transfer-Encoding: chunked" 3881 * headers are added when the response is used with #MHD_HTTP_NOT_MODIFIED 3882 * code or to respond to HEAD request. 3883 * The flag also allow to set arbitrary "Content-Length" by 3884 * MHD_add_response_header() function. 3885 * This flag value can be used only with responses created without body 3886 * (zero-size body). 3887 * Responses with this flag enabled cannot be used in situations where 3888 * reply body must be sent to the client. 3889 * This flag is primarily intended to be used when automatic "Content-Length" 3890 * header is undesirable in response to HEAD requests. 3891 * @note Available since #MHD_VERSION 0x00097701 3892 */ 3893 MHD_RF_HEAD_ONLY_RESPONSE = 1 << 4 3894 } _MHD_FIXED_FLAGS_ENUM; 3895 3896 3897 /** 3898 * MHD options (for future extensions). 3899 */ 3900 enum MHD_ResponseOptions 3901 { 3902 /** 3903 * End of the list of options. 3904 */ 3905 MHD_RO_END = 0 3906 } _MHD_FIXED_ENUM; 3907 3908 3909 /** 3910 * Set special flags and options for a response. 3911 * 3912 * @param response the response to modify 3913 * @param flags to set for the response 3914 * @param ... #MHD_RO_END terminated list of options 3915 * @return #MHD_YES on success, #MHD_NO on error 3916 */ 3917 _MHD_EXTERN enum MHD_Result 3918 MHD_set_response_options (struct MHD_Response *response, 3919 enum MHD_ResponseFlags flags, 3920 ...); 3921 3922 3923 /** 3924 * Create a response object. 3925 * The response object can be extended with header information and then be used 3926 * any number of times. 3927 * 3928 * If response object is used to answer HEAD request then the body of the 3929 * response is not used, while all headers (including automatic headers) are 3930 * used. 3931 * 3932 * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown 3933 * @param block_size preferred block size for querying crc (advisory only, 3934 * MHD may still call @a crc using smaller chunks); this 3935 * is essentially the buffer size used for IO, clients 3936 * should pick a value that is appropriate for IO and 3937 * memory performance requirements 3938 * @param crc callback to use to obtain response data 3939 * @param crc_cls extra argument to @a crc 3940 * @param crfc callback to call to free @a crc_cls resources 3941 * @return NULL on error (i.e. invalid arguments, out of memory) 3942 * @ingroup response 3943 */ 3944 _MHD_EXTERN struct MHD_Response * 3945 MHD_create_response_from_callback (uint64_t size, 3946 size_t block_size, 3947 MHD_ContentReaderCallback crc, void *crc_cls, 3948 MHD_ContentReaderFreeCallback crfc); 3949 3950 3951 /** 3952 * Create a response object. 3953 * The response object can be extended with header information and then be used 3954 * any number of times. 3955 * 3956 * If response object is used to answer HEAD request then the body of the 3957 * response is not used, while all headers (including automatic headers) are 3958 * used. 3959 * 3960 * @param size size of the @a data portion of the response 3961 * @param data the data itself 3962 * @param must_free libmicrohttpd should free data when done 3963 * @param must_copy libmicrohttpd must make a copy of @a data 3964 * right away, the data may be released anytime after 3965 * this call returns 3966 * @return NULL on error (i.e. invalid arguments, out of memory) 3967 * @deprecated use #MHD_create_response_from_buffer instead 3968 * @ingroup response 3969 */ 3970 _MHD_DEPR_FUNC ( \ 3971 "MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()" \ 3972 ) \ 3973 _MHD_EXTERN struct MHD_Response * 3974 MHD_create_response_from_data (size_t size, 3975 void *data, 3976 int must_free, 3977 int must_copy); 3978 3979 3980 /** 3981 * Specification for how MHD should treat the memory buffer 3982 * given for the response. 3983 * @ingroup response 3984 */ 3985 enum MHD_ResponseMemoryMode 3986 { 3987 3988 /** 3989 * Buffer is a persistent (static/global) buffer that won't change 3990 * for at least the lifetime of the response, MHD should just use 3991 * it, not free it, not copy it, just keep an alias to it. 3992 * @ingroup response 3993 */ 3994 MHD_RESPMEM_PERSISTENT, 3995 3996 /** 3997 * Buffer is heap-allocated with `malloc()` (or equivalent) and 3998 * should be freed by MHD after processing the response has 3999 * concluded (response reference counter reaches zero). 4000 * The more portable way to automatically free the buffer is function 4001 * MHD_create_response_from_buffer_with_free_callback() with '&free' as 4002 * crfc parameter as it does not require to use the same runtime library. 4003 * @warning It is critical to make sure that the same C-runtime library 4004 * is used by both application and MHD (especially 4005 * important for W32). 4006 * @ingroup response 4007 */ 4008 MHD_RESPMEM_MUST_FREE, 4009 4010 /** 4011 * Buffer is in transient memory, but not on the heap (for example, 4012 * on the stack or non-`malloc()` allocated) and only valid during the 4013 * call to #MHD_create_response_from_buffer. MHD must make its 4014 * own private copy of the data for processing. 4015 * @ingroup response 4016 */ 4017 MHD_RESPMEM_MUST_COPY 4018 4019 } _MHD_FIXED_ENUM; 4020 4021 4022 /** 4023 * Create a response object with the content of provided buffer used as 4024 * the response body. 4025 * 4026 * The response object can be extended with header information and then 4027 * be used any number of times. 4028 * 4029 * If response object is used to answer HEAD request then the body 4030 * of the response is not used, while all headers (including automatic 4031 * headers) are used. 4032 * 4033 * @param size size of the data portion of the response 4034 * @param buffer size bytes containing the response's data portion 4035 * @param mode flags for buffer management 4036 * @return NULL on error (i.e. invalid arguments, out of memory) 4037 * @ingroup response 4038 */ 4039 _MHD_EXTERN struct MHD_Response * 4040 MHD_create_response_from_buffer (size_t size, 4041 void *buffer, 4042 enum MHD_ResponseMemoryMode mode); 4043 4044 4045 /** 4046 * Create a response object with the content of provided statically allocated 4047 * buffer used as the response body. 4048 * 4049 * The buffer must be valid for the lifetime of the response. The easiest way 4050 * to achieve this is to use a statically allocated buffer. 4051 * 4052 * The response object can be extended with header information and then 4053 * be used any number of times. 4054 * 4055 * If response object is used to answer HEAD request then the body 4056 * of the response is not used, while all headers (including automatic 4057 * headers) are used. 4058 * 4059 * @param size the size of the data in @a buffer, can be zero 4060 * @param buffer the buffer with the data for the response body, can be NULL 4061 * if @a size is zero 4062 * @return NULL on error (i.e. invalid arguments, out of memory) 4063 * @note Available since #MHD_VERSION 0x00097701 4064 * @ingroup response 4065 */ 4066 _MHD_EXTERN struct MHD_Response * 4067 MHD_create_response_from_buffer_static (size_t size, 4068 const void *buffer); 4069 4070 4071 /** 4072 * Create a response object with the content of provided temporal buffer 4073 * used as the response body. 4074 * 4075 * An internal copy of the buffer will be made automatically, so buffer have 4076 * to be valid only during the call of this function (as a typical example: 4077 * buffer is a local (non-static) array). 4078 * 4079 * The response object can be extended with header information and then 4080 * be used any number of times. 4081 * 4082 * If response object is used to answer HEAD request then the body 4083 * of the response is not used, while all headers (including automatic 4084 * headers) are used. 4085 * 4086 * @param size the size of the data in @a buffer, can be zero 4087 * @param buffer the buffer with the data for the response body, can be NULL 4088 * if @a size is zero 4089 * @return NULL on error (i.e. invalid arguments, out of memory) 4090 * @note Available since #MHD_VERSION 0x00097701 4091 * @ingroup response 4092 */ 4093 _MHD_EXTERN struct MHD_Response * 4094 MHD_create_response_from_buffer_copy (size_t size, 4095 const void *buffer); 4096 4097 4098 /** 4099 * Create a response object with the content of provided buffer used as 4100 * the response body. 4101 * 4102 * The response object can be extended with header information and then 4103 * be used any number of times. 4104 * 4105 * If response object is used to answer HEAD request then the body 4106 * of the response is not used, while all headers (including automatic 4107 * headers) are used. 4108 * 4109 * @param size size of the data portion of the response 4110 * @param buffer size bytes containing the response's data portion 4111 * @param crfc function to call to free the @a buffer 4112 * @return NULL on error (i.e. invalid arguments, out of memory) 4113 * @note Available since #MHD_VERSION 0x00096000 4114 * @ingroup response 4115 */ 4116 _MHD_EXTERN struct MHD_Response * 4117 MHD_create_response_from_buffer_with_free_callback (size_t size, 4118 void *buffer, 4119 MHD_ContentReaderFreeCallback 4120 crfc); 4121 4122 4123 /** 4124 * Create a response object with the content of provided buffer used as 4125 * the response body. 4126 * 4127 * The response object can be extended with header information and then 4128 * be used any number of times. 4129 * 4130 * If response object is used to answer HEAD request then the body 4131 * of the response is not used, while all headers (including automatic 4132 * headers) are used. 4133 * 4134 * @param size size of the data portion of the response 4135 * @param buffer size bytes containing the response's data portion 4136 * @param crfc function to call to cleanup, if set to NULL then callback 4137 * is not called 4138 * @param crfc_cls an argument for @a crfc 4139 * @return NULL on error (i.e. invalid arguments, out of memory) 4140 * @note Available since #MHD_VERSION 0x00097302 4141 * @note 'const' qualifier is used for @a buffer since #MHD_VERSION 0x00097701 4142 * @ingroup response 4143 */ 4144 _MHD_EXTERN struct MHD_Response * 4145 MHD_create_response_from_buffer_with_free_callback_cls (size_t size, 4146 const void *buffer, 4147 MHD_ContentReaderFreeCallback 4148 crfc, 4149 void *crfc_cls); 4150 4151 4152 /** 4153 * Create a response object with the content of provided file used as 4154 * the response body. 4155 * 4156 * The response object can be extended with header information and then 4157 * be used any number of times. 4158 * 4159 * If response object is used to answer HEAD request then the body 4160 * of the response is not used, while all headers (including automatic 4161 * headers) are used. 4162 * 4163 * @param size size of the data portion of the response 4164 * @param fd file descriptor referring to a file on disk with the 4165 * data; will be closed when response is destroyed; 4166 * fd should be in 'blocking' mode 4167 * @return NULL on error (i.e. invalid arguments, out of memory) 4168 * @ingroup response 4169 */ 4170 _MHD_EXTERN struct MHD_Response * 4171 MHD_create_response_from_fd (size_t size, 4172 int fd); 4173 4174 4175 /** 4176 * Create a response object with the response body created by reading 4177 * the provided pipe. 4178 * 4179 * The response object can be extended with header information and 4180 * then be used ONLY ONCE. 4181 * 4182 * If response object is used to answer HEAD request then the body 4183 * of the response is not used, while all headers (including automatic 4184 * headers) are used. 4185 * 4186 * @param fd file descriptor referring to a read-end of a pipe with the 4187 * data; will be closed when response is destroyed; 4188 * fd should be in 'blocking' mode 4189 * @return NULL on error (i.e. invalid arguments, out of memory) 4190 * @note Available since #MHD_VERSION 0x00097102 4191 * @ingroup response 4192 */ 4193 _MHD_EXTERN struct MHD_Response * 4194 MHD_create_response_from_pipe (int fd); 4195 4196 4197 /** 4198 * Create a response object with the content of provided file used as 4199 * the response body. 4200 * 4201 * The response object can be extended with header information and then 4202 * be used any number of times. 4203 * 4204 * If response object is used to answer HEAD request then the body 4205 * of the response is not used, while all headers (including automatic 4206 * headers) are used. 4207 * 4208 * @param size size of the data portion of the response; 4209 * sizes larger than 2 GiB may be not supported by OS or 4210 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4211 * @param fd file descriptor referring to a file on disk with the 4212 * data; will be closed when response is destroyed; 4213 * fd should be in 'blocking' mode 4214 * @return NULL on error (i.e. invalid arguments, out of memory) 4215 * @ingroup response 4216 */ 4217 _MHD_EXTERN struct MHD_Response * 4218 MHD_create_response_from_fd64 (uint64_t size, 4219 int fd); 4220 4221 4222 /** 4223 * Create a response object with the content of provided file with 4224 * specified offset used as the response body. 4225 * 4226 * The response object can be extended with header information and then 4227 * be used any number of times. 4228 * 4229 * If response object is used to answer HEAD request then the body 4230 * of the response is not used, while all headers (including automatic 4231 * headers) are used. 4232 * 4233 * @param size size of the data portion of the response 4234 * @param fd file descriptor referring to a file on disk with the 4235 * data; will be closed when response is destroyed; 4236 * fd should be in 'blocking' mode 4237 * @param offset offset to start reading from in the file; 4238 * Be careful! `off_t` may have been compiled to be a 4239 * 64-bit variable for MHD, in which case your application 4240 * also has to be compiled using the same options! Read 4241 * the MHD manual for more details. 4242 * @return NULL on error (i.e. invalid arguments, out of memory) 4243 * @ingroup response 4244 */ 4245 _MHD_DEPR_FUNC ( \ 4246 "Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()" \ 4247 ) \ 4248 _MHD_EXTERN struct MHD_Response * 4249 MHD_create_response_from_fd_at_offset (size_t size, 4250 int fd, 4251 off_t offset); 4252 4253 #if ! defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) 4254 /* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() 4255 to minimize potential problems with different off_t sizes */ 4256 #define MHD_create_response_from_fd_at_offset(size,fd,offset) \ 4257 _MHD_DEPR_IN_MACRO ( \ 4258 "Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ 4259 MHD_create_response_from_fd_at_offset64 ((size),(fd),(offset)) 4260 #endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ 4261 4262 4263 /** 4264 * Create a response object with the content of provided file with 4265 * specified offset used as the response body. 4266 * 4267 * The response object can be extended with header information and then 4268 * be used any number of times. 4269 * 4270 * If response object is used to answer HEAD request then the body 4271 * of the response is not used, while all headers (including automatic 4272 * headers) are used. 4273 * 4274 * @param size size of the data portion of the response; 4275 * sizes larger than 2 GiB may be not supported by OS or 4276 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4277 * @param fd file descriptor referring to a file on disk with the 4278 * data; will be closed when response is destroyed; 4279 * fd should be in 'blocking' mode 4280 * @param offset offset to start reading from in the file; 4281 * reading file beyond 2 GiB may be not supported by OS or 4282 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4283 * @return NULL on error (i.e. invalid arguments, out of memory) 4284 * @ingroup response 4285 */ 4286 _MHD_EXTERN struct MHD_Response * 4287 MHD_create_response_from_fd_at_offset64 (uint64_t size, 4288 int fd, 4289 uint64_t offset); 4290 4291 4292 /** 4293 * Create a response object with an array of memory buffers 4294 * used as the response body. 4295 * 4296 * The response object can be extended with header information and then 4297 * be used any number of times. 4298 * 4299 * If response object is used to answer HEAD request then the body 4300 * of the response is not used, while all headers (including automatic 4301 * headers) are used. 4302 * 4303 * @param iov the array for response data buffers, an internal copy of this 4304 * will be made 4305 * @param iovcnt the number of elements in @a iov 4306 * @param free_cb the callback to clean up any data associated with @a iov when 4307 * the response is destroyed. 4308 * @param cls the argument passed to @a free_cb 4309 * @return NULL on error (i.e. invalid arguments, out of memory) 4310 * @note Available since #MHD_VERSION 0x00097204 4311 * @ingroup response 4312 */ 4313 _MHD_EXTERN struct MHD_Response * 4314 MHD_create_response_from_iovec (const struct MHD_IoVec *iov, 4315 unsigned int iovcnt, 4316 MHD_ContentReaderFreeCallback free_cb, 4317 void *cls); 4318 4319 4320 /** 4321 * Create a response object with empty (zero size) body. 4322 * 4323 * The response object can be extended with header information and then be used 4324 * any number of times. 4325 * 4326 * This function is a faster equivalent of #MHD_create_response_from_buffer call 4327 * with zero size combined with call of #MHD_set_response_options. 4328 * 4329 * @param flags the flags for the new response object 4330 * @return NULL on error (i.e. invalid arguments, out of memory), 4331 * the pointer to the created response object otherwise 4332 * @note Available since #MHD_VERSION 0x00097701 4333 * @ingroup response 4334 */ 4335 _MHD_EXTERN struct MHD_Response * 4336 MHD_create_response_empty (enum MHD_ResponseFlags flags); 4337 4338 4339 /** 4340 * Enumeration for actions MHD should perform on the underlying socket 4341 * of the upgrade. This API is not finalized, and in particular 4342 * the final set of actions is yet to be decided. This is just an 4343 * idea for what we might want. 4344 */ 4345 enum MHD_UpgradeAction 4346 { 4347 4348 /** 4349 * Close the socket, the application is done with it. 4350 * 4351 * Takes no extra arguments. 4352 */ 4353 MHD_UPGRADE_ACTION_CLOSE = 0, 4354 4355 /** 4356 * Enable CORKing on the underlying socket. 4357 */ 4358 MHD_UPGRADE_ACTION_CORK_ON = 1, 4359 4360 /** 4361 * Disable CORKing on the underlying socket. 4362 */ 4363 MHD_UPGRADE_ACTION_CORK_OFF = 2 4364 4365 } _MHD_FIXED_ENUM; 4366 4367 4368 /** 4369 * Handle given to the application to manage special 4370 * actions relating to MHD responses that "upgrade" 4371 * the HTTP protocol (i.e. to WebSockets). 4372 */ 4373 struct MHD_UpgradeResponseHandle; 4374 4375 4376 /** 4377 * This connection-specific callback is provided by MHD to 4378 * applications (unusual) during the #MHD_UpgradeHandler. 4379 * It allows applications to perform 'special' actions on 4380 * the underlying socket from the upgrade. 4381 * 4382 * @param urh the handle identifying the connection to perform 4383 * the upgrade @a action on. 4384 * @param action which action should be performed 4385 * @param ... arguments to the action (depends on the action) 4386 * @return #MHD_NO on error, #MHD_YES on success 4387 */ 4388 _MHD_EXTERN enum MHD_Result 4389 MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, 4390 enum MHD_UpgradeAction action, 4391 ...); 4392 4393 4394 /** 4395 * Function called after a protocol "upgrade" response was sent 4396 * successfully and the socket should now be controlled by some 4397 * protocol other than HTTP. 4398 * 4399 * Any data already received on the socket will be made available in 4400 * @e extra_in. This can happen if the application sent extra data 4401 * before MHD send the upgrade response. The application should 4402 * treat data from @a extra_in as if it had read it from the socket. 4403 * 4404 * Note that the application must not close() @a sock directly, 4405 * but instead use #MHD_upgrade_action() for special operations 4406 * on @a sock. 4407 * 4408 * Data forwarding to "upgraded" @a sock will be started as soon 4409 * as this function return. 4410 * 4411 * Except when in 'thread-per-connection' mode, implementations 4412 * of this function should never block (as it will still be called 4413 * from within the main event loop). 4414 * 4415 * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). 4416 * @param connection original HTTP connection handle, 4417 * giving the function a last chance 4418 * to inspect the original HTTP request 4419 * @param req_cls last value left in `req_cls` of the `MHD_AccessHandlerCallback` 4420 * @param extra_in if we happened to have read bytes after the 4421 * HTTP header already (because the client sent 4422 * more than the HTTP header of the request before 4423 * we sent the upgrade response), 4424 * these are the extra bytes already read from @a sock 4425 * by MHD. The application should treat these as if 4426 * it had read them from @a sock. 4427 * @param extra_in_size number of bytes in @a extra_in 4428 * @param sock socket to use for bi-directional communication 4429 * with the client. For HTTPS, this may not be a socket 4430 * that is directly connected to the client and thus certain 4431 * operations (TCP-specific setsockopt(), getsockopt(), etc.) 4432 * may not work as expected (as the socket could be from a 4433 * socketpair() or a TCP-loopback). The application is expected 4434 * to perform read()/recv() and write()/send() calls on the socket. 4435 * The application may also call shutdown(), but must not call 4436 * close() directly. 4437 * @param urh argument for #MHD_upgrade_action()s on this @a connection. 4438 * Applications must eventually use this callback to (indirectly) 4439 * perform the close() action on the @a sock. 4440 */ 4441 typedef void 4442 (*MHD_UpgradeHandler)(void *cls, 4443 struct MHD_Connection *connection, 4444 void *req_cls, 4445 const char *extra_in, 4446 size_t extra_in_size, 4447 MHD_socket sock, 4448 struct MHD_UpgradeResponseHandle *urh); 4449 4450 4451 /** 4452 * Create a response object that can be used for 101 UPGRADE 4453 * responses, for example to implement WebSockets. After sending the 4454 * response, control over the data stream is given to the callback (which 4455 * can then, for example, start some bi-directional communication). 4456 * If the response is queued for multiple connections, the callback 4457 * will be called for each connection. The callback 4458 * will ONLY be called after the response header was successfully passed 4459 * to the OS; if there are communication errors before, the usual MHD 4460 * connection error handling code will be performed. 4461 * 4462 * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) 4463 * and setting correct HTTP headers for the upgrade must be done 4464 * manually (this way, it is possible to implement most existing 4465 * WebSocket versions using this API; in fact, this API might be useful 4466 * for any protocol switch, not just WebSockets). Note that 4467 * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this 4468 * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" 4469 * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 4470 * Switching Protocols" (if the response code 101 is used). 4471 * 4472 * As usual, the response object can be extended with header 4473 * information and then be used any number of times (as long as the 4474 * header information is not connection-specific). 4475 * 4476 * @param upgrade_handler function to call with the "upgraded" socket 4477 * @param upgrade_handler_cls closure for @a upgrade_handler 4478 * @return NULL on error (i.e. invalid arguments, out of memory) 4479 */ 4480 _MHD_EXTERN struct MHD_Response * 4481 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, 4482 void *upgrade_handler_cls); 4483 4484 4485 /** 4486 * Destroy a response object and associated resources. Note that 4487 * libmicrohttpd may keep some of the resources around if the response 4488 * is still in the queue for some clients, so the memory may not 4489 * necessarily be freed immediately. 4490 * 4491 * @param response response to destroy 4492 * @ingroup response 4493 */ 4494 _MHD_EXTERN void 4495 MHD_destroy_response (struct MHD_Response *response); 4496 4497 4498 /** 4499 * Add a header line to the response. 4500 * 4501 * When reply is generated with queued response, some headers are generated 4502 * automatically. Automatically generated headers are only sent to the client, 4503 * but not added back to the response object. 4504 * 4505 * The list of automatic headers: 4506 * + "Date" header is added automatically unless already set by 4507 * this function 4508 * @see #MHD_USE_SUPPRESS_DATE_NO_CLOCK 4509 * + "Content-Length" is added automatically when required, attempt to set 4510 * it manually by this function is ignored. 4511 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4512 * + "Transfer-Encoding" with value "chunked" is added automatically, 4513 * when chunked transfer encoding is used automatically. Same header with 4514 * the same value can be set manually by this function to enforce chunked 4515 * encoding, however for HTTP/1.0 clients chunked encoding will not be used 4516 * and manually set "Transfer-Encoding" header is automatically removed 4517 * for HTTP/1.0 clients 4518 * + "Connection" may be added automatically with value "Keep-Alive" (only 4519 * for HTTP/1.0 clients) or "Close". The header "Connection" with value 4520 * "Close" could be set by this function to enforce closure of 4521 * the connection after sending this response. "Keep-Alive" cannot be 4522 * enforced and will be removed automatically. 4523 * @see #MHD_RF_SEND_KEEP_ALIVE_HEADER 4524 * 4525 * Some headers are pre-processed by this function: 4526 * * "Connection" headers are combined into single header entry, value is 4527 * normilised, "Keep-Alive" tokens are removed. 4528 * * "Transfer-Encoding" header: the only one header is allowed, the only 4529 * allowed value is "chunked". 4530 * * "Date" header: the only one header is allowed, the second added header 4531 * replaces the first one. 4532 * * "Content-Length" application-defined header is not allowed. 4533 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4534 * 4535 * Headers are used in order as they were added. 4536 * 4537 * @param response the response to add a header to 4538 * @param header the header name to add, no need to be static, an internal copy 4539 * will be created automatically 4540 * @param content the header value to add, no need to be static, an internal 4541 * copy will be created automatically 4542 * @return #MHD_YES on success, 4543 * #MHD_NO on error (i.e. invalid header or content format), 4544 * or out of memory 4545 * @ingroup response 4546 */ 4547 _MHD_EXTERN enum MHD_Result 4548 MHD_add_response_header (struct MHD_Response *response, 4549 const char *header, 4550 const char *content); 4551 4552 4553 /** 4554 * Add a footer line to the response. 4555 * 4556 * @param response response to remove a header from 4557 * @param footer the footer to delete 4558 * @param content value to delete 4559 * @return #MHD_NO on error (i.e. invalid footer or content format). 4560 * @ingroup response 4561 */ 4562 _MHD_EXTERN enum MHD_Result 4563 MHD_add_response_footer (struct MHD_Response *response, 4564 const char *footer, 4565 const char *content); 4566 4567 4568 /** 4569 * Delete a header (or footer) line from the response. 4570 * 4571 * For "Connection" headers this function remove all tokens from existing 4572 * value. Successful result means that at least one token has been removed. 4573 * If all tokens are removed from "Connection" header, the empty "Connection" 4574 * header removed. 4575 * 4576 * @param response response to remove a header from 4577 * @param header the header to delete 4578 * @param content value to delete 4579 * @return #MHD_NO on error (no such header known) 4580 * @ingroup response 4581 */ 4582 _MHD_EXTERN enum MHD_Result 4583 MHD_del_response_header (struct MHD_Response *response, 4584 const char *header, 4585 const char *content); 4586 4587 4588 /** 4589 * Get all of the headers (and footers) added to a response. 4590 * 4591 * @param response response to query 4592 * @param iterator callback to call on each header; 4593 * may be NULL (then just count headers) 4594 * @param iterator_cls extra argument to @a iterator 4595 * @return number of entries iterated over 4596 * @ingroup response 4597 */ 4598 _MHD_EXTERN int 4599 MHD_get_response_headers (struct MHD_Response *response, 4600 MHD_KeyValueIterator iterator, 4601 void *iterator_cls); 4602 4603 4604 /** 4605 * Get a particular header (or footer) from the response. 4606 * 4607 * @param response response to query 4608 * @param key which header to get 4609 * @return NULL if header does not exist 4610 * @ingroup response 4611 */ 4612 _MHD_EXTERN const char * 4613 MHD_get_response_header (struct MHD_Response *response, 4614 const char *key); 4615 4616 4617 /* ********************** PostProcessor functions ********************** */ 4618 4619 /** 4620 * Create a `struct MHD_PostProcessor`. 4621 * 4622 * A `struct MHD_PostProcessor` can be used to (incrementally) parse 4623 * the data portion of a POST request. Note that some buggy browsers 4624 * fail to set the encoding type. If you want to support those, you 4625 * may have to call #MHD_set_connection_value with the proper encoding 4626 * type before creating a post processor (if no supported encoding 4627 * type is set, this function will fail). 4628 * 4629 * @param connection the connection on which the POST is 4630 * happening (used to determine the POST format) 4631 * @param buffer_size maximum number of bytes to use for 4632 * internal buffering (used only for the parsing, 4633 * specifically the parsing of the keys). A 4634 * tiny value (256-1024) should be sufficient. 4635 * Do NOT use a value smaller than 256. For good 4636 * performance, use 32 or 64k (i.e. 65536). 4637 * @param iter iterator to be called with the parsed data, 4638 * Must NOT be NULL. 4639 * @param iter_cls first argument to @a iter 4640 * @return NULL on error (out of memory, unsupported encoding), 4641 * otherwise a PP handle 4642 * @ingroup request 4643 */ 4644 _MHD_EXTERN struct MHD_PostProcessor * 4645 MHD_create_post_processor (struct MHD_Connection *connection, 4646 size_t buffer_size, 4647 MHD_PostDataIterator iter, void *iter_cls); 4648 4649 4650 /** 4651 * Parse and process POST data. Call this function when POST data is 4652 * available (usually during an #MHD_AccessHandlerCallback) with the 4653 * "upload_data" and "upload_data_size". Whenever possible, this will 4654 * then cause calls to the #MHD_PostDataIterator. 4655 * 4656 * @param pp the post processor 4657 * @param post_data @a post_data_len bytes of POST data 4658 * @param post_data_len length of @a post_data 4659 * @return #MHD_YES on success, #MHD_NO on error 4660 * (out-of-memory, iterator aborted, parse error) 4661 * @ingroup request 4662 */ 4663 _MHD_EXTERN enum MHD_Result 4664 MHD_post_process (struct MHD_PostProcessor *pp, 4665 const char *post_data, 4666 size_t post_data_len); 4667 4668 4669 /** 4670 * Release PostProcessor resources. 4671 * 4672 * @param pp the PostProcessor to destroy 4673 * @return #MHD_YES if processing completed nicely, 4674 * #MHD_NO if there were spurious characters / formatting 4675 * problems; it is common to ignore the return 4676 * value of this function 4677 * @ingroup request 4678 */ 4679 _MHD_EXTERN enum MHD_Result 4680 MHD_destroy_post_processor (struct MHD_PostProcessor *pp); 4681 4682 4683 /* ********************* Digest Authentication functions *************** */ 4684 4685 4686 /** 4687 * Length of the binary output of the MD5 hash function. 4688 * @sa #MHD_digest_get_hash_size() 4689 * @ingroup authentication 4690 */ 4691 #define MHD_MD5_DIGEST_SIZE 16 4692 4693 /** 4694 * Length of the binary output of the SHA-256 hash function. 4695 * @sa #MHD_digest_get_hash_size() 4696 * @ingroup authentication 4697 */ 4698 #define MHD_SHA256_DIGEST_SIZE 32 4699 4700 /** 4701 * Length of the binary output of the SHA-512/256 hash function. 4702 * @warning While this value is the same as the #MHD_SHA256_DIGEST_SIZE, 4703 * the calculated digests for SHA-256 and SHA-512/256 are different. 4704 * @sa #MHD_digest_get_hash_size() 4705 * @note Available since #MHD_VERSION 0x00097701 4706 * @ingroup authentication 4707 */ 4708 #define MHD_SHA512_256_DIGEST_SIZE 32 4709 4710 /** 4711 * Base type of hash calculation. 4712 * Used as part of #MHD_DigestAuthAlgo3 values. 4713 * 4714 * @warning Not used directly by MHD API. 4715 * @note Available since #MHD_VERSION 0x00097701 4716 */ 4717 enum MHD_DigestBaseAlgo 4718 { 4719 /** 4720 * Invalid hash algorithm value 4721 */ 4722 MHD_DIGEST_BASE_ALGO_INVALID = 0, 4723 4724 /** 4725 * MD5 hash algorithm. 4726 * As specified by RFC1321 4727 */ 4728 MHD_DIGEST_BASE_ALGO_MD5 = (1 << 0), 4729 4730 /** 4731 * SHA-256 hash algorithm. 4732 * As specified by FIPS PUB 180-4 4733 */ 4734 MHD_DIGEST_BASE_ALGO_SHA256 = (1 << 1), 4735 4736 /** 4737 * SHA-512/256 hash algorithm. 4738 * As specified by FIPS PUB 180-4 4739 */ 4740 MHD_DIGEST_BASE_ALGO_SHA512_256 = (1 << 2) 4741 } _MHD_FIXED_FLAGS_ENUM; 4742 4743 /** 4744 * The flag indicating non-session algorithm types, 4745 * like 'MD5', 'SHA-256' or 'SHA-512-256'. 4746 * @note Available since #MHD_VERSION 0x00097701 4747 */ 4748 #define MHD_DIGEST_AUTH_ALGO3_NON_SESSION (1 << 6) 4749 4750 /** 4751 * The flag indicating session algorithm types, 4752 * like 'MD5-sess', 'SHA-256-sess' or 'SHA-512-256-sess'. 4753 * @note Available since #MHD_VERSION 0x00097701 4754 */ 4755 #define MHD_DIGEST_AUTH_ALGO3_SESSION (1 << 7) 4756 4757 /** 4758 * Digest algorithm identification 4759 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 4760 * which uses other values! 4761 * @note Available since #MHD_VERSION 0x00097701 4762 */ 4763 enum MHD_DigestAuthAlgo3 4764 { 4765 /** 4766 * Unknown or wrong algorithm type. 4767 * Used in struct MHD_DigestAuthInfo to indicate client value that 4768 * cannot by identified. 4769 */ 4770 MHD_DIGEST_AUTH_ALGO3_INVALID = 0, 4771 4772 /** 4773 * The 'MD5' algorithm, non-session version. 4774 */ 4775 MHD_DIGEST_AUTH_ALGO3_MD5 = 4776 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4777 4778 /** 4779 * The 'MD5-sess' algorithm. 4780 * Not supported by MHD for authentication. 4781 */ 4782 MHD_DIGEST_AUTH_ALGO3_MD5_SESSION = 4783 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4784 4785 /** 4786 * The 'SHA-256' algorithm, non-session version. 4787 */ 4788 MHD_DIGEST_AUTH_ALGO3_SHA256 = 4789 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4790 4791 /** 4792 * The 'SHA-256-sess' algorithm. 4793 * Not supported by MHD for authentication. 4794 */ 4795 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION = 4796 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4797 4798 /** 4799 * The 'SHA-512-256' (SHA-512/256) algorithm. 4800 */ 4801 MHD_DIGEST_AUTH_ALGO3_SHA512_256 = 4802 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4803 4804 /** 4805 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4806 * Not supported by MHD for authentication. 4807 */ 4808 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION = 4809 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_SESSION 4810 }; 4811 4812 4813 /** 4814 * Get digest size for specified algorithm. 4815 * 4816 * The size of the digest specifies the size of the userhash, userdigest 4817 * and other parameters which size depends on used hash algorithm. 4818 * @param algo3 the algorithm to check 4819 * @return the size of the digest (either #MHD_MD5_DIGEST_SIZE or 4820 * #MHD_SHA256_DIGEST_SIZE/MHD_SHA512_256_DIGEST_SIZE) 4821 * or zero if the input value is not supported or not valid 4822 * @sa #MHD_digest_auth_calc_userdigest() 4823 * @sa #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_calc_userhash_hex() 4824 * @note Available since #MHD_VERSION 0x00097701 4825 * @ingroup authentication 4826 */ 4827 _MHD_EXTERN size_t 4828 MHD_digest_get_hash_size (enum MHD_DigestAuthAlgo3 algo3); 4829 4830 /** 4831 * Digest algorithm identification, allow multiple selection. 4832 * 4833 * #MHD_DigestAuthAlgo3 always can be casted to #MHD_DigestAuthMultiAlgo3, but 4834 * not vice versa. 4835 * 4836 * @note Available since #MHD_VERSION 0x00097701 4837 */ 4838 enum MHD_DigestAuthMultiAlgo3 4839 { 4840 /** 4841 * Unknown or wrong algorithm type. 4842 */ 4843 MHD_DIGEST_AUTH_MULT_ALGO3_INVALID = MHD_DIGEST_AUTH_ALGO3_INVALID, 4844 4845 /** 4846 * The 'MD5' algorithm, non-session version. 4847 */ 4848 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 = MHD_DIGEST_AUTH_ALGO3_MD5, 4849 4850 /** 4851 * The 'MD5-sess' algorithm. 4852 * Not supported by MHD for authentication. 4853 * Reserved value. 4854 */ 4855 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION = MHD_DIGEST_AUTH_ALGO3_MD5_SESSION, 4856 4857 /** 4858 * The 'SHA-256' algorithm, non-session version. 4859 */ 4860 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 = MHD_DIGEST_AUTH_ALGO3_SHA256, 4861 4862 /** 4863 * The 'SHA-256-sess' algorithm. 4864 * Not supported by MHD for authentication. 4865 * Reserved value. 4866 */ 4867 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION = 4868 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION, 4869 4870 /** 4871 * The 'SHA-512-256' (SHA-512/256) algorithm, non-session version. 4872 */ 4873 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 = MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4874 4875 /** 4876 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4877 * Not supported by MHD for authentication. 4878 * Reserved value. 4879 */ 4880 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION = 4881 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4882 4883 /** 4884 * SHA-256 or SHA-512/256 non-session algorithm, MHD will choose 4885 * the preferred or the matching one. 4886 */ 4887 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION = 4888 MHD_DIGEST_AUTH_ALGO3_SHA256 | MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4889 4890 /** 4891 * Any non-session algorithm, MHD will choose the preferred or 4892 * the matching one. 4893 */ 4894 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_NON_SESSION = 4895 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4896 4897 /** 4898 * The SHA-256 or SHA-512/256 session algorithm. 4899 * Not supported by MHD. 4900 * Reserved value. 4901 */ 4902 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION = 4903 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION 4904 | MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4905 4906 /** 4907 * Any session algorithm. 4908 * Not supported by MHD. 4909 * Reserved value. 4910 */ 4911 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_SESSION = 4912 (0x3F) | MHD_DIGEST_AUTH_ALGO3_SESSION, 4913 4914 /** 4915 * The MD5 algorithm, session or non-session. 4916 * Currently supported as non-session only. 4917 */ 4918 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_ANY = 4919 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 | MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION, 4920 4921 /** 4922 * The SHA-256 algorithm, session or non-session. 4923 * Currently supported as non-session only. 4924 */ 4925 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_ANY = 4926 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 4927 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION, 4928 4929 /** 4930 * The SHA-512/256 algorithm, session or non-session. 4931 * Currently supported as non-session only. 4932 */ 4933 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_ANY = 4934 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 4935 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION, 4936 4937 /** 4938 * The SHA-256 or SHA-512/256 algorithm, session or non-session. 4939 * Currently supported as non-session only. 4940 */ 4941 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_ANY = 4942 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION 4943 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION, 4944 4945 /** 4946 * Any algorithm, MHD will choose the preferred or the matching one. 4947 */ 4948 MHD_DIGEST_AUTH_MULT_ALGO3_ANY = 4949 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION | MHD_DIGEST_AUTH_ALGO3_SESSION 4950 }; 4951 4952 4953 /** 4954 * Calculate "userhash", return it as binary data. 4955 * 4956 * The "userhash" is the hash of the string "username:realm". 4957 * 4958 * The "userhash" could be used to avoid sending username in cleartext in Digest 4959 * Authorization client's header. 4960 * 4961 * Userhash is not designed to hide the username in local database or files, 4962 * as username in cleartext is required for #MHD_digest_auth_check3() function 4963 * to check the response, but it can be used to hide username in HTTP headers. 4964 * 4965 * This function could be used when the new username is added to the username 4966 * database to save the "userhash" alongside with the username (preferably) or 4967 * when loading list of the usernames to generate the userhash for every loaded 4968 * username (this will cause delays at the start with the long lists). 4969 * 4970 * Once "userhash" is generated it could be used to identify users by clients 4971 * with "userhash" support. 4972 * Avoid repetitive usage of this function for the same username/realm 4973 * combination as it will cause excessive CPU load; save and re-use the result 4974 * instead. 4975 * 4976 * @param algo3 the algorithm for userhash calculations 4977 * @param username the username 4978 * @param realm the realm 4979 * @param[out] userhash_bin the output buffer for userhash as binary data; 4980 * if this function succeeds, then this buffer has 4981 * #MHD_digest_get_hash_size(algo3) bytes of userhash 4982 * upon return 4983 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 4984 * at least #MHD_digest_get_hash_size(algo3) bytes long 4985 * @return MHD_YES on success, 4986 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 4987 * not supported (or external error has occurred, 4988 * see #MHD_FEATURE_EXTERN_HASH) 4989 * @sa #MHD_digest_auth_calc_userhash_hex() 4990 * @note Available since #MHD_VERSION 0x00097701 4991 * @ingroup authentication 4992 */ 4993 _MHD_EXTERN enum MHD_Result 4994 MHD_digest_auth_calc_userhash (enum MHD_DigestAuthAlgo3 algo3, 4995 const char *username, 4996 const char *realm, 4997 void *userhash_bin, 4998 size_t bin_buf_size); 4999 5000 5001 /** 5002 * Calculate "userhash", return it as hexadecimal string. 5003 * 5004 * The "userhash" is the hash of the string "username:realm". 5005 * 5006 * The "userhash" could be used to avoid sending username in cleartext in Digest 5007 * Authorization client's header. 5008 * 5009 * Userhash is not designed to hide the username in local database or files, 5010 * as username in cleartext is required for #MHD_digest_auth_check3() function 5011 * to check the response, but it can be used to hide username in HTTP headers. 5012 * 5013 * This function could be used when the new username is added to the username 5014 * database to save the "userhash" alongside with the username (preferably) or 5015 * when loading list of the usernames to generate the userhash for every loaded 5016 * username (this will cause delays at the start with the long lists). 5017 * 5018 * Once "userhash" is generated it could be used to identify users by clients 5019 * with "userhash" support. 5020 * Avoid repetitive usage of this function for the same username/realm 5021 * combination as it will cause excessive CPU load; save and re-use the result 5022 * instead. 5023 * 5024 * @param algo3 the algorithm for userhash calculations 5025 * @param username the username 5026 * @param realm the realm 5027 * @param[out] userhash_hex the output buffer for userhash as hex string; 5028 * if this function succeeds, then this buffer has 5029 * #MHD_digest_get_hash_size(algo3)*2 chars long 5030 * userhash zero-terminated string 5031 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 5032 * at least #MHD_digest_get_hash_size(algo3)*2+1 chars long 5033 * @return MHD_YES on success, 5034 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 5035 * not supported (or external error has occurred, 5036 * see #MHD_FEATURE_EXTERN_HASH). 5037 * @sa #MHD_digest_auth_calc_userhash() 5038 * @note Available since #MHD_VERSION 0x00097701 5039 * @ingroup authentication 5040 */ 5041 _MHD_EXTERN enum MHD_Result 5042 MHD_digest_auth_calc_userhash_hex (enum MHD_DigestAuthAlgo3 algo3, 5043 const char *username, 5044 const char *realm, 5045 char *userhash_hex, 5046 size_t hex_buf_size); 5047 5048 5049 /** 5050 * The type of username used by client in Digest Authorization header 5051 * 5052 * Values are sorted so simplified checks could be used. 5053 * For example: 5054 * * (value <= MHD_DIGEST_AUTH_UNAME_TYPE_INVALID) is true if no valid username 5055 * is provided by the client 5056 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH) is true if username is 5057 * provided in any form 5058 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD) is true if username is 5059 * provided in clear text (no userhash matching is needed) 5060 * 5061 * @note Available since #MHD_VERSION 0x00097701 5062 */ 5063 enum MHD_DigestAuthUsernameType 5064 { 5065 /** 5066 * No username parameter in in Digest Authorization header. 5067 * This should be treated as an error. 5068 */ 5069 MHD_DIGEST_AUTH_UNAME_TYPE_MISSING = 0, 5070 5071 /** 5072 * The 'username' parameter is used to specify the username. 5073 */ 5074 MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD = (1 << 2), 5075 5076 /** 5077 * The username is specified by 'username*' parameter with 5078 * the extended notation (see RFC 5987 #section-3.2.1). 5079 * The only difference between standard and extended types is 5080 * the way how username value is encoded in the header. 5081 */ 5082 MHD_DIGEST_AUTH_UNAME_TYPE_EXTENDED = (1 << 3), 5083 5084 /** 5085 * The username provided in form of 'userhash' as 5086 * specified by RFC 7616 #section-3.4.4. 5087 * @sa #MHD_digest_auth_calc_userhash_hex(), #MHD_digest_auth_calc_userhash() 5088 */ 5089 MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH = (1 << 1), 5090 5091 /** 5092 * The invalid combination of username parameters are used by client. 5093 * Either: 5094 * * both 'username' and 'username*' are used 5095 * * 'username*' is used with 'userhash=true' 5096 * * 'username*' used with invalid extended notation 5097 * * 'username' is not hexadecimal string, while 'userhash' set to 'true' 5098 */ 5099 MHD_DIGEST_AUTH_UNAME_TYPE_INVALID = (1 << 0) 5100 } _MHD_FIXED_ENUM; 5101 5102 /** 5103 * The QOP ('quality of protection') types. 5104 * @note Available since #MHD_VERSION 0x00097701 5105 */ 5106 enum MHD_DigestAuthQOP 5107 { 5108 /** 5109 * Invalid/unknown QOP. 5110 * Used in struct MHD_DigestAuthInfo to indicate client value that 5111 * cannot by identified. 5112 */ 5113 MHD_DIGEST_AUTH_QOP_INVALID = 0, 5114 5115 /** 5116 * No QOP parameter. 5117 * As described in old RFC 2069 original specification. 5118 * This mode is not allowed by latest RFCs and should be used only to 5119 * communicate with clients that do not support more modern modes (with QOP 5120 * parameter). 5121 * This mode is less secure than other modes and inefficient. 5122 */ 5123 MHD_DIGEST_AUTH_QOP_NONE = 1 << 0, 5124 5125 /** 5126 * The 'auth' QOP type. 5127 */ 5128 MHD_DIGEST_AUTH_QOP_AUTH = 1 << 1, 5129 5130 /** 5131 * The 'auth-int' QOP type. 5132 * Not supported by MHD for authentication. 5133 */ 5134 MHD_DIGEST_AUTH_QOP_AUTH_INT = 1 << 2 5135 } _MHD_FIXED_FLAGS_ENUM; 5136 5137 /** 5138 * The QOP ('quality of protection') types, multiple selection. 5139 * 5140 * #MHD_DigestAuthQOP always can be casted to #MHD_DigestAuthMultiQOP, but 5141 * not vice versa. 5142 * 5143 * @note Available since #MHD_VERSION 0x00097701 5144 */ 5145 enum MHD_DigestAuthMultiQOP 5146 { 5147 /** 5148 * Invalid/unknown QOP. 5149 */ 5150 MHD_DIGEST_AUTH_MULT_QOP_INVALID = MHD_DIGEST_AUTH_QOP_INVALID, 5151 5152 /** 5153 * No QOP parameter. 5154 * As described in old RFC 2069 original specification. 5155 * This mode is not allowed by latest RFCs and should be used only to 5156 * communicate with clients that do not support more modern modes (with QOP 5157 * parameter). 5158 * This mode is less secure than other modes and inefficient. 5159 */ 5160 MHD_DIGEST_AUTH_MULT_QOP_NONE = MHD_DIGEST_AUTH_QOP_NONE, 5161 5162 /** 5163 * The 'auth' QOP type. 5164 */ 5165 MHD_DIGEST_AUTH_MULT_QOP_AUTH = MHD_DIGEST_AUTH_QOP_AUTH, 5166 5167 /** 5168 * The 'auth-int' QOP type. 5169 * Not supported by MHD. 5170 * Reserved value. 5171 */ 5172 MHD_DIGEST_AUTH_MULT_QOP_AUTH_INT = MHD_DIGEST_AUTH_QOP_AUTH_INT, 5173 5174 /** 5175 * The 'auth' QOP type OR the old RFC2069 (no QOP) type. 5176 * In other words: any types except 'auth-int'. 5177 * RFC2069-compatible mode is allowed, thus this value should be used only 5178 * when it is really necessary. 5179 */ 5180 MHD_DIGEST_AUTH_MULT_QOP_ANY_NON_INT = 5181 MHD_DIGEST_AUTH_QOP_NONE | MHD_DIGEST_AUTH_QOP_AUTH, 5182 5183 /** 5184 * Any 'auth' QOP type ('auth' or 'auth-int'). 5185 * Currently supported as 'auth' QOP type only. 5186 */ 5187 MHD_DIGEST_AUTH_MULT_QOP_AUTH_ANY = 5188 MHD_DIGEST_AUTH_QOP_AUTH | MHD_DIGEST_AUTH_QOP_AUTH_INT 5189 } _MHD_FIXED_ENUM; 5190 5191 /** 5192 * The invalid value of 'nc' parameter in client Digest Authorization header. 5193 * @note Available since #MHD_VERSION 0x00097701 5194 */ 5195 #define MHD_DIGEST_AUTH_INVALID_NC_VALUE (0) 5196 5197 /** 5198 * Information from Digest Authorization client's header. 5199 * 5200 * All buffers pointed by any struct members are freed when #MHD_free() is 5201 * called for pointer to this structure. 5202 * 5203 * Application may modify buffers as needed until #MHD_free() is called for 5204 * pointer to this structure 5205 * @note Available since #MHD_VERSION 0x00097701 5206 */ 5207 struct MHD_DigestAuthInfo 5208 { 5209 /** 5210 * The algorithm as defined by client. 5211 * Set automatically to MD5 if not specified by client. 5212 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5213 * which uses other values! 5214 */ 5215 enum MHD_DigestAuthAlgo3 algo3; 5216 5217 /** 5218 * The type of username used by client. 5219 */ 5220 enum MHD_DigestAuthUsernameType uname_type; 5221 5222 /** 5223 * The username string. 5224 * Used only if username type is standard or extended, always NULL otherwise. 5225 * If extended notation is used, this string is pct-decoded string 5226 * with charset and language tag removed (i.e. it is original username 5227 * extracted from the extended notation). 5228 * When userhash is used by the client, this member is NULL and 5229 * @a userhash_hex and @a userhash_bin are set. 5230 * The buffer pointed by the @a username becomes invalid when the pointer 5231 * to the structure is freed by #MHD_free(). 5232 */ 5233 char *username; 5234 5235 /** 5236 * The length of the @a username. 5237 * When the @a username is NULL, this member is always zero. 5238 */ 5239 size_t username_len; 5240 5241 /** 5242 * The userhash string. 5243 * Valid only if username type is userhash. 5244 * This is unqoted string without decoding of the hexadecimal 5245 * digits (as provided by the client). 5246 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5247 * to the structure is freed by #MHD_free(). 5248 * @sa #MHD_digest_auth_calc_userhash_hex() 5249 */ 5250 char *userhash_hex; 5251 5252 /** 5253 * The length of the @a userhash_hex in characters. 5254 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5255 * When the @a userhash_hex is NULL, this member is always zero. 5256 */ 5257 size_t userhash_hex_len; 5258 5259 /** 5260 * The userhash decoded to binary form. 5261 * Used only if username type is userhash, always NULL otherwise. 5262 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5263 * long. 5264 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5265 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5266 * to the structure is freed by #MHD_free(). 5267 * @warning This is a binary data, no zero termination. 5268 * @warning To avoid buffer overruns, always check the size of the data before 5269 * use, because @a userhash_bin can point even to zero-sized 5270 * data. 5271 * @sa #MHD_digest_auth_calc_userhash() 5272 */ 5273 uint8_t *userhash_bin; 5274 5275 /** 5276 * The 'opaque' parameter value, as specified by client. 5277 * NULL if not specified by client. 5278 * The buffer pointed by the @a opaque becomes invalid when the pointer 5279 * to the structure is freed by #MHD_free(). 5280 */ 5281 char *opaque; 5282 5283 /** 5284 * The length of the @a opaque. 5285 * When the @a opaque is NULL, this member is always zero. 5286 */ 5287 size_t opaque_len; 5288 5289 /** 5290 * The 'realm' parameter value, as specified by client. 5291 * NULL if not specified by client. 5292 * The buffer pointed by the @a realm becomes invalid when the pointer 5293 * to the structure is freed by #MHD_free(). 5294 */ 5295 char *realm; 5296 5297 /** 5298 * The length of the @a realm. 5299 * When the @a realm is NULL, this member is always zero. 5300 */ 5301 size_t realm_len; 5302 5303 /** 5304 * The 'qop' parameter value. 5305 */ 5306 enum MHD_DigestAuthQOP qop; 5307 5308 /** 5309 * The length of the 'cnonce' parameter value, including possible 5310 * backslash-escape characters. 5311 * 'cnonce' is used in hash calculation, which is CPU-intensive procedure. 5312 * An application may want to reject too large cnonces to limit the CPU load. 5313 * A few kilobytes is a reasonable limit, typically cnonce is just 32-160 5314 * characters long. 5315 */ 5316 size_t cnonce_len; 5317 5318 /** 5319 * The nc parameter value. 5320 * Can be used by application to limit the number of nonce re-uses. If @a nc 5321 * is higher than application wants to allow, then "auth required" response 5322 * with 'stale=true' could be used to force client to retry with the fresh 5323 * 'nonce'. 5324 * If not specified by client or does not have hexadecimal digits only, the 5325 * value is #MHD_DIGEST_AUTH_INVALID_NC_VALUE. 5326 */ 5327 uint32_t nc; 5328 }; 5329 5330 5331 /** 5332 * Get information about Digest Authorization client's header. 5333 * 5334 * @param connection The MHD connection structure 5335 * @return NULL if no valid Digest Authorization header is used in the request; 5336 * a pointer to the structure with information if the valid request 5337 * header found, free using #MHD_free(). 5338 * @sa #MHD_digest_auth_get_username3() 5339 * @note Available since #MHD_VERSION 0x00097701 5340 * @ingroup authentication 5341 */ 5342 _MHD_EXTERN struct MHD_DigestAuthInfo * 5343 MHD_digest_auth_get_request_info3 (struct MHD_Connection *connection); 5344 5345 5346 /** 5347 * Information from Digest Authorization client's header. 5348 * 5349 * All buffers pointed by any struct members are freed when #MHD_free() is 5350 * called for pointer to this structure. 5351 * 5352 * Application may modify buffers as needed until #MHD_free() is called for 5353 * pointer to this structure 5354 * @note Available since #MHD_VERSION 0x00097701 5355 */ 5356 struct MHD_DigestAuthUsernameInfo 5357 { 5358 /** 5359 * The algorithm as defined by client. 5360 * Set automatically to MD5 if not specified by client. 5361 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5362 * which uses other values! 5363 */ 5364 enum MHD_DigestAuthAlgo3 algo3; 5365 5366 /** 5367 * The type of username used by client. 5368 * The 'invalid' and 'missing' types are not used in this structure, 5369 * instead NULL is returned by #MHD_digest_auth_get_username3(). 5370 */ 5371 enum MHD_DigestAuthUsernameType uname_type; 5372 5373 /** 5374 * The username string. 5375 * Used only if username type is standard or extended, always NULL otherwise. 5376 * If extended notation is used, this string is pct-decoded string 5377 * with charset and language tag removed (i.e. it is original username 5378 * extracted from the extended notation). 5379 * When userhash is used by the client, this member is NULL and 5380 * @a userhash_hex and @a userhash_bin are set. 5381 * The buffer pointed by the @a username becomes invalid when the pointer 5382 * to the structure is freed by #MHD_free(). 5383 */ 5384 char *username; 5385 5386 /** 5387 * The length of the @a username. 5388 * When the @a username is NULL, this member is always zero. 5389 */ 5390 size_t username_len; 5391 5392 /** 5393 * The userhash string. 5394 * Valid only if username type is userhash. 5395 * This is unqoted string without decoding of the hexadecimal 5396 * digits (as provided by the client). 5397 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5398 * to the structure is freed by #MHD_free(). 5399 * @sa #MHD_digest_auth_calc_userhash_hex() 5400 */ 5401 char *userhash_hex; 5402 5403 /** 5404 * The length of the @a userhash_hex in characters. 5405 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5406 * When the @a userhash_hex is NULL, this member is always zero. 5407 */ 5408 size_t userhash_hex_len; 5409 5410 /** 5411 * The userhash decoded to binary form. 5412 * Used only if username type is userhash, always NULL otherwise. 5413 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5414 * long. 5415 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5416 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5417 * to the structure is freed by #MHD_free(). 5418 * @warning This is a binary data, no zero termination. 5419 * @warning To avoid buffer overruns, always check the size of the data before 5420 * use, because @a userhash_bin can point even to zero-sized 5421 * data. 5422 * @sa #MHD_digest_auth_calc_userhash() 5423 */ 5424 uint8_t *userhash_bin; 5425 }; 5426 5427 5428 /** 5429 * Get the username from Digest Authorization client's header. 5430 * 5431 * @param connection The MHD connection structure 5432 * @return NULL if no valid Digest Authorization header is used in the request, 5433 * or no username parameter is present in the header, or username is 5434 * provided incorrectly by client (see description for 5435 * #MHD_DIGEST_AUTH_UNAME_TYPE_INVALID); 5436 * a pointer structure with information if the valid request header 5437 * found, free using #MHD_free(). 5438 * @sa #MHD_digest_auth_get_request_info3() provides more complete information 5439 * @note Available since #MHD_VERSION 0x00097701 5440 * @ingroup authentication 5441 */ 5442 _MHD_EXTERN struct MHD_DigestAuthUsernameInfo * 5443 MHD_digest_auth_get_username3 (struct MHD_Connection *connection); 5444 5445 5446 /** 5447 * The result of digest authentication of the client. 5448 * 5449 * All error values are zero or negative. 5450 * 5451 * @note Available since #MHD_VERSION 0x00097701 5452 */ 5453 enum MHD_DigestAuthResult 5454 { 5455 /** 5456 * Authentication OK. 5457 */ 5458 MHD_DAUTH_OK = 1, 5459 5460 /** 5461 * General error, like "out of memory". 5462 */ 5463 MHD_DAUTH_ERROR = 0, 5464 5465 /** 5466 * No "Authorization" header or wrong format of the header. 5467 * Also may be returned if required parameters in client Authorisation header 5468 * are missing or broken (in invalid format). 5469 */ 5470 MHD_DAUTH_WRONG_HEADER = -1, 5471 5472 /** 5473 * Wrong 'username'. 5474 */ 5475 MHD_DAUTH_WRONG_USERNAME = -2, 5476 5477 /** 5478 * Wrong 'realm'. 5479 */ 5480 MHD_DAUTH_WRONG_REALM = -3, 5481 5482 /** 5483 * Wrong 'URI' (or URI parameters). 5484 */ 5485 MHD_DAUTH_WRONG_URI = -4, 5486 5487 /** 5488 * Wrong 'qop'. 5489 */ 5490 MHD_DAUTH_WRONG_QOP = -5, 5491 5492 /** 5493 * Wrong 'algorithm'. 5494 */ 5495 MHD_DAUTH_WRONG_ALGO = -6, 5496 5497 /** 5498 * Too large (>64 KiB) Authorization parameter value. 5499 */ 5500 MHD_DAUTH_TOO_LARGE = -15, 5501 5502 /* The different form of naming is intentionally used for the results below, 5503 * as they are more important */ 5504 5505 /** 5506 * The 'nonce' is too old. Suggest the client to retry with the same 5507 * username and password to get the fresh 'nonce'. 5508 * The validity of the 'nonce' may be not checked. 5509 */ 5510 MHD_DAUTH_NONCE_STALE = -17, 5511 5512 /** 5513 * The 'nonce' was generated by MHD for other conditions. 5514 * This value is only returned if #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE 5515 * is set to anything other than #MHD_DAUTH_BIND_NONCE_NONE. 5516 * The interpretation of this code could be different. For example, if 5517 * #MHD_DAUTH_BIND_NONCE_URI is set and client just used the same 'nonce' for 5518 * another URI, the code could be handled as #MHD_DAUTH_NONCE_STALE as 5519 * RFCs allow nonces re-using for other URIs in the same "protection 5520 * space". However, if only #MHD_DAUTH_BIND_NONCE_CLIENT_IP bit is set and 5521 * it is know that clients have fixed IP addresses, this return code could 5522 * be handled like #MHD_DAUTH_NONCE_WRONG. 5523 */ 5524 MHD_DAUTH_NONCE_OTHER_COND = -18, 5525 5526 /** 5527 * The 'nonce' is wrong. May indicate an attack attempt. 5528 */ 5529 MHD_DAUTH_NONCE_WRONG = -33, 5530 5531 /** 5532 * The 'response' is wrong. Typically it means that wrong password used. 5533 * May indicate an attack attempt. 5534 */ 5535 MHD_DAUTH_RESPONSE_WRONG = -34 5536 }; 5537 5538 5539 /** 5540 * Authenticates the authorization header sent by the client. 5541 * 5542 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5543 * @a mqop and the client uses this mode, then server generated nonces are 5544 * used as one-time nonces because nonce-count is not supported in this old RFC. 5545 * Communication in this mode is very inefficient, especially if the client 5546 * requests several resources one-by-one as for every request a new nonce must 5547 * be generated and client repeats all requests twice (first time to get a new 5548 * nonce and second time to perform an authorised request). 5549 * 5550 * @param connection the MHD connection structure 5551 * @param realm the realm for authorization of the client 5552 * @param username the username to be authenticated, must be in clear text 5553 * even if userhash is used by the client 5554 * @param password the password matching the @a username (and the @a realm) 5555 * @param nonce_timeout the period of seconds since nonce generation, when 5556 * the nonce is recognised as valid and not stale; 5557 * if zero is specified then daemon default value is used. 5558 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5559 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5560 * returned; 5561 * if zero is specified then daemon default value is used. 5562 * @param mqop the QOP to use 5563 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5564 * by the client is not allowed by this parameter 5565 * @return #MHD_DAUTH_OK if authenticated, 5566 * the error code otherwise 5567 * @note Available since #MHD_VERSION 0x00097708 5568 * @ingroup authentication 5569 */ 5570 _MHD_EXTERN enum MHD_DigestAuthResult 5571 MHD_digest_auth_check3 (struct MHD_Connection *connection, 5572 const char *realm, 5573 const char *username, 5574 const char *password, 5575 unsigned int nonce_timeout, 5576 uint32_t max_nc, 5577 enum MHD_DigestAuthMultiQOP mqop, 5578 enum MHD_DigestAuthMultiAlgo3 malgo3); 5579 5580 5581 /** 5582 * Calculate userdigest, return it as a binary data. 5583 * 5584 * The "userdigest" is the hash of the "username:realm:password" string. 5585 * 5586 * The "userdigest" can be used to avoid storing the password in clear text 5587 * in database/files 5588 * 5589 * This function is designed to improve security of stored credentials, 5590 * the "userdigest" does not improve security of the authentication process. 5591 * 5592 * The results can be used to store username & userdigest pairs instead of 5593 * username & password pairs. To further improve security, application may 5594 * store username & userhash & userdigest triplets. 5595 * 5596 * @param algo3 the digest algorithm 5597 * @param username the username 5598 * @param realm the realm 5599 * @param password the password 5600 * @param[out] userdigest_bin the output buffer for userdigest; 5601 * if this function succeeds, then this buffer has 5602 * #MHD_digest_get_hash_size(algo3) bytes of 5603 * userdigest upon return 5604 * @param bin_buf_size the size of the @a userdigest_bin buffer, must be 5605 * at least #MHD_digest_get_hash_size(algo3) bytes long 5606 * @return MHD_YES on success, 5607 * MHD_NO if @a userdigest_bin is too small or if @a algo3 algorithm is 5608 * not supported (or external error has occurred, 5609 * see #MHD_FEATURE_EXTERN_HASH). 5610 * @sa #MHD_digest_auth_check_digest3() 5611 * @note Available since #MHD_VERSION 0x00097701 5612 * @ingroup authentication 5613 */ 5614 _MHD_EXTERN enum MHD_Result 5615 MHD_digest_auth_calc_userdigest (enum MHD_DigestAuthAlgo3 algo3, 5616 const char *username, 5617 const char *realm, 5618 const char *password, 5619 void *userdigest_bin, 5620 size_t bin_buf_size); 5621 5622 5623 /** 5624 * Authenticates the authorization header sent by the client by using 5625 * hash of "username:realm:password". 5626 * 5627 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5628 * @a mqop and the client uses this mode, then server generated nonces are 5629 * used as one-time nonces because nonce-count is not supported in this old RFC. 5630 * Communication in this mode is very inefficient, especially if the client 5631 * requests several resources one-by-one as for every request a new nonce must 5632 * be generated and client repeats all requests twice (first time to get a new 5633 * nonce and second time to perform an authorised request). 5634 * 5635 * @param connection the MHD connection structure 5636 * @param realm the realm for authorization of the client 5637 * @param username the username to be authenticated, must be in clear text 5638 * even if userhash is used by the client 5639 * @param userdigest the precalculated binary hash of the string 5640 * "username:realm:password", 5641 * see #MHD_digest_auth_calc_userdigest() 5642 * @param userdigest_size the size of the @a userdigest in bytes, must match the 5643 * hashing algorithm (see #MHD_MD5_DIGEST_SIZE, 5644 * #MHD_SHA256_DIGEST_SIZE, #MHD_SHA512_256_DIGEST_SIZE, 5645 * #MHD_digest_get_hash_size()) 5646 * @param nonce_timeout the period of seconds since nonce generation, when 5647 * the nonce is recognised as valid and not stale; 5648 * if zero is specified then daemon default value is used. 5649 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5650 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5651 * returned; 5652 * if zero is specified then daemon default value is used. 5653 * @param mqop the QOP to use 5654 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5655 * by the client is not allowed by this parameter; 5656 * more than one base algorithms (MD5, SHA-256, SHA-512/256) 5657 * cannot be used at the same time for this function 5658 * as @a userdigest must match specified algorithm 5659 * @return #MHD_DAUTH_OK if authenticated, 5660 * the error code otherwise 5661 * @sa #MHD_digest_auth_calc_userdigest() 5662 * @note Available since #MHD_VERSION 0x00097701 5663 * @ingroup authentication 5664 */ 5665 _MHD_EXTERN enum MHD_DigestAuthResult 5666 MHD_digest_auth_check_digest3 (struct MHD_Connection *connection, 5667 const char *realm, 5668 const char *username, 5669 const void *userdigest, 5670 size_t userdigest_size, 5671 unsigned int nonce_timeout, 5672 uint32_t max_nc, 5673 enum MHD_DigestAuthMultiQOP mqop, 5674 enum MHD_DigestAuthMultiAlgo3 malgo3); 5675 5676 5677 /** 5678 * Queues a response to request authentication from the client 5679 * 5680 * This function modifies provided @a response. The @a response must not be 5681 * reused and should be destroyed (by #MHD_destroy_response()) after call of 5682 * this function. 5683 * 5684 * If @a mqop allows both RFC 2069 (MHD_DIGEST_AUTH_QOP_NONE) and QOP with 5685 * value, then response is formed like if MHD_DIGEST_AUTH_QOP_NONE bit was 5686 * not set, because such response should be backward-compatible with RFC 2069. 5687 * 5688 * If @a mqop allows only MHD_DIGEST_AUTH_MULT_QOP_NONE, then the response is 5689 * formed in strict accordance with RFC 2069 (no 'qop', no 'userhash', no 5690 * 'charset'). For better compatibility with clients, it is recommended (but 5691 * not required) to set @a domain to NULL in this mode. 5692 * 5693 * @param connection the MHD connection structure 5694 * @param realm the realm presented to the client 5695 * @param opaque the string for opaque value, can be NULL, but NULL is 5696 * not recommended for better compatibility with clients; 5697 * the recommended format is hex or Base64 encoded string 5698 * @param domain the optional space-separated list of URIs for which the 5699 * same authorisation could be used, URIs can be in form 5700 * "path-absolute" (the path for the same host with initial slash) 5701 * or in form "absolute-URI" (the full path with protocol), in 5702 * any case client may assume that URI is in the same "protection 5703 * space" if it starts with any of values specified here; 5704 * could be NULL (clients typically assume that the same 5705 * credentials could be used for any URI on the same host); 5706 * this list provides information for the client only and does 5707 * not actually restrict anything on the server side 5708 * @param response the reply to send; should contain the "access denied" 5709 * body; 5710 * note: this function sets the "WWW Authenticate" header and 5711 * the caller should not set this header; 5712 * the NULL is tolerated 5713 * @param signal_stale if set to #MHD_YES then indication of stale nonce used in 5714 * the client's request is signalled by adding 'stale=true' 5715 * to the authentication header, this instructs the client 5716 * to retry immediately with the new nonce and the same 5717 * credentials, without asking user for the new password 5718 * @param mqop the QOP to use 5719 * @param malgo3 digest algorithm to use; if several algorithms are allowed 5720 * then MD5 is preferred (currently, may be changed in next 5721 * versions) 5722 * @param userhash_support if set to non-zero value (#MHD_YES) then support of 5723 * userhash is indicated, allowing client to provide 5724 * hash("username:realm") instead of the username in 5725 * clear text; 5726 * note that clients are allowed to provide the username 5727 * in cleartext even if this parameter set to non-zero; 5728 * when userhash is used, application must be ready to 5729 * identify users by provided userhash value instead of 5730 * username; see #MHD_digest_auth_calc_userhash() and 5731 * #MHD_digest_auth_calc_userhash_hex() 5732 * @param prefer_utf8 if not set to #MHD_NO, parameter 'charset=UTF-8' is 5733 * added, indicating for the client that UTF-8 encoding for 5734 * the username is preferred 5735 * @return #MHD_YES on success, #MHD_NO otherwise 5736 * @note Available since #MHD_VERSION 0x00097701 5737 * @ingroup authentication 5738 */ 5739 _MHD_EXTERN enum MHD_Result 5740 MHD_queue_auth_required_response3 (struct MHD_Connection *connection, 5741 const char *realm, 5742 const char *opaque, 5743 const char *domain, 5744 struct MHD_Response *response, 5745 int signal_stale, 5746 enum MHD_DigestAuthMultiQOP mqop, 5747 enum MHD_DigestAuthMultiAlgo3 algo, 5748 int userhash_support, 5749 int prefer_utf8); 5750 5751 5752 /** 5753 * Constant to indicate that the nonce of the provided 5754 * authentication code was wrong. 5755 * Used as return code by #MHD_digest_auth_check(), #MHD_digest_auth_check2(), 5756 * #MHD_digest_auth_check_digest(), #MHD_digest_auth_check_digest2(). 5757 * @ingroup authentication 5758 */ 5759 #define MHD_INVALID_NONCE -1 5760 5761 5762 /** 5763 * Get the username from the authorization header sent by the client 5764 * 5765 * This function supports username in standard and extended notations. 5766 * "userhash" is not supported by this function. 5767 * 5768 * @param connection The MHD connection structure 5769 * @return NULL if no username could be found, username provided as 5770 * "userhash", extended notation broken or memory allocation error 5771 * occurs; 5772 * a pointer to the username if found, free using #MHD_free(). 5773 * @warning Returned value must be freed by #MHD_free(). 5774 * @sa #MHD_digest_auth_get_username3() 5775 * @ingroup authentication 5776 */ 5777 _MHD_EXTERN char * 5778 MHD_digest_auth_get_username (struct MHD_Connection *connection); 5779 5780 5781 /** 5782 * Which digest algorithm should MHD use for HTTP digest authentication? 5783 * Used as parameter for #MHD_digest_auth_check2(), 5784 * #MHD_digest_auth_check_digest2(), #MHD_queue_auth_fail_response2(). 5785 */ 5786 enum MHD_DigestAuthAlgorithm 5787 { 5788 5789 /** 5790 * MHD should pick (currently defaults to MD5). 5791 */ 5792 MHD_DIGEST_ALG_AUTO = 0, 5793 5794 /** 5795 * Force use of MD5. 5796 */ 5797 MHD_DIGEST_ALG_MD5, 5798 5799 /** 5800 * Force use of SHA-256. 5801 */ 5802 MHD_DIGEST_ALG_SHA256 5803 5804 } _MHD_FIXED_ENUM; 5805 5806 5807 /** 5808 * Authenticates the authorization header sent by the client. 5809 * 5810 * @param connection The MHD connection structure 5811 * @param realm The realm presented to the client 5812 * @param username The username needs to be authenticated 5813 * @param password The password used in the authentication 5814 * @param nonce_timeout The amount of time for a nonce to be 5815 * invalid in seconds 5816 * @param algo digest algorithms allowed for verification 5817 * @return #MHD_YES if authenticated, #MHD_NO if not, 5818 * #MHD_INVALID_NONCE if nonce is invalid or stale 5819 * @note Available since #MHD_VERSION 0x00096200 5820 * @deprecated use MHD_digest_auth_check3() 5821 * @ingroup authentication 5822 */ 5823 _MHD_EXTERN int 5824 MHD_digest_auth_check2 (struct MHD_Connection *connection, 5825 const char *realm, 5826 const char *username, 5827 const char *password, 5828 unsigned int nonce_timeout, 5829 enum MHD_DigestAuthAlgorithm algo); 5830 5831 5832 /** 5833 * Authenticates the authorization header sent by the client. 5834 * Uses #MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). 5835 * Note that this MAY change to #MHD_DIGEST_ALG_AUTO in the future. 5836 * If you want to be sure you get MD5, use #MHD_digest_auth_check2() 5837 * and specify MD5 explicitly. 5838 * 5839 * @param connection The MHD connection structure 5840 * @param realm The realm presented to the client 5841 * @param username The username needs to be authenticated 5842 * @param password The password used in the authentication 5843 * @param nonce_timeout The amount of time for a nonce to be 5844 * invalid in seconds 5845 * @return #MHD_YES if authenticated, #MHD_NO if not, 5846 * #MHD_INVALID_NONCE if nonce is invalid or stale 5847 * @deprecated use MHD_digest_auth_check3() 5848 * @ingroup authentication 5849 */ 5850 _MHD_EXTERN int 5851 MHD_digest_auth_check (struct MHD_Connection *connection, 5852 const char *realm, 5853 const char *username, 5854 const char *password, 5855 unsigned int nonce_timeout); 5856 5857 5858 /** 5859 * Authenticates the authorization header sent by the client. 5860 * 5861 * @param connection The MHD connection structure 5862 * @param realm The realm presented to the client 5863 * @param username The username needs to be authenticated 5864 * @param digest An `unsigned char *' pointer to the binary MD5 sum 5865 * for the precalculated hash value "username:realm:password" 5866 * of @a digest_size bytes 5867 * @param digest_size number of bytes in @a digest (size must match @a algo!) 5868 * @param nonce_timeout The amount of time for a nonce to be 5869 * invalid in seconds 5870 * @param algo digest algorithms allowed for verification 5871 * @return #MHD_YES if authenticated, #MHD_NO if not, 5872 * #MHD_INVALID_NONCE if nonce is invalid or stale 5873 * @note Available since #MHD_VERSION 0x00096200 5874 * @deprecated use MHD_digest_auth_check_digest3() 5875 * @ingroup authentication 5876 */ 5877 _MHD_EXTERN int 5878 MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, 5879 const char *realm, 5880 const char *username, 5881 const uint8_t *digest, 5882 size_t digest_size, 5883 unsigned int nonce_timeout, 5884 enum MHD_DigestAuthAlgorithm algo); 5885 5886 5887 /** 5888 * Authenticates the authorization header sent by the client 5889 * Uses #MHD_DIGEST_ALG_MD5 (required, as @a digest is of fixed 5890 * size). 5891 * 5892 * @param connection The MHD connection structure 5893 * @param realm The realm presented to the client 5894 * @param username The username needs to be authenticated 5895 * @param digest An `unsigned char *' pointer to the binary hash 5896 * for the precalculated hash value "username:realm:password"; 5897 * length must be #MHD_MD5_DIGEST_SIZE bytes 5898 * @param nonce_timeout The amount of time for a nonce to be 5899 * invalid in seconds 5900 * @return #MHD_YES if authenticated, #MHD_NO if not, 5901 * #MHD_INVALID_NONCE if nonce is invalid or stale 5902 * @note Available since #MHD_VERSION 0x00096000 5903 * @deprecated use #MHD_digest_auth_check_digest3() 5904 * @ingroup authentication 5905 */ 5906 _MHD_EXTERN int 5907 MHD_digest_auth_check_digest (struct MHD_Connection *connection, 5908 const char *realm, 5909 const char *username, 5910 const uint8_t digest[MHD_MD5_DIGEST_SIZE], 5911 unsigned int nonce_timeout); 5912 5913 5914 /** 5915 * Queues a response to request authentication from the client 5916 * 5917 * This function modifies provided @a response. The @a response must not be 5918 * reused and should be destroyed after call of this function. 5919 * 5920 * @param connection The MHD connection structure 5921 * @param realm the realm presented to the client 5922 * @param opaque string to user for opaque value 5923 * @param response reply to send; should contain the "access denied" 5924 * body; note that this function will set the "WWW Authenticate" 5925 * header and that the caller should not do this; the NULL is tolerated 5926 * @param signal_stale #MHD_YES if the nonce is stale to add 5927 * 'stale=true' to the authentication header 5928 * @param algo digest algorithm to use 5929 * @return #MHD_YES on success, #MHD_NO otherwise 5930 * @note Available since #MHD_VERSION 0x00096200 5931 * @deprecated use MHD_queue_auth_required_response3() 5932 * @ingroup authentication 5933 */ 5934 _MHD_EXTERN enum MHD_Result 5935 MHD_queue_auth_fail_response2 (struct MHD_Connection *connection, 5936 const char *realm, 5937 const char *opaque, 5938 struct MHD_Response *response, 5939 int signal_stale, 5940 enum MHD_DigestAuthAlgorithm algo); 5941 5942 5943 /** 5944 * Queues a response to request authentication from the client. 5945 * For now uses MD5 (for backwards-compatibility). Still, if you 5946 * need to be sure, use #MHD_queue_auth_fail_response2(). 5947 * 5948 * This function modifies provided @a response. The @a response must not be 5949 * reused and should be destroyed after call of this function. 5950 * 5951 * @param connection The MHD connection structure 5952 * @param realm the realm presented to the client 5953 * @param opaque string to user for opaque value 5954 * @param response reply to send; should contain the "access denied" 5955 * body; note that this function will set the "WWW Authenticate" 5956 * header and that the caller should not do this; the NULL is tolerated 5957 * @param signal_stale #MHD_YES if the nonce is stale to add 5958 * 'stale=true' to the authentication header 5959 * @return #MHD_YES on success, #MHD_NO otherwise 5960 * @deprecated use MHD_queue_auth_required_response3() 5961 * @ingroup authentication 5962 */ 5963 _MHD_EXTERN enum MHD_Result 5964 MHD_queue_auth_fail_response (struct MHD_Connection *connection, 5965 const char *realm, 5966 const char *opaque, 5967 struct MHD_Response *response, 5968 int signal_stale); 5969 5970 5971 /* ********************* Basic Authentication functions *************** */ 5972 5973 5974 /** 5975 * Information decoded from Basic Authentication client's header. 5976 * 5977 * The username and the password are technically allowed to have binary zeros, 5978 * username_len and password_len could be used to detect such situations. 5979 * 5980 * The buffers pointed by username and password members are freed 5981 * when #MHD_free() is called for pointer to this structure. 5982 * 5983 * Application may modify buffers as needed until #MHD_free() is called for 5984 * pointer to this structure 5985 */ 5986 struct MHD_BasicAuthInfo 5987 { 5988 /** 5989 * The username, cannot be NULL. 5990 * The buffer pointed by the @a username becomes invalid when the pointer 5991 * to the structure is freed by #MHD_free(). 5992 */ 5993 char *username; 5994 5995 /** 5996 * The length of the @a username, not including zero-termination 5997 */ 5998 size_t username_len; 5999 6000 /** 6001 * The password, may be NULL if password is not encoded by the client. 6002 * The buffer pointed by the @a password becomes invalid when the pointer 6003 * to the structure is freed by #MHD_free(). 6004 */ 6005 char *password; 6006 6007 /** 6008 * The length of the @a password, not including zero-termination; 6009 * when the @a password is NULL, the length is always zero. 6010 */ 6011 size_t password_len; 6012 }; 6013 6014 /** 6015 * Get the username and password from the Basic Authorisation header 6016 * sent by the client 6017 * 6018 * @param connection the MHD connection structure 6019 * @return NULL if no valid Basic Authentication header is present in 6020 * current request, or 6021 * pointer to structure with username and password, which must be 6022 * freed by #MHD_free(). 6023 * @note Available since #MHD_VERSION 0x00097701 6024 * @ingroup authentication 6025 */ 6026 _MHD_EXTERN struct MHD_BasicAuthInfo * 6027 MHD_basic_auth_get_username_password3 (struct MHD_Connection *connection); 6028 6029 /** 6030 * Queues a response to request basic authentication from the client. 6031 * 6032 * The given response object is expected to include the payload for 6033 * the response; the "WWW-Authenticate" header will be added and the 6034 * response queued with the 'UNAUTHORIZED' status code. 6035 * 6036 * See RFC 7617#section-2 for details. 6037 * 6038 * The @a response is modified by this function. The modified response object 6039 * can be used to respond subsequent requests by #MHD_queue_response() 6040 * function with status code #MHD_HTTP_UNAUTHORIZED and must not be used again 6041 * with MHD_queue_basic_auth_required_response3() function. The response could 6042 * be destroyed right after call of this function. 6043 * 6044 * @param connection the MHD connection structure 6045 * @param realm the realm presented to the client 6046 * @param prefer_utf8 if not set to #MHD_NO, parameter'charset="UTF-8"' will 6047 * be added, indicating for client that UTF-8 encoding 6048 * is preferred 6049 * @param response the response object to modify and queue; the NULL 6050 * is tolerated 6051 * @return #MHD_YES on success, #MHD_NO otherwise 6052 * @note Available since #MHD_VERSION 0x00097704 6053 * @ingroup authentication 6054 */ 6055 _MHD_EXTERN enum MHD_Result 6056 MHD_queue_basic_auth_required_response3 (struct MHD_Connection *connection, 6057 const char *realm, 6058 int prefer_utf8, 6059 struct MHD_Response *response); 6060 6061 /** 6062 * Get the username and password from the basic authorization header sent by the client 6063 * 6064 * @param connection The MHD connection structure 6065 * @param[out] password a pointer for the password, free using #MHD_free(). 6066 * @return NULL if no username could be found, a pointer 6067 * to the username if found, free using #MHD_free(). 6068 * @deprecated use #MHD_basic_auth_get_username_password3() 6069 * @ingroup authentication 6070 */ 6071 _MHD_EXTERN char * 6072 MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 6073 char **password); 6074 6075 6076 /** 6077 * Queues a response to request basic authentication from the client 6078 * The given response object is expected to include the payload for 6079 * the response; the "WWW-Authenticate" header will be added and the 6080 * response queued with the 'UNAUTHORIZED' status code. 6081 * 6082 * @param connection The MHD connection structure 6083 * @param realm the realm presented to the client 6084 * @param response response object to modify and queue; the NULL is tolerated 6085 * @return #MHD_YES on success, #MHD_NO otherwise 6086 * @deprecated use MHD_queue_basic_auth_required_response3() 6087 * @ingroup authentication 6088 */ 6089 _MHD_EXTERN enum MHD_Result 6090 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, 6091 const char *realm, 6092 struct MHD_Response *response); 6093 6094 /* ********************** generic query functions ********************** */ 6095 6096 6097 /** 6098 * Obtain information about the given connection. 6099 * The returned pointer is invalidated with the next call of this function or 6100 * when the connection is closed. 6101 * 6102 * @param connection what connection to get information about 6103 * @param info_type what information is desired? 6104 * @param ... depends on @a info_type 6105 * @return NULL if this information is not available 6106 * (or if the @a info_type is unknown) 6107 * @ingroup specialized 6108 */ 6109 _MHD_EXTERN const union MHD_ConnectionInfo * 6110 MHD_get_connection_info (struct MHD_Connection *connection, 6111 enum MHD_ConnectionInfoType info_type, 6112 ...); 6113 6114 6115 /** 6116 * MHD connection options. Given to #MHD_set_connection_option to 6117 * set custom options for a particular connection. 6118 */ 6119 enum MHD_CONNECTION_OPTION 6120 { 6121 6122 /** 6123 * Set a custom timeout for the given connection. Specified 6124 * as the number of seconds, given as an `unsigned int`. Use 6125 * zero for no timeout. 6126 * If timeout was set to zero (or unset) before, setup of new value by 6127 * MHD_set_connection_option() will reset timeout timer. 6128 * Values larger than (UINT64_MAX / 2000 - 1) will 6129 * be clipped to this number. 6130 */ 6131 MHD_CONNECTION_OPTION_TIMEOUT 6132 6133 } _MHD_FIXED_ENUM; 6134 6135 6136 /** 6137 * Set a custom option for the given connection, overriding defaults. 6138 * 6139 * @param connection connection to modify 6140 * @param option option to set 6141 * @param ... arguments to the option, depending on the option type 6142 * @return #MHD_YES on success, #MHD_NO if setting the option failed 6143 * @ingroup specialized 6144 */ 6145 _MHD_EXTERN enum MHD_Result 6146 MHD_set_connection_option (struct MHD_Connection *connection, 6147 enum MHD_CONNECTION_OPTION option, 6148 ...); 6149 6150 6151 /** 6152 * Information about an MHD daemon. 6153 */ 6154 union MHD_DaemonInfo 6155 { 6156 /** 6157 * Size of the key, no longer supported. 6158 * @deprecated 6159 */ 6160 size_t key_size; 6161 6162 /** 6163 * Size of the mac key, no longer supported. 6164 * @deprecated 6165 */ 6166 size_t mac_key_size; 6167 6168 /** 6169 * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. 6170 */ 6171 MHD_socket listen_fd; 6172 6173 /** 6174 * Bind port number, returned for #MHD_DAEMON_INFO_BIND_PORT. 6175 */ 6176 uint16_t port; 6177 6178 /** 6179 * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. 6180 */ 6181 int epoll_fd; 6182 6183 /** 6184 * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. 6185 */ 6186 unsigned int num_connections; 6187 6188 /** 6189 * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. 6190 * This value is actually a bitfield. 6191 * Note: flags may differ from original 'flags' specified for 6192 * daemon, especially if #MHD_USE_AUTO was set. 6193 */ 6194 enum MHD_FLAG flags; 6195 }; 6196 6197 6198 /** 6199 * Obtain information about the given daemon. 6200 * The returned pointer is invalidated with the next call of this function or 6201 * when the daemon is stopped. 6202 * 6203 * @param daemon what daemon to get information about 6204 * @param info_type what information is desired? 6205 * @param ... depends on @a info_type 6206 * @return NULL if this information is not available 6207 * (or if the @a info_type is unknown) 6208 * @ingroup specialized 6209 */ 6210 _MHD_EXTERN const union MHD_DaemonInfo * 6211 MHD_get_daemon_info (struct MHD_Daemon *daemon, 6212 enum MHD_DaemonInfoType info_type, 6213 ...); 6214 6215 6216 /** 6217 * Obtain the version of this library 6218 * 6219 * @return static version string, e.g. "0.9.9" 6220 * @ingroup specialized 6221 */ 6222 _MHD_EXTERN const char * 6223 MHD_get_version (void); 6224 6225 6226 /** 6227 * Obtain the version of this library as a binary value. 6228 * 6229 * @return version binary value, e.g. "0x00090900" (#MHD_VERSION of 6230 * compiled MHD binary) 6231 * @note Available since #MHD_VERSION 0x00097601 6232 * @ingroup specialized 6233 */ 6234 _MHD_EXTERN uint32_t 6235 MHD_get_version_bin (void); 6236 6237 6238 /** 6239 * Types of information about MHD features, 6240 * used by #MHD_is_feature_supported(). 6241 */ 6242 enum MHD_FEATURE 6243 { 6244 /** 6245 * Get whether messages are supported. If supported then in debug 6246 * mode messages can be printed to stderr or to external logger. 6247 */ 6248 MHD_FEATURE_MESSAGES = 1, 6249 6250 /** 6251 * Get whether HTTPS is supported. If supported then flag 6252 * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, 6253 * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, 6254 * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, 6255 * #MHD_OPTION_HTTPS_PRIORITIES can be used. 6256 */ 6257 MHD_FEATURE_TLS = 2, 6258 MHD_FEATURE_SSL = 2, 6259 6260 /** 6261 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is 6262 * supported. 6263 */ 6264 MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, 6265 6266 /** 6267 * Get whether IPv6 is supported. If supported then flag 6268 * #MHD_USE_IPv6 can be used. 6269 */ 6270 MHD_FEATURE_IPv6 = 4, 6271 6272 /** 6273 * Get whether IPv6 without IPv4 is supported. If not supported 6274 * then IPv4 is always enabled in IPv6 sockets and 6275 * flag #MHD_USE_DUAL_STACK is always used when #MHD_USE_IPv6 is 6276 * specified. 6277 */ 6278 MHD_FEATURE_IPv6_ONLY = 5, 6279 6280 /** 6281 * Get whether `poll()` is supported. If supported then flag 6282 * #MHD_USE_POLL can be used. 6283 */ 6284 MHD_FEATURE_POLL = 6, 6285 6286 /** 6287 * Get whether `epoll()` is supported. If supported then Flags 6288 * #MHD_USE_EPOLL and 6289 * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. 6290 */ 6291 MHD_FEATURE_EPOLL = 7, 6292 6293 /** 6294 * Get whether shutdown on listen socket to signal other 6295 * threads is supported. If not supported flag 6296 * #MHD_USE_ITC is automatically forced. 6297 */ 6298 MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, 6299 6300 /** 6301 * Get whether socketpair is used internally instead of pipe to 6302 * signal other threads. 6303 */ 6304 MHD_FEATURE_SOCKETPAIR = 9, 6305 6306 /** 6307 * Get whether TCP Fast Open is supported. If supported then 6308 * flag #MHD_USE_TCP_FASTOPEN and option 6309 * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. 6310 */ 6311 MHD_FEATURE_TCP_FASTOPEN = 10, 6312 6313 /** 6314 * Get whether HTTP Basic authorization is supported. If supported 6315 * then functions #MHD_basic_auth_get_username_password and 6316 * #MHD_queue_basic_auth_fail_response can be used. 6317 */ 6318 MHD_FEATURE_BASIC_AUTH = 11, 6319 6320 /** 6321 * Get whether HTTP Digest authorization is supported. If 6322 * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, 6323 * #MHD_OPTION_NONCE_NC_SIZE and 6324 * #MHD_digest_auth_check() can be used. 6325 */ 6326 MHD_FEATURE_DIGEST_AUTH = 12, 6327 6328 /** 6329 * Get whether postprocessor is supported. If supported then 6330 * functions #MHD_create_post_processor(), #MHD_post_process() and 6331 * #MHD_destroy_post_processor() can 6332 * be used. 6333 */ 6334 MHD_FEATURE_POSTPROCESSOR = 13, 6335 6336 /** 6337 * Get whether password encrypted private key for HTTPS daemon is 6338 * supported. If supported then option 6339 * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. 6340 */ 6341 MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, 6342 6343 /** 6344 * Get whether reading files beyond 2 GiB boundary is supported. 6345 * If supported then #MHD_create_response_from_fd(), 6346 * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() 6347 * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and 6348 * offsets larger than 2 GiB. If not supported value of size+offset is 6349 * limited to 2 GiB. 6350 */ 6351 MHD_FEATURE_LARGE_FILE = 15, 6352 6353 /** 6354 * Get whether MHD set names on generated threads. 6355 */ 6356 MHD_FEATURE_THREAD_NAMES = 16, 6357 MHD_THREAD_NAMES = 16, 6358 6359 /** 6360 * Get whether HTTP "Upgrade" is supported. 6361 * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and 6362 * #MHD_create_response_for_upgrade() can be used. 6363 */ 6364 MHD_FEATURE_UPGRADE = 17, 6365 6366 /** 6367 * Get whether it's safe to use same FD for multiple calls of 6368 * #MHD_create_response_from_fd() and whether it's safe to use single 6369 * response generated by #MHD_create_response_from_fd() with multiple 6370 * connections at same time. 6371 * If #MHD_is_feature_supported() return #MHD_NO for this feature then 6372 * usage of responses with same file FD in multiple parallel threads may 6373 * results in incorrect data sent to remote client. 6374 * It's always safe to use same file FD in multiple responses if MHD 6375 * is run in any single thread mode. 6376 */ 6377 MHD_FEATURE_RESPONSES_SHARED_FD = 18, 6378 6379 /** 6380 * Get whether MHD support automatic detection of bind port number. 6381 * @sa #MHD_DAEMON_INFO_BIND_PORT 6382 */ 6383 MHD_FEATURE_AUTODETECT_BIND_PORT = 19, 6384 6385 /** 6386 * Get whether MHD supports automatic SIGPIPE suppression. 6387 * If SIGPIPE suppression is not supported, application must handle 6388 * SIGPIPE signal by itself. 6389 */ 6390 MHD_FEATURE_AUTOSUPPRESS_SIGPIPE = 20, 6391 6392 /** 6393 * Get whether MHD use system's sendfile() function to send 6394 * file-FD based responses over non-TLS connections. 6395 * @note Since v0.9.56 6396 */ 6397 MHD_FEATURE_SENDFILE = 21, 6398 6399 /** 6400 * Get whether MHD supports threads. 6401 */ 6402 MHD_FEATURE_THREADS = 22, 6403 6404 /** 6405 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK2 is 6406 * supported. 6407 */ 6408 MHD_FEATURE_HTTPS_CERT_CALLBACK2 = 23, 6409 6410 /** 6411 * Get whether automatic parsing of HTTP Cookie header is supported. 6412 * If disabled, no MHD_COOKIE_KIND will be generated by MHD. 6413 * MHD versions before 0x00097701 always support cookie parsing. 6414 * @note Available since #MHD_VERSION 0x01000200 6415 */ 6416 MHD_FEATURE_COOKIE_PARSING = 24, 6417 6418 /** 6419 * Get whether the early version the Digest Authorization (RFC 2069) is 6420 * supported (digest authorisation without QOP parameter). 6421 * Since #MHD_VERSION 0x00097701 it is always supported if Digest Auth 6422 * module is built. 6423 * @note Available since #MHD_VERSION 0x00097701 6424 */ 6425 MHD_FEATURE_DIGEST_AUTH_RFC2069 = 25, 6426 6427 /** 6428 * Get whether the MD5-based hashing algorithms are supported for Digest 6429 * Authorization. 6430 * Currently it is always supported if Digest Auth module is built 6431 * unless manually disabled in a custom build. 6432 * @note Available since #MHD_VERSION 0x00097701 6433 */ 6434 MHD_FEATURE_DIGEST_AUTH_MD5 = 26, 6435 6436 /** 6437 * Get whether the SHA-256-based hashing algorithms are supported for Digest 6438 * Authorization. 6439 * It is always supported since #MHD_VERSION 0x00096200 if Digest Auth 6440 * module is built unless manually disabled in a custom build. 6441 * @note Available since #MHD_VERSION 0x00097701 6442 */ 6443 MHD_FEATURE_DIGEST_AUTH_SHA256 = 27, 6444 6445 /** 6446 * Get whether the SHA-512/256-based hashing algorithms are supported 6447 * for Digest Authorization. 6448 * It it always supported since #MHD_VERSION 0x00097701 if Digest Auth 6449 * module is built unless manually disabled in a custom build. 6450 * @note Available since #MHD_VERSION 0x00097701 6451 */ 6452 MHD_FEATURE_DIGEST_AUTH_SHA512_256 = 28, 6453 6454 /** 6455 * Get whether QOP with value 'auth-int' (authentication with integrity 6456 * protection) is supported for Digest Authorization. 6457 * Currently it is always not supported. 6458 * @note Available since #MHD_VERSION 0x00097701 6459 */ 6460 MHD_FEATURE_DIGEST_AUTH_AUTH_INT = 29, 6461 6462 /** 6463 * Get whether 'session' algorithms (like 'MD5-sess') are supported for Digest 6464 * Authorization. 6465 * Currently it is always not supported. 6466 * @note Available since #MHD_VERSION 0x00097701 6467 */ 6468 MHD_FEATURE_DIGEST_AUTH_ALGO_SESSION = 30, 6469 6470 /** 6471 * Get whether 'userhash' is supported for Digest Authorization. 6472 * It is always supported since #MHD_VERSION 0x00097701 if Digest Auth 6473 * module is built. 6474 * @note Available since #MHD_VERSION 0x00097701 6475 */ 6476 MHD_FEATURE_DIGEST_AUTH_USERHASH = 31, 6477 6478 /** 6479 * Get whether any of hashing algorithms is implemented by external 6480 * function (like TLS library) and may fail due to external conditions, 6481 * like "out-of-memory". 6482 * 6483 * If result is #MHD_YES then functions which use hash calculations 6484 * like #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_check3() and others 6485 * potentially may fail even with valid input because of out-of-memory error 6486 * or crypto accelerator device failure, however in practice such fails are 6487 * unlikely. 6488 * @note Available since #MHD_VERSION 0x00097701 6489 */ 6490 MHD_FEATURE_EXTERN_HASH = 32, 6491 6492 /** 6493 * Get whether MHD was built with asserts enabled. 6494 * For debug builds the error log is always enabled even if #MHD_USE_ERROR_LOG 6495 * is not specified for daemon. 6496 * @note Available since #MHD_VERSION 0x00097701 6497 */ 6498 MHD_FEATURE_DEBUG_BUILD = 33, 6499 6500 /** 6501 * Get whether MHD was build with support for overridable FD_SETSIZE. 6502 * This feature should be always available when the relevant platform ability 6503 * is detected. 6504 * @sa #MHD_OPTION_APP_FD_SETSIZE 6505 * @note Available since #MHD_VERSION 0x00097705 6506 */ 6507 MHD_FEATURE_FLEXIBLE_FD_SETSIZE = 34 6508 }; 6509 6510 #define MHD_FEATURE_HTTPS_COOKIE_PARSING _MHD_DEPR_IN_MACRO ( \ 6511 "Value MHD_FEATURE_HTTPS_COOKIE_PARSING is deprecated, use MHD_FEATURE_COOKIE_PARSING" \ 6512 ) MHD_FEATURE_COOKIE_PARSING 6513 6514 /** 6515 * Get information about supported MHD features. 6516 * Indicate that MHD was compiled with or without support for 6517 * particular feature. Some features require additional support 6518 * by kernel. Kernel support is not checked by this function. 6519 * 6520 * @param feature type of requested information 6521 * @return #MHD_YES if feature is supported by MHD, #MHD_NO if 6522 * feature is not supported or feature is unknown. 6523 * @ingroup specialized 6524 */ 6525 _MHD_EXTERN enum MHD_Result 6526 MHD_is_feature_supported (enum MHD_FEATURE feature); 6527 6528 6529 MHD_C_DECLRATIONS_FINISH_HERE_ 6530 6531 #endif