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#define LWS_SERVER_OPTION_OPENSSL_AUTO_DH_PARAMETERS (1ll << 40)
246 /**< Configure openssl to use the default built-in DH parameters
247 * to support TLSv1.2 Kx=DH ciphers (by calling SSL_CTX_set_dh_auto)
248 * This is needed when you want to enable TLSv1.2 ephemeral
249 * Diffie-Hellman (DH) key exchange ciphers
250 * (e.g. TLS_DHE_RSA_WITH_AES_256_GCM_SHA384). It's not recommended. */
251
252#define LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE ((1ll << 41) | \
253 (1ll << 12))
254 /**< (VH) An option to be used with mbedtls only, forces server to load
255 * and store the client cert (without CA dependent check)
256 * to be able to verify it later (after the handshake);
257 * provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT.
258 * Note: LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT and
259 * LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED are ignored if
260 * LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE is set */
261
262#define LWS_SERVER_OPTION_VH_INSTANTIATE_ALL_PROTOCOLS (1ll << 42)
263 /**< (VH) force instantiation of all protocols for this vhost */
264
265 /****** add new things just above ---^ ******/
266
267
268#define lws_check_opt(c, f) ((((uint64_t)c) & ((uint64_t)f)) == ((uint64_t)f))
269
270struct lws_plat_file_ops;
271struct lws_ss_policy;
272struct lws_ss_plugin;
273struct lws_metric_policy;
274struct lws_sss_ops;
275
276typedef int (*lws_context_ready_cb_t)(struct lws_context *context);
277
278#if defined(LWS_WITH_NETWORK)
279typedef int (*lws_peer_limits_notify_t)(struct lws_context *ctx,
280 lws_sockfd_type sockfd,
281 lws_sockaddr46 *sa46);
282#endif
283
284/** struct lws_context_creation_info - parameters to create context and /or vhost with
285 *
286 * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
287 * is not given, then for backwards compatibility one vhost is created at
288 * context-creation time using the info from this struct.
289 *
290 * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
291 * at the same time as the context, they are expected to be created afterwards.
292 */
293struct lws_context_creation_info {
294#if defined(LWS_WITH_NETWORK)
295 const char *iface;
296 /**< VHOST: NULL to bind the listen socket to all interfaces, or the
297 * interface name, eg, "eth2"
298 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
299 * the pathname of a UNIX domain socket. you can use the UNIX domain
300 * sockets in abstract namespace, by prepending an at symbol to the
301 * socket name. */
302 const struct lws_protocols *protocols;
303 /**< VHOST: Array of structures listing supported protocols and a
304 * protocol-specific callback for each one. The list is ended with an
305 * entry that has a NULL callback pointer. SEE ALSO .pprotocols below,
306 * which gives an alternative way to provide an array of pointers to
307 * protocol structs. */
308#if defined(LWS_ROLE_WS)
309 const struct lws_extension *extensions;
310 /**< VHOST: NULL or array of lws_extension structs listing the
311 * extensions this context supports. */
312#endif
313#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2)
314 const struct lws_token_limits *token_limits;
315 /**< CONTEXT: NULL or struct lws_token_limits pointer which is
316 * initialized with a token length limit for each possible WSI_TOKEN_ */
317 const char *http_proxy_address;
318 /**< VHOST: If non-NULL, attempts to proxy via the given address.
319 * If proxy auth is required, use format
320 * "username:password\@server:port" */
321 const struct lws_protocol_vhost_options *headers;
322 /**< VHOST: pointer to optional linked list of per-vhost
323 * canned headers that are added to server responses */
324
325 const struct lws_protocol_vhost_options *reject_service_keywords;
326 /**< CONTEXT: Optional list of keywords and rejection codes + text.
327 *
328 * The keywords are checked for existing in the user agent string.
329 *
330 * Eg, "badrobot" "404 Not Found"
331 */
332 const struct lws_protocol_vhost_options *pvo;
333 /**< VHOST: pointer to optional linked list of per-vhost
334 * options made accessible to protocols */
335 const char *log_filepath;
336 /**< VHOST: filepath to append logs to... this is opened before
337 * any dropping of initial privileges */
338 const struct lws_http_mount *mounts;
339 /**< VHOST: optional linked list of mounts for this vhost */
340 const char *server_string;
341 /**< CONTEXT: string used in HTTP headers to identify server
342 * software, if NULL, "libwebsockets". */
343
344 const char *error_document_404;
345 /**< VHOST: If non-NULL, when asked to serve a non-existent file,
346 * lws attempts to server this url path instead. Eg,
347 * "/404.html" */
348 int port;
349 /**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress
350 * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are
351 * writing a server but you are using \ref sock-adopt instead of the
352 * built-in listener.
353 *
354 * You can also set port to 0, in which case the kernel will pick
355 * a random port that is not already in use. You can find out what
356 * port the vhost is listening on using lws_get_vhost_listen_port()
357 *
358 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, you should set
359 * port to 0 */
360
361 unsigned int http_proxy_port;
362 /**< VHOST: If http_proxy_address was non-NULL, uses this port */
363 unsigned int max_http_header_data2;
364 /**< CONTEXT: if max_http_header_data is 0 and this
365 * is nonzero, this will be used in place of the default. It's
366 * like this for compatibility with the original short version,
367 * this is unsigned int length. */
368 unsigned int max_http_header_pool2;
369 /**< CONTEXT: if max_http_header_pool is 0 and this
370 * is nonzero, this will be used in place of the default. It's
371 * like this for compatibility with the original short version:
372 * this is unsigned int length. */
373
374 int keepalive_timeout;
375 /**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote
376 * client to hold on to an idle HTTP/1.1 connection. Timeout lifetime
377 * applied to idle h2 network connections */
378 uint32_t http2_settings[7];
379 /**< VHOST: if http2_settings[0] is nonzero, the values given in
380 * http2_settings[1]..[6] are used instead of the lws
381 * platform default values.
382 * Just leave all at 0 if you don't care.
383 */
384
385 unsigned short max_http_header_data;
386 /**< CONTEXT: The max amount of header payload that can be handled
387 * in an http request (unrecognized header payload is dropped) */
388 unsigned short max_http_header_pool;
389 /**< CONTEXT: The max number of connections with http headers that
390 * can be processed simultaneously (the corresponding memory is
391 * allocated and deallocated dynamically as needed). If the pool is
392 * fully busy new incoming connections must wait for accept until one
393 * becomes free. 0 = allow as many ah as number of availble fds for
394 * the process */
395
396#endif
397
398#if defined(LWS_WITH_TLS)
399 const char *ssl_private_key_password;
400 /**< VHOST: NULL or the passphrase needed for the private key. (For
401 * backwards compatibility, this can also be used to pass the client
402 * cert passphrase when setting up a vhost client SSL context, but it is
403 * preferred to use .client_ssl_private_key_password for that.) */
404 const char *ssl_cert_filepath;
405 /**< VHOST: If libwebsockets was compiled to use ssl, and you want
406 * to listen using SSL, set to the filepath to fetch the
407 * server cert from, otherwise NULL for unencrypted. (For backwards
408 * compatibility, this can also be used to pass the client certificate
409 * when setting up a vhost client SSL context, but it is preferred to
410 * use .client_ssl_cert_filepath for that.)
411 *
412 * Notice you can alternatively set a single DER or PEM from a memory
413 * buffer as the vhost tls cert using \p server_ssl_cert_mem and
414 * \p server_ssl_cert_mem_len.
415 */
416 const char *ssl_private_key_filepath;
417 /**< VHOST: filepath to private key if wanting SSL mode;
418 * this should not be set to NULL when ssl_cert_filepath is set.
419 *
420 * Alteratively, the certificate and private key can both be set in
421 * the OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback directly via
422 * openSSL library calls. This requires that
423 * LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX is set in the vhost info options
424 * to force initializtion of the SSL_CTX context.
425 *
426 * (For backwards compatibility, this can also be used
427 * to pass the client cert private key filepath when setting up a
428 * vhost client SSL context, but it is preferred to use
429 * .client_ssl_private_key_filepath for that.)
430 *
431 * Notice you can alternatively set a DER or PEM private key from a
432 * memory buffer as the vhost tls private key using
433 * \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len.
434 */
435 const char *ssl_ca_filepath;
436 /**< VHOST: CA certificate filepath or NULL. (For backwards
437 * compatibility, this can also be used to pass the client CA
438 * filepath when setting up a vhost client SSL context,
439 * but it is preferred to use .client_ssl_ca_filepath for that.)
440 *
441 * Notice you can alternatively set a DER or PEM CA cert from a memory
442 * buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len.
443 */
444 const char *ssl_cipher_list;
445 /**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg,
446 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
447 * or you can leave it as NULL to get "DEFAULT" (For backwards
448 * compatibility, this can also be used to pass the client cipher
449 * list when setting up a vhost client SSL context,
450 * but it is preferred to use .client_ssl_cipher_list for that.)
451 * SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list
452 * for the equivalent for tls1.3.
453 */
454 const char *ecdh_curve;
455 /**< VHOST: if NULL, defaults to initializing server with
456 * "prime256v1" */
457 const char *tls1_3_plus_cipher_list;
458 /**< VHOST: List of valid ciphers to use for incoming server connections
459 * ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost
460 * or you can leave it as NULL to get "DEFAULT".
461 * SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost
462 * client SSL_CTX.
463 */
464
465 const void *server_ssl_cert_mem;
466 /**< VHOST: Alternative for \p ssl_cert_filepath that allows setting
467 * from memory instead of from a file. At most one of
468 * \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */
469 const void *server_ssl_private_key_mem;
470 /**< VHOST: Alternative for \p ssl_private_key_filepath allowing
471 * init from a private key in memory instead of a file. At most one
472 * of \p ssl_private_key_filepath or \p server_ssl_private_key_mem
473 * should be non-NULL. */
474 const void *server_ssl_ca_mem;
475 /**< VHOST: Alternative for \p ssl_ca_filepath allowing
476 * init from a CA cert in memory instead of a file. At most one
477 * of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */
478
479 long ssl_options_set;
480 /**< VHOST: Any bits set here will be set as server SSL options */
481 long ssl_options_clear;
482 /**< VHOST: Any bits set here will be cleared as server SSL options */
483 int simultaneous_ssl_restriction;
484 /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions
485 * possible.*/
486 int simultaneous_ssl_handshake_restriction;
487 /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL handshakes ongoing */
488 int ssl_info_event_mask;
489 /**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO
490 * callback for connections on this vhost. The mask values are of
491 * the form SSL_CB_ALERT, defined in openssl/ssl.h. The default of
492 * 0 means no info events will be reported.
493 */
494 unsigned int server_ssl_cert_mem_len;
495 /**< VHOST: Server SSL context init: length of server_ssl_cert_mem in
496 * bytes */
497 unsigned int server_ssl_private_key_mem_len;
498 /**< VHOST: length of \p server_ssl_private_key_mem in memory */
499 unsigned int server_ssl_ca_mem_len;
500 /**< VHOST: length of \p server_ssl_ca_mem in memory */
501
502 const char *alpn;
503 /**< CONTEXT: If non-NULL, default list of advertised alpn, comma-
504 * separated
505 *
506 * VHOST: If non-NULL, per-vhost list of advertised alpn, comma-
507 * separated
508 */
509
510
511#if defined(LWS_WITH_CLIENT)
512 const char *client_ssl_private_key_password;
513 /**< VHOST: Client SSL context init: NULL or the passphrase needed
514 * for the private key */
515 const char *client_ssl_cert_filepath;
516 /**< VHOST: Client SSL context init: The certificate the client
517 * should present to the peer on connection */
518 const void *client_ssl_cert_mem;
519 /**< VHOST: Client SSL context init: client certificate memory buffer or
520 * NULL... use this to load client cert from memory instead of file */
521 unsigned int client_ssl_cert_mem_len;
522 /**< VHOST: Client SSL context init: length of client_ssl_cert_mem in
523 * bytes */
524 const char *client_ssl_private_key_filepath;
525 /**< VHOST: Client SSL context init: filepath to client private key
526 * if this is set to NULL but client_ssl_cert_filepath is set, you
527 * can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS
528 * callback of protocols[0] to allow setting of the private key directly
529 * via tls library calls */
530 const void *client_ssl_key_mem;
531 /**< VHOST: Client SSL context init: client key memory buffer or
532 * NULL... use this to load client key from memory instead of file */
533 const char *client_ssl_ca_filepath;
534 /**< VHOST: Client SSL context init: CA certificate filepath or NULL */
535 const void *client_ssl_ca_mem;
536 /**< VHOST: Client SSL context init: CA certificate memory buffer or
537 * NULL... use this to load CA cert from memory instead of file */
538
539 const char *client_ssl_cipher_list;
540 /**< VHOST: Client SSL context init: List of valid ciphers to use (eg,
541 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
542 * or you can leave it as NULL to get "DEFAULT" */
543 const char *client_tls_1_3_plus_cipher_list;
544 /**< VHOST: List of valid ciphers to use for outgoing client connections
545 * ON TLS1.3 AND ABOVE on this vhost (eg,
546 * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get
547 * "DEFAULT".
548 */
549
550 long ssl_client_options_set;
551 /**< VHOST: Any bits set here will be set as CLIENT SSL options */
552 long ssl_client_options_clear;
553 /**< VHOST: Any bits set here will be cleared as CLIENT SSL options */
554
555
556 unsigned int client_ssl_ca_mem_len;
557 /**< VHOST: Client SSL context init: length of client_ssl_ca_mem in
558 * bytes */
559 unsigned int client_ssl_key_mem_len;
560 /**< VHOST: Client SSL context init: length of client_ssl_key_mem in
561 * bytes */
562
563#endif
564
565#if !defined(LWS_WITH_MBEDTLS)
566 SSL_CTX *provided_client_ssl_ctx;
567 /**< CONTEXT: If non-null, swap out libwebsockets ssl
568 * implementation for the one provided by provided_ssl_ctx.
569 * Libwebsockets no longer is responsible for freeing the context
570 * if this option is selected. */
571#else /* WITH_MBEDTLS */
572 const char *mbedtls_client_preload_filepath;
573 /**< CONTEXT: If NULL, no effect. Otherwise it should point to a
574 * filepath where every created client SSL_CTX is preloaded from the
575 * system trust bundle.
576 *
577 * This sets a processwide variable that affects all contexts.
578 *
579 * Requires that the mbedtls provides mbedtls_x509_crt_parse_file(),
580 * else disabled.
581 */
582#endif
583#endif
584
585 int ka_time;
586 /**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
587 * timeout to all libwebsocket sockets, client or server */
588 int ka_probes;
589 /**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
590 * times to try to get a response from the peer before giving up
591 * and killing the connection */
592 int ka_interval;
593 /**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
594 * attempt */
595 unsigned int timeout_secs;
596 /**< VHOST: various processes involving network roundtrips in the
597 * library are protected from hanging forever by timeouts. If
598 * nonzero, this member lets you set the timeout used in seconds.
599 * Otherwise a default timeout is used. */
600 unsigned int connect_timeout_secs;
601 /**< VHOST: client connections have this long to find a working server
602 * from the DNS results, or the whole connection times out. If zero,
603 * a default timeout is used */
604 int bind_iface;
605 /**< VHOST: nonzero to strictly bind sockets to the interface name in
606 * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
607 *
608 * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW
609 * capability.
610 *
611 * Notice that common things like access network interface IP from
612 * your local machine use your lo / loopback interface and will be
613 * disallowed by this.
614 */
615 unsigned int timeout_secs_ah_idle;
616 /**< VHOST: seconds to allow a client to hold an ah without using it.
617 * 0 defaults to 10s. */
618#endif /* WITH_NETWORK */
619
620#if defined(LWS_WITH_TLS_SESSIONS)
621 uint32_t tls_session_timeout;
622 /**< VHOST: seconds until timeout/ttl for newly created sessions.
623 * 0 means default timeout (defined per protocol, usually 300s). */
624 uint32_t tls_session_cache_max;
625 /**< VHOST: 0 for default limit of 10, or the maximum number of
626 * client tls sessions we are willing to cache */
627#endif
628
629 gid_t gid;
630 /**< CONTEXT: group id to change to after setting listen socket,
631 * or -1. See also .username below. */
632 uid_t uid;
633 /**< CONTEXT: user id to change to after setting listen socket,
634 * or -1. See also .groupname below. */
635 uint64_t options;
636 /**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
637 void *user;
638 /**< VHOST + CONTEXT: optional user pointer that will be associated
639 * with the context when creating the context (and can be retrieved by
640 * lws_context_user(context), or with the vhost when creating the vhost
641 * (and can be retrieved by lws_vhost_user(vhost)). You will need to
642 * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately
643 * if you care about giving the context and vhost different user pointer
644 * values.
645 */
646 unsigned int count_threads;
647 /**< CONTEXT: how many contexts to create in an array, 0 = 1 */
648 unsigned int fd_limit_per_thread;
649 /**< CONTEXT: nonzero means restrict each service thread to this
650 * many fds, 0 means the default which is divide the process fd
651 * limit by the number of threads.
652 *
653 * Note if this is nonzero, and fd_limit_per_thread multiplied by the
654 * number of service threads is less than the process ulimit, then lws
655 * restricts internal lookup table allocation to the smaller size, and
656 * switches to a less efficient lookup scheme. You should use this to
657 * trade off speed against memory usage if you know the lws context
658 * will only use a handful of fds.
659 *
660 * Bear in mind lws may use some fds internally, for example for the
661 * cancel pipe, so you may need to allow for some extras for normal
662 * operation.
663 */
664 const char *vhost_name;
665 /**< VHOST: name of vhost, must match external DNS name used to
666 * access the site, like "warmcat.com" as it's used to match
667 * Host: header and / or SNI name for SSL.
668 * CONTEXT: NULL, or the name to associate with the context for
669 * context-specific logging
670 */
671#if defined(LWS_WITH_PLUGINS)
672 const char * const *plugin_dirs;
673 /**< CONTEXT: NULL, or NULL-terminated array of directories to
674 * scan for lws protocol plugins at context creation time */
675#endif
676 void *external_baggage_free_on_destroy;
677 /**< CONTEXT: NULL, or pointer to something externally malloc'd, that
678 * should be freed when the context is destroyed. This allows you to
679 * automatically sync the freeing action to the context destruction
680 * action, so there is no need for an external free() if the context
681 * succeeded to create.
682 */
683
684
685 unsigned int pt_serv_buf_size;
686 /**< CONTEXT: 0 = default of 4096. This buffer is used by
687 * various service related features including file serving, it
688 * defines the max chunk of file that can be sent at once.
689 * At the risk of lws having to buffer failed large sends, it
690 * can be increased to, eg, 128KiB to improve throughput. */
691#if defined(LWS_WITH_FILE_OPS)
692 const struct lws_plat_file_ops *fops;
693 /**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
694 * by a sentinel with NULL .open.
695 *
696 * If NULL, lws provides just the platform file operations struct for
697 * backwards compatibility.
698 */
699#endif
700
701#if defined(LWS_WITH_SOCKS5)
702 const char *socks_proxy_address;
703 /**< VHOST: If non-NULL, attempts to proxy via the given address.
704 * If proxy auth is required, use format
705 * "username:password\@server:port" */
706 unsigned int socks_proxy_port;
707 /**< VHOST: If socks_proxy_address was non-NULL, uses this port
708 * if nonzero, otherwise requires "server:port" in .socks_proxy_address
709 */
710#endif
711
712#if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
713 cap_value_t caps[4];
714 /**< CONTEXT: array holding Linux capabilities you want to
715 * continue to be available to the server after it transitions
716 * to a noprivileged user. Usually none are needed but for, eg,
717 * .bind_iface, CAP_NET_RAW is required. This gives you a way
718 * to still have the capability but drop root.
719 */
720 char count_caps;
721 /**< CONTEXT: count of Linux capabilities in .caps[]. 0 means
722 * no capabilities will be inherited from root (the default) */
723#endif
724 void **foreign_loops;
725 /**< CONTEXT: This is ignored if the context is not being started with
726 * an event loop, ie, .options has a flag like
727 * LWS_SERVER_OPTION_LIBUV.
728 *
729 * NULL indicates lws should start its own even loop for
730 * each service thread, and deal with closing the loops
731 * when the context is destroyed.
732 *
733 * Non-NULL means it points to an array of external
734 * ("foreign") event loops that are to be used in turn for
735 * each service thread. In the default case of 1 service
736 * thread, it can just point to one foreign event loop.
737 */
738 void (*signal_cb)(void *event_lib_handle, int signum);
739 /**< CONTEXT: NULL: default signal handling. Otherwise this receives
740 * the signal handler callback. event_lib_handle is the
741 * native event library signal handle, eg uv_signal_t *
742 * for libuv.
743 */
744 struct lws_context **pcontext;
745 /**< CONTEXT: if non-NULL, at the end of context destroy processing,
746 * the pointer pointed to by pcontext is written with NULL. You can
747 * use this to let foreign event loops know that lws context destruction
748 * is fully completed.
749 */
750 void (*finalize)(struct lws_vhost *vh, void *arg);
751 /**< VHOST: NULL, or pointer to function that will be called back
752 * when the vhost is just about to be freed. The arg parameter
753 * will be set to whatever finalize_arg is below.
754 */
755 void *finalize_arg;
756 /**< VHOST: opaque pointer lws ignores but passes to the finalize
757 * callback. If you don't care, leave it NULL.
758 */
759 const char *listen_accept_role;
760 /**< VHOST: NULL for default, or force accepted incoming connections to
761 * bind to this role. Uses the role names from their ops struct, eg,
762 * "raw-skt".
763 */
764 const char *listen_accept_protocol;
765 /**< VHOST: NULL for default, or force accepted incoming connections to
766 * bind to this vhost protocol name.
767 */
768 const struct lws_protocols **pprotocols;
769 /**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use
770 * this array of pointers to protocols structs. The end of the array
771 * is marked by a NULL pointer.
772 *
773 * This is preferred over .protocols, because it allows the protocol
774 * struct to be opaquely defined elsewhere, with just a pointer to it
775 * needed to create the context with it. .protocols requires also
776 * the type of the user data to be known so its size can be given.
777 */
778
779 const char *username; /**< CONTEXT: string username for post-init
780 * permissions. Like .uid but takes a string username. */
781 const char *groupname; /**< CONTEXT: string groupname for post-init
782 * permissions. Like .gid but takes a string groupname. */
783 const char *unix_socket_perms; /**< VHOST: if your vhost is listening
784 * on a unix socket, you can give a "username:groupname" string here
785 * to control the owner:group it's created with. It's always created
786 * with 0660 mode. */
787 const lws_system_ops_t *system_ops;
788 /**< CONTEXT: hook up lws_system_ apis to system-specific
789 * implementations */
790 const lws_retry_bo_t *retry_and_idle_policy;
791 /**< VHOST: optional retry and idle policy to apply to this vhost.
792 * Currently only the idle parts are applied to the connections.
793 */
794#if defined(LWS_WITH_SYS_STATE)
795 lws_state_notify_link_t * const *register_notifier_list;
796 /**< CONTEXT: NULL, or pointer to an array of notifiers that should
797 * be registered during context creation, so they can see state change
798 * events from very early on. The array should end with a NULL. */
799#endif
800#if defined(LWS_WITH_SECURE_STREAMS)
801#if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
802 const struct lws_ss_policy *pss_policies; /**< CONTEXT: point to first
803 * in a linked-list of streamtype policies prepared by user code */
804#else
805 const char *pss_policies_json; /**< CONTEXT: point to a string
806 * containing a JSON description of the secure streams policies. Set
807 * to NULL if not using Secure Streams.
808 * If the platform supports files and the string does not begin with
809 * '{', lws treats the string as a filepath to open to get the JSON
810 * policy.
811 */
812#endif
813 const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array
814 * of pointers to plugin structs here, terminated with a NULL ptr.
815 * Set to NULL if not using Secure Streams. */
816 const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0:
817 * point to a string giving the Unix Domain Socket address to use (start
818 * with @ for abstract namespace), ss_proxy_port nonzero: set the
819 * network interface address (not name, it's ambiguous for ipv4/6) to
820 * bind the tcp connection to the proxy to */
821 const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port
822 * nonzero: the tcp address of the ss proxy to connect to */
823 uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a
824 * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else
825 * the socket path given in ss_proxy_bind (start it with a + or +@);
826 * nonzero means connect via a tcp socket to the tcp address in
827 * ss_proxy_bind and the given port */
828 const struct lws_transport_proxy_ops *txp_ops_ssproxy; /**< CONTEXT: NULL, or
829 * custom sss transport ops used for ss proxy communication. NULL means
830 * to use the default wsi-based proxy server */
831 const void *txp_ssproxy_info; /**< CONTEXT: NULL, or extra transport-
832 * specifi creation info to be used at \p txp_ops_ssproxy creation */
833 const struct lws_transport_client_ops *txp_ops_sspc; /**< CONTEXT: NULL, or
834 * custom sss transport ops used for ss client communication to the ss
835 * proxy. NULL means to use the default wsi-based client support */
836#endif
837
838#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
839#endif
840
841 int rlimit_nofile;
842 /**< 0 = inherit the initial ulimit for files / sockets from the startup
843 * environment. Nonzero = try to set the limit for this process.
844 */
845#if defined(LWS_WITH_PEER_LIMITS)
846 lws_peer_limits_notify_t pl_notify_cb;
847 /**< CONTEXT: NULL, or a callback to receive notifications each time a
848 * connection is being dropped because of peer limits.
849 *
850 * The callback provides the context, and an lws_sockaddr46 with the
851 * peer address and port.
852 */
853 unsigned short ip_limit_ah;
854 /**< CONTEXT: max number of ah a single IP may use simultaneously
855 * 0 is no limit. This is a soft limit: if the limit is
856 * reached, connections from that IP will wait in the ah
857 * waiting list and not be able to acquire an ah until
858 * a connection belonging to the IP relinquishes one it
859 * already has.
860 */
861 unsigned short ip_limit_wsi;
862 /**< CONTEXT: max number of wsi a single IP may use simultaneously.
863 * 0 is no limit. This is a hard limit, connections from
864 * the same IP will simply be dropped once it acquires the
865 * amount of simultaneous wsi / accepted connections
866 * given here.
867 */
868
869#endif /* PEER_LIMITS */
870
871#if defined(LWS_WITH_SYS_FAULT_INJECTION)
872 lws_fi_ctx_t fic;
873 /**< CONTEXT | VHOST: attach external Fault Injection context to the
874 * lws_context or vhost. If creating the context + default vhost in
875 * one step, only the context binds to \p fi. When creating a vhost
876 * otherwise this can bind to the vhost so the faults can be injected
877 * from the start.
878 */
879#endif
880
881#if defined(LWS_WITH_SYS_SMD)
882 lws_smd_notification_cb_t early_smd_cb;
883 /**< CONTEXT: NULL, or an smd notification callback that will be registered
884 * immediately after the smd in the context is initialized. This ensures
885 * you can get all notifications without having to intercept the event loop
886 * creation, eg, when using an event library. Other callbacks can be
887 * registered later manually without problems.
888 */
889 void *early_smd_opaque;
890 lws_smd_class_t early_smd_class_filter;
891 lws_usec_t smd_ttl_us;
892 /**< CONTEXT: SMD messages older than this many us are removed from the
893 * queue and destroyed even if not fully delivered yet. If zero,
894 * defaults to 2 seconds (5 second for FREERTOS).
895 */
896 uint16_t smd_queue_depth;
897 /**< CONTEXT: Maximum queue depth, If zero defaults to 40
898 * (20 for FREERTOS) */
899#endif
900
901#if defined(LWS_WITH_SYS_METRICS)
902 const struct lws_metric_policy *metrics_policies;
903 /**< CONTEXT: non-SS policy metrics policies */
904 const char *metrics_prefix;
905 /**< CONTEXT: prefix for this context's metrics, used to distinguish
906 * metrics pooled from different processes / applications, so, eg what
907 * would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is
908 * set to "myapp". Policies are applied using the name with the prefix,
909 * if present.
910 */
911#endif
912
913 int fo_listen_queue;
914 /**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the
915 * platform supports it, with the given queue length for the listen
916 * socket.
917 */
918
919 const struct lws_plugin_evlib *event_lib_custom;
920 /**< CONTEXT: If non-NULL, override event library selection so it uses
921 * this custom event library implementation, instead of default internal
922 * loop. Don't set any other event lib context creation flags in that
923 * case. it will be used automatically. This is useful for integration
924 * where an existing application is using its own handrolled event loop
925 * instead of an event library, it provides a way to allow lws to use
926 * the custom event loop natively as if it were an "event library".
927 */
928
929#if defined(LWS_WITH_TLS_JIT_TRUST)
930 size_t jitt_cache_max_footprint;
931 /**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache...
932 * LRU items are evicted to keep under this limit */
933 int vh_idle_grace_ms;
934 /**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts
935 * are allowed to live without active connections using them. */
936#endif
937
938 lws_log_cx_t *log_cx;
939 /**< CONTEXT: NULL to use the default, process-scope logging context,
940 * else a specific logging context to associate with this context */
941
942#if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT)
943 const char *http_nsc_filepath;
944 /**< CONTEXT: Filepath to use for http netscape cookiejar file */
945
946 size_t http_nsc_heap_max_footprint;
947 /**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie
948 * cache */
949 size_t http_nsc_heap_max_items;
950 /**< CONTEXT: 0, or the max number of items allowed in the cookie cache
951 * before destroying lru items to keep it under the limit */
952 size_t http_nsc_heap_max_payload;
953 /**< CONTEXT: 0, or the maximum size of a single cookie we are able to
954 * handle */
955#endif
956
957#if defined(LWS_WITH_SYS_ASYNC_DNS)
958 const char **async_dns_servers;
959 /**< CONTEXT: NULL, or a pointer to an array of strings containing the
960 * numeric IP like "8.8.8.8" or "2001:4860:4860::8888" for a list of DNS
961 * server to forcibly add. If given, the list of strings must be
962 * terminated with a NULL.
963 */
964#endif
965
966#if defined(WIN32)
967 unsigned int win32_connect_check_interval_usec;
968 /**< CONTEXT: win32 needs client connection status checking at intervals
969 * to work reliably. This sets the interval in us, up to 999999. By
970 * default, it's 500us.
971 */
972#endif
973
974 int default_loglevel;
975 /**< CONTEXT: 0 for LLL_USER, LLL_ERR, LLL_WARN, LLL_NOTICE enabled by default when
976 * using lws_cmdline_option_handle_builtin(), else set to the LLL_ flags you want
977 * to be the default before calling lws_cmdline_option_handle_builtin(). Your
978 * selected default loglevel can then be cleanly overridden using -d 1039 etc
979 * commandline switch */
980
981 lws_sockfd_type vh_listen_sockfd;
982 /**< VHOST: 0 for normal vhost listen socket fd creation, if any.
983 * Nonzero to force the selection of an already-existing fd for the
984 * vhost's listen socket, which is already prepared. This is intended
985 * for an external process having chosen the fd, which cannot then be
986 * zero.
987 */
988
989#if defined(LWS_WITH_NETWORK)
990 const char *wol_if;
991 /**< CONTEXT: NULL, or interface name to bind outgoing WOL packet to */
992#endif
993
994 int argc;
995 /**< CONTEXT: optionally pass the app commandline to the context, so we can use it
996 * as part of lws_cmdline_option_cx() */
997 const char **argv;
998 /**< CONTEXT: optionally pass the app commandline to the context, so we can use it
999 * as part of lws_cmdline_option_cx() */
1000
1001 /* Add new things just above here ---^
1002 * This is part of the ABI, don't needlessly break compatibility
1003 *
1004 * The below is to ensure later library versions with new
1005 * members added above will see 0 (default) even if the app
1006 * was not built against the newer headers.
1007 */
1008
1009 void *_unused[2]; /**< dummy */
1010};
1011
1012/**
1013 * lws_create_context() - Create the websocket handler
1014 * \param info: pointer to struct with parameters
1015 *
1016 * This function creates the listening socket (if serving) and takes care
1017 * of all initialization in one step.
1018 *
1019 * If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
1020 * created; you're expected to create your own vhosts afterwards using
1021 * lws_create_vhost(). Otherwise a vhost named "default" is also created
1022 * using the information in the vhost-related members, for compatibility.
1023 *
1024 * After initialization, it returns a struct lws_context * that
1025 * represents this server. After calling, user code needs to take care
1026 * of calling lws_service() with the context pointer to get the
1027 * server's sockets serviced. This must be done in the same process
1028 * context as the initialization call.
1029 *
1030 * The protocol callback functions are called for a handful of events
1031 * including http requests coming in, websocket connections becoming
1032 * established, and data arriving; it's also called periodically to allow
1033 * async transmission.
1034 *
1035 * HTTP requests are sent always to the FIRST protocol in protocol, since
1036 * at that time websocket protocol has not been negotiated. Other
1037 * protocols after the first one never see any HTTP callback activity.
1038 *
1039 * The server created is a simple http server by default; part of the
1040 * websocket standard is upgrading this http connection to a websocket one.
1041 *
1042 * This allows the same server to provide files like scripts and favicon /
1043 * images or whatever over http and dynamic data over websockets all in
1044 * one place; they're all handled in the user callback.
1045 */
1046LWS_VISIBLE LWS_EXTERN struct lws_context *
1047lws_create_context(const struct lws_context_creation_info *info);
1048
1049
1050/**
1051 * lws_context_destroy() - Destroy the websocket context
1052 * \param context: Websocket context
1053 *
1054 * This function closes any active connections and then frees the
1055 * context. After calling this, any further use of the context is
1056 * undefined.
1057 */
1058LWS_VISIBLE LWS_EXTERN void
1059lws_context_destroy(struct lws_context *context);
1060
1061typedef int (*lws_reload_func)(void);
1062
1063/**
1064 * lws_context_deprecate() - Deprecate the websocket context
1065 *
1066 * \param context: Websocket context
1067 * \param cb: Callback notified when old context listen sockets are closed
1068 *
1069 * This function is used on an existing context before superceding it
1070 * with a new context.
1071 *
1072 * It closes any listen sockets in the context, so new connections are
1073 * not possible.
1074 *
1075 * And it marks the context to be deleted when the number of active
1076 * connections into it falls to zero.
1077 *
1078 * This is aimed at allowing seamless configuration reloads.
1079 *
1080 * The callback cb will be called after the listen sockets are actually
1081 * closed and may be reopened. In the callback the new context should be
1082 * configured and created. (With libuv, socket close happens async after
1083 * more loop events).
1084 */
1085LWS_VISIBLE LWS_EXTERN void
1086lws_context_deprecate(struct lws_context *context, lws_reload_func cb);
1087
1088LWS_VISIBLE LWS_EXTERN int
1089lws_context_is_deprecated(struct lws_context *context);
1090
1091/**
1092 * lws_set_proxy() - Setups proxy to lws_context.
1093 * \param vhost: pointer to struct lws_vhost you want set proxy for
1094 * \param proxy: pointer to c string containing proxy in format address:port
1095 *
1096 * Returns 0 if proxy string was parsed and proxy was setup.
1097 * Returns -1 if proxy is NULL or has incorrect format.
1098 *
1099 * This is only required if your OS does not provide the http_proxy
1100 * environment variable (eg, OSX)
1101 *
1102 * IMPORTANT! You should call this function right after creation of the
1103 * lws_context and before call to connect. If you call this
1104 * function after connect behavior is undefined.
1105 * This function will override proxy settings made on lws_context
1106 * creation with genenv() call.
1107 */
1108LWS_VISIBLE LWS_EXTERN int
1109lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
1110
1111/**
1112 * lws_set_socks() - Setup socks to lws_context.
1113 * \param vhost: pointer to struct lws_vhost you want set socks for
1114 * \param socks: pointer to c string containing socks in format address:port
1115 *
1116 * Returns 0 if socks string was parsed and socks was setup.
1117 * Returns -1 if socks is NULL or has incorrect format.
1118 *
1119 * This is only required if your OS does not provide the socks_proxy
1120 * environment variable (eg, OSX)
1121 *
1122 * IMPORTANT! You should call this function right after creation of the
1123 * lws_context and before call to connect. If you call this
1124 * function after connect behavior is undefined.
1125 * This function will override proxy settings made on lws_context
1126 * creation with genenv() call.
1127 */
1128LWS_VISIBLE LWS_EXTERN int
1129lws_set_socks(struct lws_vhost *vhost, const char *socks);
1130
1131struct lws_vhost;
1132
1133/**
1134 * lws_create_vhost() - Create a vhost (virtual server context)
1135 * \param context: pointer to result of lws_create_context()
1136 * \param info: pointer to struct with parameters
1137 *
1138 * This function creates a virtual server (vhost) using the vhost-related
1139 * members of the info struct. You can create many vhosts inside one context
1140 * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1141 */
1142LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1143lws_create_vhost(struct lws_context *context,
1144 const struct lws_context_creation_info *info);
1145
1146/**
1147 * lws_vhost_destroy() - Destroy a vhost (virtual server context)
1148 *
1149 * \param vh: pointer to result of lws_create_vhost()
1150 *
1151 * This function destroys a vhost. Normally, if you just want to exit,
1152 * then lws_destroy_context() will take care of everything. If you want
1153 * to destroy an individual vhost and all connections and allocations, you
1154 * can do it with this.
1155 *
1156 * If the vhost has a listen sockets shared by other vhosts, it will be given
1157 * to one of the vhosts sharing it rather than closed.
1158 *
1159 * The vhost close is staged according to the needs of the event loop, and if
1160 * there are multiple service threads. At the point the vhost itself if
1161 * about to be freed, if you provided a finalize callback and optional arg at
1162 * vhost creation time, it will be called just before the vhost is freed.
1163 */
1164LWS_VISIBLE LWS_EXTERN void
1165lws_vhost_destroy(struct lws_vhost *vh);
1166
1167/**
1168 * lwsws_get_config_globals() - Parse a JSON server config file
1169 * \param info: pointer to struct with parameters
1170 * \param d: filepath of the config file
1171 * \param config_strings: storage for the config strings extracted from JSON,
1172 * the pointer is incremented as strings are stored
1173 * \param len: pointer to the remaining length left in config_strings
1174 * the value is decremented as strings are stored
1175 *
1176 * This function prepares a n lws_context_creation_info struct with global
1177 * settings from a file d.
1178 *
1179 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1180 */
1181LWS_VISIBLE LWS_EXTERN int
1182lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
1183 char **config_strings, int *len);
1184
1185/**
1186 * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
1187 * \param context: pointer to result of lws_create_context()
1188 * \param info: pointer to struct with parameters
1189 * \param d: filepath of the config file
1190 * \param config_strings: storage for the config strings extracted from JSON,
1191 * the pointer is incremented as strings are stored
1192 * \param len: pointer to the remaining length left in config_strings
1193 * the value is decremented as strings are stored
1194 *
1195 * This function creates vhosts into a context according to the settings in
1196 *JSON files found in directory d.
1197 *
1198 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1199 */
1200LWS_VISIBLE LWS_EXTERN int
1201lwsws_get_config_vhosts(struct lws_context *context,
1202 struct lws_context_creation_info *info, const char *d,
1203 char **config_strings, int *len);
1204
1205/**
1206 * lws_get_vhost() - return the vhost a wsi belongs to
1207 *
1208 * \param wsi: which connection
1209 */
1210LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1211lws_get_vhost(struct lws *wsi);
1212
1213/**
1214 * lws_get_vhost_name() - returns the name of a vhost
1215 *
1216 * \param vhost: which vhost
1217 */
1218LWS_VISIBLE LWS_EXTERN const char *
1219lws_get_vhost_name(struct lws_vhost *vhost);
1220
1221/**
1222 * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
1223 *
1224 * \param context: the lws_context to look in
1225 * \param name: vhost name we are looking for
1226 *
1227 * Returns NULL, or the vhost with the name \p name
1228 */
1229LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1230lws_get_vhost_by_name(struct lws_context *context, const char *name);
1231
1232/**
1233 * lws_get_vhost_port() - returns the port a vhost listens on, or -1
1234 *
1235 * \param vhost: which vhost
1236 */
1237LWS_VISIBLE LWS_EXTERN int
1238lws_get_vhost_port(struct lws_vhost *vhost);
1239
1240/**
1241 * lws_get_vhost_user() - returns the user pointer for the vhost
1242 *
1243 * \param vhost: which vhost
1244 */
1245LWS_VISIBLE LWS_EXTERN void *
1246lws_get_vhost_user(struct lws_vhost *vhost);
1247
1248/**
1249 * lws_get_vhost_iface() - returns the binding for the vhost listen socket
1250 *
1251 * \param vhost: which vhost
1252 */
1253LWS_VISIBLE LWS_EXTERN const char *
1254lws_get_vhost_iface(struct lws_vhost *vhost);
1255
1256/**
1257 * lws_vhost_user() - get the user data associated with the vhost
1258 * \param vhost: Websocket vhost
1259 *
1260 * This returns the optional user pointer that can be attached to
1261 * a vhost when it was created. Lws never dereferences this pointer, it only
1262 * sets it when the vhost is created, and returns it using this api.
1263 */
1264LWS_VISIBLE LWS_EXTERN void *
1265lws_vhost_user(struct lws_vhost *vhost);
1266
1267/**
1268 * lws_context_user() - get the user data associated with the context
1269 * \param context: Websocket context
1270 *
1271 * This returns the optional user allocation that can be attached to
1272 * the context the sockets live in at context_create time. It's a way
1273 * to let all sockets serviced in the same context share data without
1274 * using globals statics in the user code.
1275 */
1276LWS_VISIBLE LWS_EXTERN void *
1277lws_context_user(struct lws_context *context);
1278
1279LWS_VISIBLE LWS_EXTERN const char *
1280lws_vh_tag(struct lws_vhost *vh);
1281
1282LWS_VISIBLE LWS_EXTERN void
1283_lws_context_info_defaults(struct lws_context_creation_info *info,
1284 const char *sspol);
1285
1286LWS_VISIBLE LWS_EXTERN void
1287lws_default_loop_exit(struct lws_context *cx);
1288
1289LWS_VISIBLE LWS_EXTERN void
1290lws_context_default_loop_run_destroy(struct lws_context *cx);
1291
1292LWS_VISIBLE LWS_EXTERN int
1293lws_cmdline_passfail(int argc, const char **argv, int actual);
1294
1295/**
1296 * lws_systemd_inherited_fd() - prepare vhost creation info for systemd exported fd if any
1297 *
1298 * \param index: 0+ index of exported fd
1299 * \param info: info struct to be prepared with related info, if any
1300 *
1301 * Returns 0 and points info to the related fd, aligning the other information
1302 * to the type of fd and port it is bound to, or returns nonzero if no such
1303 * inherited fd.
1304 */
1305LWS_VISIBLE LWS_EXTERN int
1306lws_systemd_inherited_fd(unsigned int index,
1307 struct lws_context_creation_info *info);
1308
1309/**
1310 * lws_context_is_being_destroyed() - find out if context is being destroyed
1311 *
1312 * \param context: the struct lws_context pointer
1313 *
1314 * Returns nonzero if the context has had lws_context_destroy() called on it...
1315 * when using event library loops the destroy process can be asynchronous. In
1316 * the special case of libuv foreign loops, the failure to create the context
1317 * may have to do work on the foreign loop to reverse the partial creation,
1318 * meaning a failed context create cannot unpick what it did and return NULL.
1319 *
1320 * In that condition, a valid context that is already started the destroy
1321 * process is returned, and this test api will return nonzero as a way to
1322 * find out the create is in the middle of failing.
1323 */
1324LWS_VISIBLE LWS_EXTERN int
1325lws_context_is_being_destroyed(struct lws_context *context);
1326
1327/*! \defgroup vhost-mounts Vhost mounts and options
1328 * \ingroup context-and-vhost-creation
1329 *
1330 * ##Vhost mounts and options
1331 */
1332///@{
1333/** struct lws_protocol_vhost_options - linked list of per-vhost protocol
1334 * name=value options
1335 *
1336 * This provides a general way to attach a linked-list of name=value pairs,
1337 * which can also have an optional child link-list using the options member.
1338 */
1339struct lws_protocol_vhost_options {
1340 const struct lws_protocol_vhost_options *next; /**< linked list */
1341 const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */
1342 const char *name; /**< name of name=value pair */
1343 const char *value; /**< value of name=value pair */
1344};
1345
1346/** enum lws_mount_protocols
1347 * This specifies the mount protocol for a mountpoint, whether it is to be
1348 * served from a filesystem, or it is a cgi etc.
1349 */
1350enum lws_mount_protocols {
1351 LWSMPRO_HTTP = 0, /**< http reverse proxy */
1352 LWSMPRO_HTTPS = 1, /**< https reverse proxy */
1353 LWSMPRO_FILE = 2, /**< serve from filesystem directory */
1354 LWSMPRO_CGI = 3, /**< pass to CGI to handle */
1355 LWSMPRO_REDIR_HTTP = 4, /**< redirect to http:// url */
1356 LWSMPRO_REDIR_HTTPS = 5, /**< redirect to https:// url */
1357 LWSMPRO_CALLBACK = 6, /**< handle by named protocol's callback */
1358 LWSMPRO_NO_MOUNT = 7, /**< matches fall back to no match processing */
1359};
1360
1361/** enum lws_authentication_mode
1362 * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter
1363 * is ignored unless LWSAUTHM_DEFAULT is set.
1364 */
1365enum lws_authentication_mode {
1366 LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */
1367 LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */
1368};
1369
1370/** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */
1371#define AUTH_MODE_MASK 0xF0000000
1372
1373/** struct lws_http_mount
1374 *
1375 * arguments for mounting something in a vhost's url namespace
1376 */
1377struct lws_http_mount {
1378 const struct lws_http_mount *mount_next;
1379 /**< pointer to next struct lws_http_mount */
1380 const char *mountpoint;
1381 /**< mountpoint in http pathspace, eg, "/" */
1382 const char *origin;
1383 /**< path to be mounted, eg, "/var/www/warmcat.com" */
1384 const char *def;
1385 /**< default target, eg, "index.html" */
1386 const char *protocol;
1387 /**<"protocol-name" to handle mount */
1388
1389 const struct lws_protocol_vhost_options *cgienv;
1390 /**< optional linked-list of cgi options. These are created
1391 * as environment variables for the cgi process
1392 */
1393 const struct lws_protocol_vhost_options *extra_mimetypes;
1394 /**< optional linked-list of mimetype mappings */
1395 const struct lws_protocol_vhost_options *interpret;
1396 /**< optional linked-list of files to be interpreted */
1397
1398 int cgi_timeout;
1399 /**< seconds cgi is allowed to live, if cgi://mount type */
1400 int cache_max_age;
1401 /**< max-age for reuse of client cache of files, seconds */
1402 unsigned int auth_mask;
1403 /**< bits set here must be set for authorized client session */
1404
1405 unsigned int cache_reusable:1; /**< set if client cache may reuse this */
1406 unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */
1407 unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */
1408 unsigned int cache_no:1; /**< set if client should check cache always*/
1409
1410 unsigned char origin_protocol; /**< one of enum lws_mount_protocols */
1411 unsigned char mountpoint_len; /**< length of mountpoint string */
1412
1413 const char *basic_auth_login_file;
1414 /**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */
1415
1416 const char *cgi_chroot_path;
1417 /**< NULL, or chroot patch for child cgi process */
1418
1419 const char *cgi_wd;
1420 /**< working directory to cd to after fork of a cgi process,
1421 * NULL defaults to /tmp
1422 */
1423
1424 const struct lws_protocol_vhost_options *headers;
1425 /**< NULL, or pointer to optional linked list of
1426 * canned headers that are added to server responses.
1427 * If given, these override the headers given at
1428 * the vhost and are used instead of those when
1429 * the mountpoint matches. This allows to control,
1430 * eg, CSP on a per-mount basis.
1431 */
1432 unsigned int keepalive_timeout;
1433 /**< 0 or seconds http stream should stay alive while
1434 * idle. 0 means use the vhost value for keepalive_timeout.
1435 */
1436
1437 /* Add new things just above here ---^
1438 * This is part of the ABI, don't needlessly break compatibility
1439 */
1440};
1441
1442LWS_VISIBLE LWS_EXTERN void
1443lws_vhost_set_mounts(struct lws_vhost *v, const struct lws_http_mount *mounts);
1444
1445///@}
1446///@}
1447