1 /* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25 /*! \defgroup context-and-vhost context and vhost related functions 26 * ##Context and Vhost releated functions 27 * \ingroup lwsapi 28 * 29 * 30 * LWS requires that there is one context, in which you may define multiple 31 * vhosts. Each vhost is a virtual host, with either its own listen port 32 * or sharing an existing one. Each vhost has its own SSL context that can 33 * be set up individually or left disabled. 34 * 35 * If you don't care about multiple "site" support, you can ignore it and 36 * lws will create a single default vhost at context creation time. 37 */ 38 ///@{ 39 40 /* 41 * NOTE: These public enums are part of the abi. If you want to add one, 42 * add it at where specified so existing users are unaffected. 43 */ 44 45 46 #define LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT ((1ll << 1) | \ 47 (1ll << 12)) 48 /**< (VH) Don't allow the connection unless the client has a 49 * client cert that we recognize; provides 50 * LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */ 51 #define LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME (1ll << 2) 52 /**< (CTX) Don't try to get the server's hostname */ 53 #define LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT ((1ll << 3) | \ 54 (1ll << 12)) 55 /**< (VH) Allow non-SSL (plaintext) connections on the same 56 * port as SSL is listening. If combined with 57 * LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS it will try to 58 * force http connections on an https listener (eg, http://x.com:443) to 59 * redirect to an explicit https connection (eg, https://x.com) 60 */ 61 #define LWS_SERVER_OPTION_LIBEV (1ll << 4) 62 /**< (CTX) Use libev event loop */ 63 #define LWS_SERVER_OPTION_DISABLE_IPV6 (1ll << 5) 64 /**< (VH) Disable IPV6 support */ 65 #define LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS (1ll << 6) 66 /**< (VH) Don't load OS CA certs, you will need to load your 67 * own CA cert(s) */ 68 #define LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED (1ll << 7) 69 /**< (VH) Accept connections with no valid Cert (eg, selfsigned) */ 70 #define LWS_SERVER_OPTION_VALIDATE_UTF8 (1ll << 8) 71 /**< (VH) Check UT-8 correctness */ 72 #define LWS_SERVER_OPTION_SSL_ECDH ((1ll << 9) | \ 73 (1ll << 12)) 74 /**< (VH) initialize ECDH ciphers */ 75 #define LWS_SERVER_OPTION_LIBUV (1ll << 10) 76 /**< (CTX) Use libuv event loop */ 77 #define LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS ((1ll << 11) |\ 78 (1ll << 12)) 79 /**< (VH) Use an http redirect to force the client to ask for https. 80 * Notice if your http server issues the STS header and the client has 81 * ever seen that, the client will fail the http connection before it 82 * can actually do the redirect. 83 * 84 * Combine with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS to handle, eg, 85 * http://x.com:443 -> https://x.com 86 * 87 * (deprecated: use mount redirection) */ 88 #define LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT (1ll << 12) 89 /**< (CTX) Initialize the SSL library at all */ 90 #define LWS_SERVER_OPTION_EXPLICIT_VHOSTS (1ll << 13) 91 /**< (CTX) Only create the context when calling context 92 * create api, implies user code will create its own vhosts */ 93 #define LWS_SERVER_OPTION_UNIX_SOCK (1ll << 14) 94 /**< (VH) Use Unix socket */ 95 #define LWS_SERVER_OPTION_STS (1ll << 15) 96 /**< (VH) Send Strict Transport Security header, making 97 * clients subsequently go to https even if user asked for http */ 98 #define LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY (1ll << 16) 99 /**< (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect */ 100 #define LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE (1ll << 17) 101 /**< (VH) if set, only ipv6 allowed on the vhost */ 102 #define LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN (1ll << 18) 103 /**< (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE. A segfault 104 * normally makes the lib spin so you can attach a debugger to it 105 * even if it happened without a debugger in place. You can disable 106 * that by giving this option. 107 */ 108 #define LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN (1ll << 19) 109 /**< For backwards-compatibility reasons, by default 110 * lws prepends "http://" to the origin you give in the client 111 * connection info struct. If you give this flag when you create 112 * the context, only the string you give in the client connect 113 * info for .origin (if any) will be used directly. 114 */ 115 #define LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */ (1ll << 20) 116 #define LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20) 117 /**< (VH) if invalid http is coming in the first line, then abandon 118 * trying to treat the connection as http, and belatedly apply the 119 * .listen_accept_role / .listen_accept_protocol info struct members to 120 * the connection. If they are NULL, for backwards-compatibility the 121 * connection is bound to "raw-skt" role, and in order of priority: 122 * 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a 123 * pvo named "default", or 3) protocols[0]. 124 * 125 * Must be combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT 126 * to work with a socket listening with tls. 127 */ 128 129 #define LWS_SERVER_OPTION_LIBEVENT (1ll << 21) 130 /**< (CTX) Use libevent event loop */ 131 132 #define LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */ (1ll << 22) 133 #define LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 22) 134 /**< (VH) All connections to this vhost / port are bound to the 135 * role and protocol given in .listen_accept_role / 136 * .listen_accept_protocol. 137 * 138 * If those explicit user-controlled names are NULL, for backwards- 139 * compatibility the connection is bound to "raw-skt" role, and in order 140 * of priority: 1) the vh protocol with a pvo named "raw", 2) the vh 141 * protocol with a pvo named "default", or 3) protocols[0]. 142 * 143 * It's much preferred to specify the role + protocol using the 144 * .listen_accept_role and .listen_accept_protocol in the info struct. 145 */ 146 #define LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE (1ll << 23) 147 /**< (VH) Set to allow multiple listen sockets on one interface + 148 * address + port. The default is to strictly allow only one 149 * listen socket at a time. This is automatically selected if you 150 * have multiple service threads. Linux only. 151 */ 152 #define LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX (1ll << 24) 153 /**< (VH) Force setting up the vhost SSL_CTX, even though the user 154 * code doesn't explicitly provide a cert in the info struct. It 155 * implies the user code is going to provide a cert at the 156 * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback, which 157 * provides the vhost SSL_CTX * in the user parameter. 158 */ 159 #define LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT (1ll << 25) 160 /**< (VH) You probably don't want this. It forces this vhost to not 161 * call LWS_CALLBACK_PROTOCOL_INIT on its protocols. It's used in the 162 * special case of a temporary vhost bound to a single protocol. 163 */ 164 #define LWS_SERVER_OPTION_IGNORE_MISSING_CERT (1ll << 26) 165 /**< (VH) Don't fail if the vhost TLS cert or key are missing, just 166 * continue. The vhost won't be able to serve anything, but if for 167 * example the ACME plugin was configured to fetch a cert, this lets 168 * you bootstrap your vhost from having no cert to start with. 169 */ 170 #define LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK (1ll << 27) 171 /**< (VH) On this vhost, if the connection is being upgraded, insist 172 * that there's a Host: header and that the contents match the vhost 173 * name + port (443 / 80 are assumed if no :port given based on if the 174 * connection is using TLS). 175 * 176 * By default, without this flag, on upgrade lws just checks that the 177 * Host: header was given without checking the contents... this is to 178 * allow lax hostname mappings like localhost / 127.0.0.1, and CNAME 179 * mappings like www.mysite.com / mysite.com 180 */ 181 #define LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28) 182 /**< (VH) Send lws default HTTP headers recommended by Mozilla 183 * Observatory for security. This is a helper option that sends canned 184 * headers on each http response enabling a VERY strict Content Security 185 * Policy. The policy is so strict, for example it won't let the page 186 * run its own inline JS nor show images or take CSS from a different 187 * server. In many cases your JS only comes from your server as do the 188 * image sources and CSS, so that is what you want... attackers hoping 189 * to inject JS into your DOM are completely out of luck since even if 190 * they succeed, it will be rejected for execution by the browser 191 * according to the strict CSP. In other cases you have to deviate from 192 * the complete strictness, in which case don't use this flag: use the 193 * .headers member in the vhost init described in struct 194 * lws_context_creation_info instead to send the adapted headers 195 * yourself. 196 */ 197 198 #define LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER (1ll << 29) 199 /**< (VH) If you really want to allow HTTP connections on a tls 200 * listener, you can do it with this combined with 201 * LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT. But this is allowing 202 * accidental loss of the security assurances provided by tls depending 203 * on the client using http when he meant https... it's not 204 * recommended. 205 */ 206 #define LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND (1ll << 30) 207 /**< (VH) When instantiating a new vhost and the specified port is 208 * already in use, a null value shall be return to signal the error. 209 */ 210 211 #define LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW (1ll << 31) 212 /**< (VH) Indicates the connections using this vhost should ignore 213 * h2 WINDOW_UPDATE from broken peers and fix them up */ 214 215 #define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL (1ll << 32) 216 /**< (VH) Tell the vhost to treat half-closed remote clients as 217 * entered into an immortal (ie, not subject to normal timeouts) long 218 * poll mode. 219 */ 220 221 #define LWS_SERVER_OPTION_GLIB (1ll << 33) 222 /**< (CTX) Use glib event loop */ 223 224 #define LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE (1ll << 34) 225 /**< (VH) Tell the vhost to treat plain text http connections as 226 * H2 with prior knowledge (no upgrade request involved) 227 */ 228 229 #define LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES (1ll << 35) 230 /**< (CTX) Disable lws_system state, eg, because we are a secure streams 231 * proxy client that is not trying to track system state by itself. */ 232 233 #define LWS_SERVER_OPTION_SS_PROXY (1ll << 36) 234 /**< (VH) We are being a SS Proxy listen socket for the vhost */ 235 236 #define LWS_SERVER_OPTION_SDEVENT (1ll << 37) 237 /**< (CTX) Use sd-event loop */ 238 239 #define LWS_SERVER_OPTION_ULOOP (1ll << 38) 240 /**< (CTX) Use libubox / uloop event loop */ 241 242 #define LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE (1ll << 39) 243 /**< (VHOST) Disallow use of client tls caching (on by default) */ 244 245 246 /****** add new things just above ---^ ******/ 247 248 249 #define lws_check_opt(c, f) ((((uint64_t)c) & ((uint64_t)f)) == ((uint64_t)f)) 250 251 struct lws_plat_file_ops; 252 struct lws_ss_policy; 253 struct lws_ss_plugin; 254 struct lws_metric_policy; 255 256 typedef int (*lws_context_ready_cb_t)(struct lws_context *context); 257 258 typedef int (*lws_peer_limits_notify_t)(struct lws_context *ctx, 259 lws_sockfd_type sockfd, 260 lws_sockaddr46 *sa46); 261 262 /** struct lws_context_creation_info - parameters to create context and /or vhost with 263 * 264 * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS 265 * is not given, then for backwards compatibility one vhost is created at 266 * context-creation time using the info from this struct. 267 * 268 * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created 269 * at the same time as the context, they are expected to be created afterwards. 270 */ 271 struct lws_context_creation_info { 272 #if defined(LWS_WITH_NETWORK) 273 const char *iface; 274 /**< VHOST: NULL to bind the listen socket to all interfaces, or the 275 * interface name, eg, "eth2" 276 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is 277 * the pathname of a UNIX domain socket. you can use the UNIX domain 278 * sockets in abstract namespace, by prepending an at symbol to the 279 * socket name. */ 280 const struct lws_protocols *protocols; 281 /**< VHOST: Array of structures listing supported protocols and a 282 * protocol-specific callback for each one. The list is ended with an 283 * entry that has a NULL callback pointer. SEE ALSO .pprotocols below, 284 * which gives an alternative way to provide an array of pointers to 285 * protocol structs. */ 286 #if defined(LWS_ROLE_WS) 287 const struct lws_extension *extensions; 288 /**< VHOST: NULL or array of lws_extension structs listing the 289 * extensions this context supports. */ 290 #endif 291 #if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) 292 const struct lws_token_limits *token_limits; 293 /**< CONTEXT: NULL or struct lws_token_limits pointer which is 294 * initialized with a token length limit for each possible WSI_TOKEN_ */ 295 const char *http_proxy_address; 296 /**< VHOST: If non-NULL, attempts to proxy via the given address. 297 * If proxy auth is required, use format 298 * "username:password\@server:port" */ 299 const struct lws_protocol_vhost_options *headers; 300 /**< VHOST: pointer to optional linked list of per-vhost 301 * canned headers that are added to server responses */ 302 303 const struct lws_protocol_vhost_options *reject_service_keywords; 304 /**< CONTEXT: Optional list of keywords and rejection codes + text. 305 * 306 * The keywords are checked for existing in the user agent string. 307 * 308 * Eg, "badrobot" "404 Not Found" 309 */ 310 const struct lws_protocol_vhost_options *pvo; 311 /**< VHOST: pointer to optional linked list of per-vhost 312 * options made accessible to protocols */ 313 const char *log_filepath; 314 /**< VHOST: filepath to append logs to... this is opened before 315 * any dropping of initial privileges */ 316 const struct lws_http_mount *mounts; 317 /**< VHOST: optional linked list of mounts for this vhost */ 318 const char *server_string; 319 /**< CONTEXT: string used in HTTP headers to identify server 320 * software, if NULL, "libwebsockets". */ 321 322 const char *error_document_404; 323 /**< VHOST: If non-NULL, when asked to serve a non-existent file, 324 * lws attempts to server this url path instead. Eg, 325 * "/404.html" */ 326 int port; 327 /**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress 328 * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are 329 * writing a server but you are using \ref sock-adopt instead of the 330 * built-in listener. 331 * 332 * You can also set port to 0, in which case the kernel will pick 333 * a random port that is not already in use. You can find out what 334 * port the vhost is listening on using lws_get_vhost_listen_port() */ 335 336 unsigned int http_proxy_port; 337 /**< VHOST: If http_proxy_address was non-NULL, uses this port */ 338 unsigned int max_http_header_data2; 339 /**< CONTEXT: if max_http_header_data is 0 and this 340 * is nonzero, this will be used in place of the default. It's 341 * like this for compatibility with the original short version, 342 * this is unsigned int length. */ 343 unsigned int max_http_header_pool2; 344 /**< CONTEXT: if max_http_header_pool is 0 and this 345 * is nonzero, this will be used in place of the default. It's 346 * like this for compatibility with the original short version: 347 * this is unsigned int length. */ 348 349 int keepalive_timeout; 350 /**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote 351 * client to hold on to an idle HTTP/1.1 connection. Timeout lifetime 352 * applied to idle h2 network connections */ 353 uint32_t http2_settings[7]; 354 /**< VHOST: if http2_settings[0] is nonzero, the values given in 355 * http2_settings[1]..[6] are used instead of the lws 356 * platform default values. 357 * Just leave all at 0 if you don't care. 358 */ 359 360 unsigned short max_http_header_data; 361 /**< CONTEXT: The max amount of header payload that can be handled 362 * in an http request (unrecognized header payload is dropped) */ 363 unsigned short max_http_header_pool; 364 /**< CONTEXT: The max number of connections with http headers that 365 * can be processed simultaneously (the corresponding memory is 366 * allocated and deallocated dynamically as needed). If the pool is 367 * fully busy new incoming connections must wait for accept until one 368 * becomes free. 0 = allow as many ah as number of availble fds for 369 * the process */ 370 371 #endif 372 373 #if defined(LWS_WITH_TLS) 374 const char *ssl_private_key_password; 375 /**< VHOST: NULL or the passphrase needed for the private key. (For 376 * backwards compatibility, this can also be used to pass the client 377 * cert passphrase when setting up a vhost client SSL context, but it is 378 * preferred to use .client_ssl_private_key_password for that.) */ 379 const char *ssl_cert_filepath; 380 /**< VHOST: If libwebsockets was compiled to use ssl, and you want 381 * to listen using SSL, set to the filepath to fetch the 382 * server cert from, otherwise NULL for unencrypted. (For backwards 383 * compatibility, this can also be used to pass the client certificate 384 * when setting up a vhost client SSL context, but it is preferred to 385 * use .client_ssl_cert_filepath for that.) 386 * 387 * Notice you can alternatively set a single DER or PEM from a memory 388 * buffer as the vhost tls cert using \p server_ssl_cert_mem and 389 * \p server_ssl_cert_mem_len. 390 */ 391 const char *ssl_private_key_filepath; 392 /**< VHOST: filepath to private key if wanting SSL mode; 393 * this should not be set to NULL when ssl_cert_filepath is set. 394 * 395 * Alteratively, the certificate and private key can both be set in 396 * the OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback directly via 397 * openSSL library calls. This requires that 398 * LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX is set in the vhost info options 399 * to force initializtion of the SSL_CTX context. 400 * 401 * (For backwards compatibility, this can also be used 402 * to pass the client cert private key filepath when setting up a 403 * vhost client SSL context, but it is preferred to use 404 * .client_ssl_private_key_filepath for that.) 405 * 406 * Notice you can alternatively set a DER or PEM private key from a 407 * memory buffer as the vhost tls private key using 408 * \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len. 409 */ 410 const char *ssl_ca_filepath; 411 /**< VHOST: CA certificate filepath or NULL. (For backwards 412 * compatibility, this can also be used to pass the client CA 413 * filepath when setting up a vhost client SSL context, 414 * but it is preferred to use .client_ssl_ca_filepath for that.) 415 * 416 * Notice you can alternatively set a DER or PEM CA cert from a memory 417 * buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len. 418 */ 419 const char *ssl_cipher_list; 420 /**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg, 421 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" 422 * or you can leave it as NULL to get "DEFAULT" (For backwards 423 * compatibility, this can also be used to pass the client cipher 424 * list when setting up a vhost client SSL context, 425 * but it is preferred to use .client_ssl_cipher_list for that.) 426 * SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list 427 * for the equivalent for tls1.3. 428 */ 429 const char *ecdh_curve; 430 /**< VHOST: if NULL, defaults to initializing server with 431 * "prime256v1" */ 432 const char *tls1_3_plus_cipher_list; 433 /**< VHOST: List of valid ciphers to use for incoming server connections 434 * ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost 435 * or you can leave it as NULL to get "DEFAULT". 436 * SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost 437 * client SSL_CTX. 438 */ 439 440 const void *server_ssl_cert_mem; 441 /**< VHOST: Alternative for \p ssl_cert_filepath that allows setting 442 * from memory instead of from a file. At most one of 443 * \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */ 444 const void *server_ssl_private_key_mem; 445 /**< VHOST: Alternative for \p ssl_private_key_filepath allowing 446 * init from a private key in memory instead of a file. At most one 447 * of \p ssl_private_key_filepath or \p server_ssl_private_key_mem 448 * should be non-NULL. */ 449 const void *server_ssl_ca_mem; 450 /**< VHOST: Alternative for \p ssl_ca_filepath allowing 451 * init from a CA cert in memory instead of a file. At most one 452 * of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */ 453 454 long ssl_options_set; 455 /**< VHOST: Any bits set here will be set as server SSL options */ 456 long ssl_options_clear; 457 /**< VHOST: Any bits set here will be cleared as server SSL options */ 458 int simultaneous_ssl_restriction; 459 /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions 460 * possible.*/ 461 int simultaneous_ssl_handshake_restriction; 462 /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL handshakes ongoing */ 463 int ssl_info_event_mask; 464 /**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO 465 * callback for connections on this vhost. The mask values are of 466 * the form SSL_CB_ALERT, defined in openssl/ssl.h. The default of 467 * 0 means no info events will be reported. 468 */ 469 unsigned int server_ssl_cert_mem_len; 470 /**< VHOST: Server SSL context init: length of server_ssl_cert_mem in 471 * bytes */ 472 unsigned int server_ssl_private_key_mem_len; 473 /**< VHOST: length of \p server_ssl_private_key_mem in memory */ 474 unsigned int server_ssl_ca_mem_len; 475 /**< VHOST: length of \p server_ssl_ca_mem in memory */ 476 477 const char *alpn; 478 /**< CONTEXT: If non-NULL, default list of advertised alpn, comma- 479 * separated 480 * 481 * VHOST: If non-NULL, per-vhost list of advertised alpn, comma- 482 * separated 483 */ 484 485 486 #if defined(LWS_WITH_CLIENT) 487 const char *client_ssl_private_key_password; 488 /**< VHOST: Client SSL context init: NULL or the passphrase needed 489 * for the private key */ 490 const char *client_ssl_cert_filepath; 491 /**< VHOST: Client SSL context init: The certificate the client 492 * should present to the peer on connection */ 493 const void *client_ssl_cert_mem; 494 /**< VHOST: Client SSL context init: client certificate memory buffer or 495 * NULL... use this to load client cert from memory instead of file */ 496 unsigned int client_ssl_cert_mem_len; 497 /**< VHOST: Client SSL context init: length of client_ssl_cert_mem in 498 * bytes */ 499 const char *client_ssl_private_key_filepath; 500 /**< VHOST: Client SSL context init: filepath to client private key 501 * if this is set to NULL but client_ssl_cert_filepath is set, you 502 * can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS 503 * callback of protocols[0] to allow setting of the private key directly 504 * via tls library calls */ 505 const void *client_ssl_key_mem; 506 /**< VHOST: Client SSL context init: client key memory buffer or 507 * NULL... use this to load client key from memory instead of file */ 508 const char *client_ssl_ca_filepath; 509 /**< VHOST: Client SSL context init: CA certificate filepath or NULL */ 510 const char *client_ssl_ca_dirs[10]; 511 /**< VHOST: Client SSL context init: CA certificate path or NULL */ 512 const void *client_ssl_ca_mem; 513 /**< VHOST: Client SSL context init: CA certificate memory buffer or 514 * NULL... use this to load CA cert from memory instead of file */ 515 516 const char *client_ssl_cipher_list; 517 /**< VHOST: Client SSL context init: List of valid ciphers to use (eg, 518 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" 519 * or you can leave it as NULL to get "DEFAULT" */ 520 const char *client_tls_1_3_plus_cipher_list; 521 /**< VHOST: List of valid ciphers to use for outgoing client connections 522 * ON TLS1.3 AND ABOVE on this vhost (eg, 523 * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get 524 * "DEFAULT". 525 */ 526 527 long ssl_client_options_set; 528 /**< VHOST: Any bits set here will be set as CLIENT SSL options */ 529 long ssl_client_options_clear; 530 /**< VHOST: Any bits set here will be cleared as CLIENT SSL options */ 531 532 533 unsigned int client_ssl_ca_mem_len; 534 /**< VHOST: Client SSL context init: length of client_ssl_ca_mem in 535 * bytes */ 536 unsigned int client_ssl_key_mem_len; 537 /**< VHOST: Client SSL context init: length of client_ssl_key_mem in 538 * bytes */ 539 540 #endif 541 542 #if !defined(LWS_WITH_MBEDTLS) 543 SSL_CTX *provided_client_ssl_ctx; 544 /**< CONTEXT: If non-null, swap out libwebsockets ssl 545 * implementation for the one provided by provided_ssl_ctx. 546 * Libwebsockets no longer is responsible for freeing the context 547 * if this option is selected. */ 548 #else /* WITH_MBEDTLS */ 549 const char *mbedtls_client_preload_filepath; 550 /**< CONTEXT: If NULL, no effect. Otherwise it should point to a 551 * filepath where every created client SSL_CTX is preloaded from the 552 * system trust bundle. 553 * 554 * This sets a processwide variable that affects all contexts. 555 * 556 * Requires that the mbedtls provides mbedtls_x509_crt_parse_file(), 557 * else disabled. 558 */ 559 #endif 560 #endif 561 562 int ka_time; 563 /**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive 564 * timeout to all libwebsocket sockets, client or server */ 565 int ka_probes; 566 /**< CONTEXT: if ka_time was nonzero, after the timeout expires how many 567 * times to try to get a response from the peer before giving up 568 * and killing the connection */ 569 int ka_interval; 570 /**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes 571 * attempt */ 572 unsigned int timeout_secs; 573 /**< VHOST: various processes involving network roundtrips in the 574 * library are protected from hanging forever by timeouts. If 575 * nonzero, this member lets you set the timeout used in seconds. 576 * Otherwise a default timeout is used. */ 577 unsigned int connect_timeout_secs; 578 /**< VHOST: client connections have this long to find a working server 579 * from the DNS results, or the whole connection times out. If zero, 580 * a default timeout is used */ 581 int bind_iface; 582 /**< VHOST: nonzero to strictly bind sockets to the interface name in 583 * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE. 584 * 585 * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW 586 * capability. 587 * 588 * Notice that common things like access network interface IP from 589 * your local machine use your lo / loopback interface and will be 590 * disallowed by this. 591 */ 592 unsigned int timeout_secs_ah_idle; 593 /**< VHOST: seconds to allow a client to hold an ah without using it. 594 * 0 defaults to 10s. */ 595 #endif /* WITH_NETWORK */ 596 597 #if defined(LWS_WITH_TLS_SESSIONS) 598 uint32_t tls_session_timeout; 599 /**< VHOST: seconds until timeout/ttl for newly created sessions. 600 * 0 means default timeout (defined per protocol, usually 300s). */ 601 uint32_t tls_session_cache_max; 602 /**< VHOST: 0 for default limit of 10, or the maximum number of 603 * client tls sessions we are willing to cache */ 604 #endif 605 606 gid_t gid; 607 /**< CONTEXT: group id to change to after setting listen socket, 608 * or -1. See also .username below. */ 609 uid_t uid; 610 /**< CONTEXT: user id to change to after setting listen socket, 611 * or -1. See also .groupname below. */ 612 uint64_t options; 613 /**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */ 614 void *user; 615 /**< VHOST + CONTEXT: optional user pointer that will be associated 616 * with the context when creating the context (and can be retrieved by 617 * lws_context_user(context), or with the vhost when creating the vhost 618 * (and can be retrieved by lws_vhost_user(vhost)). You will need to 619 * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately 620 * if you care about giving the context and vhost different user pointer 621 * values. 622 */ 623 unsigned int count_threads; 624 /**< CONTEXT: how many contexts to create in an array, 0 = 1 */ 625 unsigned int fd_limit_per_thread; 626 /**< CONTEXT: nonzero means restrict each service thread to this 627 * many fds, 0 means the default which is divide the process fd 628 * limit by the number of threads. 629 * 630 * Note if this is nonzero, and fd_limit_per_thread multiplied by the 631 * number of service threads is less than the process ulimit, then lws 632 * restricts internal lookup table allocation to the smaller size, and 633 * switches to a less efficient lookup scheme. You should use this to 634 * trade off speed against memory usage if you know the lws context 635 * will only use a handful of fds. 636 * 637 * Bear in mind lws may use some fds internally, for example for the 638 * cancel pipe, so you may need to allow for some extras for normal 639 * operation. 640 */ 641 const char *vhost_name; 642 /**< VHOST: name of vhost, must match external DNS name used to 643 * access the site, like "warmcat.com" as it's used to match 644 * Host: header and / or SNI name for SSL. 645 * CONTEXT: NULL, or the name to associate with the context for 646 * context-specific logging 647 */ 648 #if defined(LWS_WITH_PLUGINS) 649 const char * const *plugin_dirs; 650 /**< CONTEXT: NULL, or NULL-terminated array of directories to 651 * scan for lws protocol plugins at context creation time */ 652 #endif 653 void *external_baggage_free_on_destroy; 654 /**< CONTEXT: NULL, or pointer to something externally malloc'd, that 655 * should be freed when the context is destroyed. This allows you to 656 * automatically sync the freeing action to the context destruction 657 * action, so there is no need for an external free() if the context 658 * succeeded to create. 659 */ 660 661 662 unsigned int pt_serv_buf_size; 663 /**< CONTEXT: 0 = default of 4096. This buffer is used by 664 * various service related features including file serving, it 665 * defines the max chunk of file that can be sent at once. 666 * At the risk of lws having to buffer failed large sends, it 667 * can be increased to, eg, 128KiB to improve throughput. */ 668 #if defined(LWS_WITH_FILE_OPS) 669 const struct lws_plat_file_ops *fops; 670 /**< CONTEXT: NULL, or pointer to an array of fops structs, terminated 671 * by a sentinel with NULL .open. 672 * 673 * If NULL, lws provides just the platform file operations struct for 674 * backwards compatibility. 675 */ 676 #endif 677 678 #if defined(LWS_WITH_SOCKS5) 679 const char *socks_proxy_address; 680 /**< VHOST: If non-NULL, attempts to proxy via the given address. 681 * If proxy auth is required, use format 682 * "username:password\@server:port" */ 683 unsigned int socks_proxy_port; 684 /**< VHOST: If socks_proxy_address was non-NULL, uses this port 685 * if nonzero, otherwise requires "server:port" in .socks_proxy_address 686 */ 687 #endif 688 689 #if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP) 690 cap_value_t caps[4]; 691 /**< CONTEXT: array holding Linux capabilities you want to 692 * continue to be available to the server after it transitions 693 * to a noprivileged user. Usually none are needed but for, eg, 694 * .bind_iface, CAP_NET_RAW is required. This gives you a way 695 * to still have the capability but drop root. 696 */ 697 char count_caps; 698 /**< CONTEXT: count of Linux capabilities in .caps[]. 0 means 699 * no capabilities will be inherited from root (the default) */ 700 #endif 701 void **foreign_loops; 702 /**< CONTEXT: This is ignored if the context is not being started with 703 * an event loop, ie, .options has a flag like 704 * LWS_SERVER_OPTION_LIBUV. 705 * 706 * NULL indicates lws should start its own even loop for 707 * each service thread, and deal with closing the loops 708 * when the context is destroyed. 709 * 710 * Non-NULL means it points to an array of external 711 * ("foreign") event loops that are to be used in turn for 712 * each service thread. In the default case of 1 service 713 * thread, it can just point to one foreign event loop. 714 */ 715 void (*signal_cb)(void *event_lib_handle, int signum); 716 /**< CONTEXT: NULL: default signal handling. Otherwise this receives 717 * the signal handler callback. event_lib_handle is the 718 * native event library signal handle, eg uv_signal_t * 719 * for libuv. 720 */ 721 struct lws_context **pcontext; 722 /**< CONTEXT: if non-NULL, at the end of context destroy processing, 723 * the pointer pointed to by pcontext is written with NULL. You can 724 * use this to let foreign event loops know that lws context destruction 725 * is fully completed. 726 */ 727 void (*finalize)(struct lws_vhost *vh, void *arg); 728 /**< VHOST: NULL, or pointer to function that will be called back 729 * when the vhost is just about to be freed. The arg parameter 730 * will be set to whatever finalize_arg is below. 731 */ 732 void *finalize_arg; 733 /**< VHOST: opaque pointer lws ignores but passes to the finalize 734 * callback. If you don't care, leave it NULL. 735 */ 736 const char *listen_accept_role; 737 /**< VHOST: NULL for default, or force accepted incoming connections to 738 * bind to this role. Uses the role names from their ops struct, eg, 739 * "raw-skt". 740 */ 741 const char *listen_accept_protocol; 742 /**< VHOST: NULL for default, or force accepted incoming connections to 743 * bind to this vhost protocol name. 744 */ 745 const struct lws_protocols **pprotocols; 746 /**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use 747 * this array of pointers to protocols structs. The end of the array 748 * is marked by a NULL pointer. 749 * 750 * This is preferred over .protocols, because it allows the protocol 751 * struct to be opaquely defined elsewhere, with just a pointer to it 752 * needed to create the context with it. .protocols requires also 753 * the type of the user data to be known so its size can be given. 754 */ 755 756 const char *username; /**< CONTEXT: string username for post-init 757 * permissions. Like .uid but takes a string username. */ 758 const char *groupname; /**< CONTEXT: string groupname for post-init 759 * permissions. Like .gid but takes a string groupname. */ 760 const char *unix_socket_perms; /**< VHOST: if your vhost is listening 761 * on a unix socket, you can give a "username:groupname" string here 762 * to control the owner:group it's created with. It's always created 763 * with 0660 mode. */ 764 const lws_system_ops_t *system_ops; 765 /**< CONTEXT: hook up lws_system_ apis to system-specific 766 * implementations */ 767 const lws_retry_bo_t *retry_and_idle_policy; 768 /**< VHOST: optional retry and idle policy to apply to this vhost. 769 * Currently only the idle parts are applied to the connections. 770 */ 771 #if defined(LWS_WITH_SYS_STATE) 772 lws_state_notify_link_t * const *register_notifier_list; 773 /**< CONTEXT: NULL, or pointer to an array of notifiers that should 774 * be registered during context creation, so they can see state change 775 * events from very early on. The array should end with a NULL. */ 776 #endif 777 #if defined(LWS_WITH_SECURE_STREAMS) 778 #if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY) 779 const struct lws_ss_policy *pss_policies; /**< CONTEXT: point to first 780 * in a linked-list of streamtype policies prepared by user code */ 781 #else 782 const char *pss_policies_json; /**< CONTEXT: point to a string 783 * containing a JSON description of the secure streams policies. Set 784 * to NULL if not using Secure Streams. 785 * If the platform supports files and the string does not begin with 786 * '{', lws treats the string as a filepath to open to get the JSON 787 * policy. 788 */ 789 #endif 790 const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array 791 * of pointers to plugin structs here, terminated with a NULL ptr. 792 * Set to NULL if not using Secure Streams. */ 793 const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0: 794 * point to a string giving the Unix Domain Socket address to use (start 795 * with @ for abstract namespace), ss_proxy_port nonzero: set the 796 * network interface address (not name, it's ambiguous for ipv4/6) to 797 * bind the tcp connection to the proxy to */ 798 const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port 799 * nonzero: the tcp address of the ss proxy to connect to */ 800 uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a 801 * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else 802 * the socket path given in ss_proxy_bind (start it with a + or +@); 803 * nonzero means connect via a tcp socket to the tcp address in 804 * ss_proxy_bind and the given port */ 805 #endif 806 807 int rlimit_nofile; 808 /**< 0 = inherit the initial ulimit for files / sockets from the startup 809 * environment. Nonzero = try to set the limit for this process. 810 */ 811 #if defined(LWS_WITH_PEER_LIMITS) 812 lws_peer_limits_notify_t pl_notify_cb; 813 /**< CONTEXT: NULL, or a callback to receive notifications each time a 814 * connection is being dropped because of peer limits. 815 * 816 * The callback provides the context, and an lws_sockaddr46 with the 817 * peer address and port. 818 */ 819 unsigned short ip_limit_ah; 820 /**< CONTEXT: max number of ah a single IP may use simultaneously 821 * 0 is no limit. This is a soft limit: if the limit is 822 * reached, connections from that IP will wait in the ah 823 * waiting list and not be able to acquire an ah until 824 * a connection belonging to the IP relinquishes one it 825 * already has. 826 */ 827 unsigned short ip_limit_wsi; 828 /**< CONTEXT: max number of wsi a single IP may use simultaneously. 829 * 0 is no limit. This is a hard limit, connections from 830 * the same IP will simply be dropped once it acquires the 831 * amount of simultaneous wsi / accepted connections 832 * given here. 833 */ 834 835 #endif /* PEER_LIMITS */ 836 837 #if defined(LWS_WITH_SYS_FAULT_INJECTION) 838 lws_fi_ctx_t fic; 839 /**< CONTEXT | VHOST: attach external Fault Injection context to the 840 * lws_context or vhost. If creating the context + default vhost in 841 * one step, only the context binds to \p fi. When creating a vhost 842 * otherwise this can bind to the vhost so the faults can be injected 843 * from the start. 844 */ 845 #endif 846 847 #if defined(LWS_WITH_SYS_SMD) 848 lws_smd_notification_cb_t early_smd_cb; 849 /**< CONTEXT: NULL, or an smd notification callback that will be registered 850 * immediately after the smd in the context is initialized. This ensures 851 * you can get all notifications without having to intercept the event loop 852 * creation, eg, when using an event library. Other callbacks can be 853 * registered later manually without problems. 854 */ 855 void *early_smd_opaque; 856 lws_smd_class_t early_smd_class_filter; 857 lws_usec_t smd_ttl_us; 858 /**< CONTEXT: SMD messages older than this many us are removed from the 859 * queue and destroyed even if not fully delivered yet. If zero, 860 * defaults to 2 seconds (5 second for FREERTOS). 861 */ 862 uint16_t smd_queue_depth; 863 /**< CONTEXT: Maximum queue depth, If zero defaults to 40 864 * (20 for FREERTOS) */ 865 #endif 866 867 #if defined(LWS_WITH_SYS_METRICS) 868 const struct lws_metric_policy *metrics_policies; 869 /**< CONTEXT: non-SS policy metrics policies */ 870 const char *metrics_prefix; 871 /**< CONTEXT: prefix for this context's metrics, used to distinguish 872 * metrics pooled from different processes / applications, so, eg what 873 * would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is 874 * set to "myapp". Policies are applied using the name with the prefix, 875 * if present. 876 */ 877 #endif 878 879 int fo_listen_queue; 880 /**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the 881 * platform supports it, with the given queue length for the listen 882 * socket. 883 */ 884 885 const struct lws_plugin_evlib *event_lib_custom; 886 /**< CONTEXT: If non-NULL, override event library selection so it uses 887 * this custom event library implementation, instead of default internal 888 * loop. Don't set any other event lib context creation flags in that 889 * case. it will be used automatically. This is useful for integration 890 * where an existing application is using its own handrolled event loop 891 * instead of an event library, it provides a way to allow lws to use 892 * the custom event loop natively as if it were an "event library". 893 */ 894 895 #if defined(LWS_WITH_TLS_JIT_TRUST) 896 size_t jitt_cache_max_footprint; 897 /**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache... 898 * LRU items are evicted to keep under this limit */ 899 int vh_idle_grace_ms; 900 /**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts 901 * are allowed to live without active connections using them. */ 902 #endif 903 904 lws_log_cx_t *log_cx; 905 /**< CONTEXT: NULL to use the default, process-scope logging context, 906 * else a specific logging context to associate with this context */ 907 908 #if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT) 909 const char *http_nsc_filepath; 910 /**< CONTEXT: Filepath to use for http netscape cookiejar file */ 911 912 size_t http_nsc_heap_max_footprint; 913 /**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie 914 * cache */ 915 size_t http_nsc_heap_max_items; 916 /**< CONTEXT: 0, or the max number of items allowed in the cookie cache 917 * before destroying lru items to keep it under the limit */ 918 size_t http_nsc_heap_max_payload; 919 /**< CONTEXT: 0, or the maximum size of a single cookie we are able to 920 * handle */ 921 #endif 922 923 /* Add new things just above here ---^ 924 * This is part of the ABI, don't needlessly break compatibility 925 * 926 * The below is to ensure later library versions with new 927 * members added above will see 0 (default) even if the app 928 * was not built against the newer headers. 929 */ 930 931 void *_unused[2]; /**< dummy */ 932 }; 933 934 /** 935 * lws_create_context() - Create the websocket handler 936 * \param info: pointer to struct with parameters 937 * 938 * This function creates the listening socket (if serving) and takes care 939 * of all initialization in one step. 940 * 941 * If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is 942 * created; you're expected to create your own vhosts afterwards using 943 * lws_create_vhost(). Otherwise a vhost named "default" is also created 944 * using the information in the vhost-related members, for compatibility. 945 * 946 * After initialization, it returns a struct lws_context * that 947 * represents this server. After calling, user code needs to take care 948 * of calling lws_service() with the context pointer to get the 949 * server's sockets serviced. This must be done in the same process 950 * context as the initialization call. 951 * 952 * The protocol callback functions are called for a handful of events 953 * including http requests coming in, websocket connections becoming 954 * established, and data arriving; it's also called periodically to allow 955 * async transmission. 956 * 957 * HTTP requests are sent always to the FIRST protocol in protocol, since 958 * at that time websocket protocol has not been negotiated. Other 959 * protocols after the first one never see any HTTP callback activity. 960 * 961 * The server created is a simple http server by default; part of the 962 * websocket standard is upgrading this http connection to a websocket one. 963 * 964 * This allows the same server to provide files like scripts and favicon / 965 * images or whatever over http and dynamic data over websockets all in 966 * one place; they're all handled in the user callback. 967 */ 968 LWS_VISIBLE LWS_EXTERN struct lws_context * 969 lws_create_context(const struct lws_context_creation_info *info); 970 971 972 /** 973 * lws_context_destroy() - Destroy the websocket context 974 * \param context: Websocket context 975 * 976 * This function closes any active connections and then frees the 977 * context. After calling this, any further use of the context is 978 * undefined. 979 */ 980 LWS_VISIBLE LWS_EXTERN void 981 lws_context_destroy(struct lws_context *context); 982 983 typedef int (*lws_reload_func)(void); 984 985 /** 986 * lws_context_deprecate() - Deprecate the websocket context 987 * 988 * \param context: Websocket context 989 * \param cb: Callback notified when old context listen sockets are closed 990 * 991 * This function is used on an existing context before superceding it 992 * with a new context. 993 * 994 * It closes any listen sockets in the context, so new connections are 995 * not possible. 996 * 997 * And it marks the context to be deleted when the number of active 998 * connections into it falls to zero. 999 * 1000 * This is aimed at allowing seamless configuration reloads. 1001 * 1002 * The callback cb will be called after the listen sockets are actually 1003 * closed and may be reopened. In the callback the new context should be 1004 * configured and created. (With libuv, socket close happens async after 1005 * more loop events). 1006 */ 1007 LWS_VISIBLE LWS_EXTERN void 1008 lws_context_deprecate(struct lws_context *context, lws_reload_func cb); 1009 1010 LWS_VISIBLE LWS_EXTERN int 1011 lws_context_is_deprecated(struct lws_context *context); 1012 1013 /** 1014 * lws_set_proxy() - Setups proxy to lws_context. 1015 * \param vhost: pointer to struct lws_vhost you want set proxy for 1016 * \param proxy: pointer to c string containing proxy in format address:port 1017 * 1018 * Returns 0 if proxy string was parsed and proxy was setup. 1019 * Returns -1 if proxy is NULL or has incorrect format. 1020 * 1021 * This is only required if your OS does not provide the http_proxy 1022 * environment variable (eg, OSX) 1023 * 1024 * IMPORTANT! You should call this function right after creation of the 1025 * lws_context and before call to connect. If you call this 1026 * function after connect behavior is undefined. 1027 * This function will override proxy settings made on lws_context 1028 * creation with genenv() call. 1029 */ 1030 LWS_VISIBLE LWS_EXTERN int 1031 lws_set_proxy(struct lws_vhost *vhost, const char *proxy); 1032 1033 /** 1034 * lws_set_socks() - Setup socks to lws_context. 1035 * \param vhost: pointer to struct lws_vhost you want set socks for 1036 * \param socks: pointer to c string containing socks in format address:port 1037 * 1038 * Returns 0 if socks string was parsed and socks was setup. 1039 * Returns -1 if socks is NULL or has incorrect format. 1040 * 1041 * This is only required if your OS does not provide the socks_proxy 1042 * environment variable (eg, OSX) 1043 * 1044 * IMPORTANT! You should call this function right after creation of the 1045 * lws_context and before call to connect. If you call this 1046 * function after connect behavior is undefined. 1047 * This function will override proxy settings made on lws_context 1048 * creation with genenv() call. 1049 */ 1050 LWS_VISIBLE LWS_EXTERN int 1051 lws_set_socks(struct lws_vhost *vhost, const char *socks); 1052 1053 struct lws_vhost; 1054 1055 /** 1056 * lws_create_vhost() - Create a vhost (virtual server context) 1057 * \param context: pointer to result of lws_create_context() 1058 * \param info: pointer to struct with parameters 1059 * 1060 * This function creates a virtual server (vhost) using the vhost-related 1061 * members of the info struct. You can create many vhosts inside one context 1062 * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS 1063 */ 1064 LWS_VISIBLE LWS_EXTERN struct lws_vhost * 1065 lws_create_vhost(struct lws_context *context, 1066 const struct lws_context_creation_info *info); 1067 1068 /** 1069 * lws_vhost_destroy() - Destroy a vhost (virtual server context) 1070 * 1071 * \param vh: pointer to result of lws_create_vhost() 1072 * 1073 * This function destroys a vhost. Normally, if you just want to exit, 1074 * then lws_destroy_context() will take care of everything. If you want 1075 * to destroy an individual vhost and all connections and allocations, you 1076 * can do it with this. 1077 * 1078 * If the vhost has a listen sockets shared by other vhosts, it will be given 1079 * to one of the vhosts sharing it rather than closed. 1080 * 1081 * The vhost close is staged according to the needs of the event loop, and if 1082 * there are multiple service threads. At the point the vhost itself if 1083 * about to be freed, if you provided a finalize callback and optional arg at 1084 * vhost creation time, it will be called just before the vhost is freed. 1085 */ 1086 LWS_VISIBLE LWS_EXTERN void 1087 lws_vhost_destroy(struct lws_vhost *vh); 1088 1089 /** 1090 * lwsws_get_config_globals() - Parse a JSON server config file 1091 * \param info: pointer to struct with parameters 1092 * \param d: filepath of the config file 1093 * \param config_strings: storage for the config strings extracted from JSON, 1094 * the pointer is incremented as strings are stored 1095 * \param len: pointer to the remaining length left in config_strings 1096 * the value is decremented as strings are stored 1097 * 1098 * This function prepares a n lws_context_creation_info struct with global 1099 * settings from a file d. 1100 * 1101 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled 1102 */ 1103 LWS_VISIBLE LWS_EXTERN int 1104 lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d, 1105 char **config_strings, int *len); 1106 1107 /** 1108 * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file 1109 * \param context: pointer to result of lws_create_context() 1110 * \param info: pointer to struct with parameters 1111 * \param d: filepath of the config file 1112 * \param config_strings: storage for the config strings extracted from JSON, 1113 * the pointer is incremented as strings are stored 1114 * \param len: pointer to the remaining length left in config_strings 1115 * the value is decremented as strings are stored 1116 * 1117 * This function creates vhosts into a context according to the settings in 1118 *JSON files found in directory d. 1119 * 1120 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled 1121 */ 1122 LWS_VISIBLE LWS_EXTERN int 1123 lwsws_get_config_vhosts(struct lws_context *context, 1124 struct lws_context_creation_info *info, const char *d, 1125 char **config_strings, int *len); 1126 1127 /** 1128 * lws_get_vhost() - return the vhost a wsi belongs to 1129 * 1130 * \param wsi: which connection 1131 */ 1132 LWS_VISIBLE LWS_EXTERN struct lws_vhost * 1133 lws_get_vhost(struct lws *wsi); 1134 1135 /** 1136 * lws_get_vhost_name() - returns the name of a vhost 1137 * 1138 * \param vhost: which vhost 1139 */ 1140 LWS_VISIBLE LWS_EXTERN const char * 1141 lws_get_vhost_name(struct lws_vhost *vhost); 1142 1143 /** 1144 * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL 1145 * 1146 * \param context: the lws_context to look in 1147 * \param name: vhost name we are looking for 1148 * 1149 * Returns NULL, or the vhost with the name \p name 1150 */ 1151 LWS_VISIBLE LWS_EXTERN struct lws_vhost * 1152 lws_get_vhost_by_name(struct lws_context *context, const char *name); 1153 1154 /** 1155 * lws_get_vhost_port() - returns the port a vhost listens on, or -1 1156 * 1157 * \param vhost: which vhost 1158 */ 1159 LWS_VISIBLE LWS_EXTERN int 1160 lws_get_vhost_port(struct lws_vhost *vhost); 1161 1162 /** 1163 * lws_get_vhost_user() - returns the user pointer for the vhost 1164 * 1165 * \param vhost: which vhost 1166 */ 1167 LWS_VISIBLE LWS_EXTERN void * 1168 lws_get_vhost_user(struct lws_vhost *vhost); 1169 1170 /** 1171 * lws_get_vhost_iface() - returns the binding for the vhost listen socket 1172 * 1173 * \param vhost: which vhost 1174 */ 1175 LWS_VISIBLE LWS_EXTERN const char * 1176 lws_get_vhost_iface(struct lws_vhost *vhost); 1177 1178 /** 1179 * lws_json_dump_vhost() - describe vhost state and stats in JSON 1180 * 1181 * \param vh: the vhost 1182 * \param buf: buffer to fill with JSON 1183 * \param len: max length of buf 1184 */ 1185 LWS_VISIBLE LWS_EXTERN int 1186 lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len); 1187 1188 /** 1189 * lws_json_dump_context() - describe context state and stats in JSON 1190 * 1191 * \param context: the context 1192 * \param buf: buffer to fill with JSON 1193 * \param len: max length of buf 1194 * \param hide_vhosts: nonzero to not provide per-vhost mount etc information 1195 * 1196 * Generates a JSON description of vhost state into buf 1197 */ 1198 LWS_VISIBLE LWS_EXTERN int 1199 lws_json_dump_context(const struct lws_context *context, char *buf, int len, 1200 int hide_vhosts); 1201 1202 /** 1203 * lws_vhost_user() - get the user data associated with the vhost 1204 * \param vhost: Websocket vhost 1205 * 1206 * This returns the optional user pointer that can be attached to 1207 * a vhost when it was created. Lws never dereferences this pointer, it only 1208 * sets it when the vhost is created, and returns it using this api. 1209 */ 1210 LWS_VISIBLE LWS_EXTERN void * 1211 lws_vhost_user(struct lws_vhost *vhost); 1212 1213 /** 1214 * lws_context_user() - get the user data associated with the context 1215 * \param context: Websocket context 1216 * 1217 * This returns the optional user allocation that can be attached to 1218 * the context the sockets live in at context_create time. It's a way 1219 * to let all sockets serviced in the same context share data without 1220 * using globals statics in the user code. 1221 */ 1222 LWS_VISIBLE LWS_EXTERN void * 1223 lws_context_user(struct lws_context *context); 1224 1225 LWS_VISIBLE LWS_EXTERN const char * 1226 lws_vh_tag(struct lws_vhost *vh); 1227 1228 /** 1229 * lws_context_is_being_destroyed() - find out if context is being destroyed 1230 * 1231 * \param context: the struct lws_context pointer 1232 * 1233 * Returns nonzero if the context has had lws_context_destroy() called on it... 1234 * when using event library loops the destroy process can be asynchronous. In 1235 * the special case of libuv foreign loops, the failure to create the context 1236 * may have to do work on the foreign loop to reverse the partial creation, 1237 * meaning a failed context create cannot unpick what it did and return NULL. 1238 * 1239 * In that condition, a valid context that is already started the destroy 1240 * process is returned, and this test api will return nonzero as a way to 1241 * find out the create is in the middle of failing. 1242 */ 1243 LWS_VISIBLE LWS_EXTERN int 1244 lws_context_is_being_destroyed(struct lws_context *context); 1245 1246 /*! \defgroup vhost-mounts Vhost mounts and options 1247 * \ingroup context-and-vhost-creation 1248 * 1249 * ##Vhost mounts and options 1250 */ 1251 ///@{ 1252 /** struct lws_protocol_vhost_options - linked list of per-vhost protocol 1253 * name=value options 1254 * 1255 * This provides a general way to attach a linked-list of name=value pairs, 1256 * which can also have an optional child link-list using the options member. 1257 */ 1258 struct lws_protocol_vhost_options { 1259 const struct lws_protocol_vhost_options *next; /**< linked list */ 1260 const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */ 1261 const char *name; /**< name of name=value pair */ 1262 const char *value; /**< value of name=value pair */ 1263 }; 1264 1265 /** enum lws_mount_protocols 1266 * This specifies the mount protocol for a mountpoint, whether it is to be 1267 * served from a filesystem, or it is a cgi etc. 1268 */ 1269 enum lws_mount_protocols { 1270 LWSMPRO_HTTP = 0, /**< http reverse proxy */ 1271 LWSMPRO_HTTPS = 1, /**< https reverse proxy */ 1272 LWSMPRO_FILE = 2, /**< serve from filesystem directory */ 1273 LWSMPRO_CGI = 3, /**< pass to CGI to handle */ 1274 LWSMPRO_REDIR_HTTP = 4, /**< redirect to http:// url */ 1275 LWSMPRO_REDIR_HTTPS = 5, /**< redirect to https:// url */ 1276 LWSMPRO_CALLBACK = 6, /**< hand by named protocol's callback */ 1277 }; 1278 1279 /** enum lws_authentication_mode 1280 * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter 1281 * is ignored unless LWSAUTHM_DEFAULT is set. 1282 */ 1283 enum lws_authentication_mode { 1284 LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */ 1285 LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */ 1286 }; 1287 1288 /** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */ 1289 #define AUTH_MODE_MASK 0xF0000000 1290 1291 /** struct lws_http_mount 1292 * 1293 * arguments for mounting something in a vhost's url namespace 1294 */ 1295 struct lws_http_mount { 1296 const struct lws_http_mount *mount_next; 1297 /**< pointer to next struct lws_http_mount */ 1298 const char *mountpoint; 1299 /**< mountpoint in http pathspace, eg, "/" */ 1300 const char *origin; 1301 /**< path to be mounted, eg, "/var/www/warmcat.com" */ 1302 const char *def; 1303 /**< default target, eg, "index.html" */ 1304 const char *protocol; 1305 /**<"protocol-name" to handle mount */ 1306 1307 const struct lws_protocol_vhost_options *cgienv; 1308 /**< optional linked-list of cgi options. These are created 1309 * as environment variables for the cgi process 1310 */ 1311 const struct lws_protocol_vhost_options *extra_mimetypes; 1312 /**< optional linked-list of mimetype mappings */ 1313 const struct lws_protocol_vhost_options *interpret; 1314 /**< optional linked-list of files to be interpreted */ 1315 1316 int cgi_timeout; 1317 /**< seconds cgi is allowed to live, if cgi://mount type */ 1318 int cache_max_age; 1319 /**< max-age for reuse of client cache of files, seconds */ 1320 unsigned int auth_mask; 1321 /**< bits set here must be set for authorized client session */ 1322 1323 unsigned int cache_reusable:1; /**< set if client cache may reuse this */ 1324 unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */ 1325 unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */ 1326 1327 unsigned char origin_protocol; /**< one of enum lws_mount_protocols */ 1328 unsigned char mountpoint_len; /**< length of mountpoint string */ 1329 1330 const char *basic_auth_login_file; 1331 /**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */ 1332 1333 /* Add new things just above here ---^ 1334 * This is part of the ABI, don't needlessly break compatibility 1335 */ 1336 }; 1337 1338 ///@} 1339 ///@} 1340