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
251struct lws_plat_file_ops;
252struct lws_ss_policy;
253struct lws_ss_plugin;
254struct lws_metric_policy;
255
256typedef int (*lws_context_ready_cb_t)(struct lws_context *context);
257
258typedef 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 */
271struct 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 void *client_ssl_ca_mem;
511 /**< VHOST: Client SSL context init: CA certificate memory buffer or
512 * NULL... use this to load CA cert from memory instead of file */
513
514 const char *client_ssl_cipher_list;
515 /**< VHOST: Client SSL context init: List of valid ciphers to use (eg,
516 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
517 * or you can leave it as NULL to get "DEFAULT" */
518 const char *client_tls_1_3_plus_cipher_list;
519 /**< VHOST: List of valid ciphers to use for outgoing client connections
520 * ON TLS1.3 AND ABOVE on this vhost (eg,
521 * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get
522 * "DEFAULT".
523 */
524
525 long ssl_client_options_set;
526 /**< VHOST: Any bits set here will be set as CLIENT SSL options */
527 long ssl_client_options_clear;
528 /**< VHOST: Any bits set here will be cleared as CLIENT SSL options */
529
530
531 unsigned int client_ssl_ca_mem_len;
532 /**< VHOST: Client SSL context init: length of client_ssl_ca_mem in
533 * bytes */
534 unsigned int client_ssl_key_mem_len;
535 /**< VHOST: Client SSL context init: length of client_ssl_key_mem in
536 * bytes */
537
538#endif
539
540#if !defined(LWS_WITH_MBEDTLS)
541 SSL_CTX *provided_client_ssl_ctx;
542 /**< CONTEXT: If non-null, swap out libwebsockets ssl
543 * implementation for the one provided by provided_ssl_ctx.
544 * Libwebsockets no longer is responsible for freeing the context
545 * if this option is selected. */
546#else /* WITH_MBEDTLS */
547 const char *mbedtls_client_preload_filepath;
548 /**< CONTEXT: If NULL, no effect. Otherwise it should point to a
549 * filepath where every created client SSL_CTX is preloaded from the
550 * system trust bundle.
551 *
552 * This sets a processwide variable that affects all contexts.
553 *
554 * Requires that the mbedtls provides mbedtls_x509_crt_parse_file(),
555 * else disabled.
556 */
557#endif
558#endif
559
560 int ka_time;
561 /**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
562 * timeout to all libwebsocket sockets, client or server */
563 int ka_probes;
564 /**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
565 * times to try to get a response from the peer before giving up
566 * and killing the connection */
567 int ka_interval;
568 /**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
569 * attempt */
570 unsigned int timeout_secs;
571 /**< VHOST: various processes involving network roundtrips in the
572 * library are protected from hanging forever by timeouts. If
573 * nonzero, this member lets you set the timeout used in seconds.
574 * Otherwise a default timeout is used. */
575 unsigned int connect_timeout_secs;
576 /**< VHOST: client connections have this long to find a working server
577 * from the DNS results, or the whole connection times out. If zero,
578 * a default timeout is used */
579 int bind_iface;
580 /**< VHOST: nonzero to strictly bind sockets to the interface name in
581 * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
582 *
583 * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW
584 * capability.
585 *
586 * Notice that common things like access network interface IP from
587 * your local machine use your lo / loopback interface and will be
588 * disallowed by this.
589 */
590 unsigned int timeout_secs_ah_idle;
591 /**< VHOST: seconds to allow a client to hold an ah without using it.
592 * 0 defaults to 10s. */
593#endif /* WITH_NETWORK */
594
595#if defined(LWS_WITH_TLS_SESSIONS)
596 uint32_t tls_session_timeout;
597 /**< VHOST: seconds until timeout/ttl for newly created sessions.
598 * 0 means default timeout (defined per protocol, usually 300s). */
599 uint32_t tls_session_cache_max;
600 /**< VHOST: 0 for default limit of 10, or the maximum number of
601 * client tls sessions we are willing to cache */
602#endif
603
604 gid_t gid;
605 /**< CONTEXT: group id to change to after setting listen socket,
606 * or -1. See also .username below. */
607 uid_t uid;
608 /**< CONTEXT: user id to change to after setting listen socket,
609 * or -1. See also .groupname below. */
610 uint64_t options;
611 /**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
612 void *user;
613 /**< VHOST + CONTEXT: optional user pointer that will be associated
614 * with the context when creating the context (and can be retrieved by
615 * lws_context_user(context), or with the vhost when creating the vhost
616 * (and can be retrieved by lws_vhost_user(vhost)). You will need to
617 * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately
618 * if you care about giving the context and vhost different user pointer
619 * values.
620 */
621 unsigned int count_threads;
622 /**< CONTEXT: how many contexts to create in an array, 0 = 1 */
623 unsigned int fd_limit_per_thread;
624 /**< CONTEXT: nonzero means restrict each service thread to this
625 * many fds, 0 means the default which is divide the process fd
626 * limit by the number of threads.
627 *
628 * Note if this is nonzero, and fd_limit_per_thread multiplied by the
629 * number of service threads is less than the process ulimit, then lws
630 * restricts internal lookup table allocation to the smaller size, and
631 * switches to a less efficient lookup scheme. You should use this to
632 * trade off speed against memory usage if you know the lws context
633 * will only use a handful of fds.
634 *
635 * Bear in mind lws may use some fds internally, for example for the
636 * cancel pipe, so you may need to allow for some extras for normal
637 * operation.
638 */
639 const char *vhost_name;
640 /**< VHOST: name of vhost, must match external DNS name used to
641 * access the site, like "warmcat.com" as it's used to match
642 * Host: header and / or SNI name for SSL.
643 * CONTEXT: NULL, or the name to associate with the context for
644 * context-specific logging
645 */
646#if defined(LWS_WITH_PLUGINS)
647 const char * const *plugin_dirs;
648 /**< CONTEXT: NULL, or NULL-terminated array of directories to
649 * scan for lws protocol plugins at context creation time */
650#endif
651 void *external_baggage_free_on_destroy;
652 /**< CONTEXT: NULL, or pointer to something externally malloc'd, that
653 * should be freed when the context is destroyed. This allows you to
654 * automatically sync the freeing action to the context destruction
655 * action, so there is no need for an external free() if the context
656 * succeeded to create.
657 */
658
659
660 unsigned int pt_serv_buf_size;
661 /**< CONTEXT: 0 = default of 4096. This buffer is used by
662 * various service related features including file serving, it
663 * defines the max chunk of file that can be sent at once.
664 * At the risk of lws having to buffer failed large sends, it
665 * can be increased to, eg, 128KiB to improve throughput. */
666#if defined(LWS_WITH_FILE_OPS)
667 const struct lws_plat_file_ops *fops;
668 /**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
669 * by a sentinel with NULL .open.
670 *
671 * If NULL, lws provides just the platform file operations struct for
672 * backwards compatibility.
673 */
674#endif
675
676#if defined(LWS_WITH_SOCKS5)
677 const char *socks_proxy_address;
678 /**< VHOST: If non-NULL, attempts to proxy via the given address.
679 * If proxy auth is required, use format
680 * "username:password\@server:port" */
681 unsigned int socks_proxy_port;
682 /**< VHOST: If socks_proxy_address was non-NULL, uses this port
683 * if nonzero, otherwise requires "server:port" in .socks_proxy_address
684 */
685#endif
686
687#if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
688 cap_value_t caps[4];
689 /**< CONTEXT: array holding Linux capabilities you want to
690 * continue to be available to the server after it transitions
691 * to a noprivileged user. Usually none are needed but for, eg,
692 * .bind_iface, CAP_NET_RAW is required. This gives you a way
693 * to still have the capability but drop root.
694 */
695 char count_caps;
696 /**< CONTEXT: count of Linux capabilities in .caps[]. 0 means
697 * no capabilities will be inherited from root (the default) */
698#endif
699 void **foreign_loops;
700 /**< CONTEXT: This is ignored if the context is not being started with
701 * an event loop, ie, .options has a flag like
702 * LWS_SERVER_OPTION_LIBUV.
703 *
704 * NULL indicates lws should start its own even loop for
705 * each service thread, and deal with closing the loops
706 * when the context is destroyed.
707 *
708 * Non-NULL means it points to an array of external
709 * ("foreign") event loops that are to be used in turn for
710 * each service thread. In the default case of 1 service
711 * thread, it can just point to one foreign event loop.
712 */
713 void (*signal_cb)(void *event_lib_handle, int signum);
714 /**< CONTEXT: NULL: default signal handling. Otherwise this receives
715 * the signal handler callback. event_lib_handle is the
716 * native event library signal handle, eg uv_signal_t *
717 * for libuv.
718 */
719 struct lws_context **pcontext;
720 /**< CONTEXT: if non-NULL, at the end of context destroy processing,
721 * the pointer pointed to by pcontext is written with NULL. You can
722 * use this to let foreign event loops know that lws context destruction
723 * is fully completed.
724 */
725 void (*finalize)(struct lws_vhost *vh, void *arg);
726 /**< VHOST: NULL, or pointer to function that will be called back
727 * when the vhost is just about to be freed. The arg parameter
728 * will be set to whatever finalize_arg is below.
729 */
730 void *finalize_arg;
731 /**< VHOST: opaque pointer lws ignores but passes to the finalize
732 * callback. If you don't care, leave it NULL.
733 */
734 const char *listen_accept_role;
735 /**< VHOST: NULL for default, or force accepted incoming connections to
736 * bind to this role. Uses the role names from their ops struct, eg,
737 * "raw-skt".
738 */
739 const char *listen_accept_protocol;
740 /**< VHOST: NULL for default, or force accepted incoming connections to
741 * bind to this vhost protocol name.
742 */
743 const struct lws_protocols **pprotocols;
744 /**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use
745 * this array of pointers to protocols structs. The end of the array
746 * is marked by a NULL pointer.
747 *
748 * This is preferred over .protocols, because it allows the protocol
749 * struct to be opaquely defined elsewhere, with just a pointer to it
750 * needed to create the context with it. .protocols requires also
751 * the type of the user data to be known so its size can be given.
752 */
753
754 const char *username; /**< CONTEXT: string username for post-init
755 * permissions. Like .uid but takes a string username. */
756 const char *groupname; /**< CONTEXT: string groupname for post-init
757 * permissions. Like .gid but takes a string groupname. */
758 const char *unix_socket_perms; /**< VHOST: if your vhost is listening
759 * on a unix socket, you can give a "username:groupname" string here
760 * to control the owner:group it's created with. It's always created
761 * with 0660 mode. */
762 const lws_system_ops_t *system_ops;
763 /**< CONTEXT: hook up lws_system_ apis to system-specific
764 * implementations */
765 const lws_retry_bo_t *retry_and_idle_policy;
766 /**< VHOST: optional retry and idle policy to apply to this vhost.
767 * Currently only the idle parts are applied to the connections.
768 */
769#if defined(LWS_WITH_SYS_STATE)
770 lws_state_notify_link_t * const *register_notifier_list;
771 /**< CONTEXT: NULL, or pointer to an array of notifiers that should
772 * be registered during context creation, so they can see state change
773 * events from very early on. The array should end with a NULL. */
774#endif
775#if defined(LWS_WITH_SECURE_STREAMS)
776#if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
777 const struct lws_ss_policy *pss_policies; /**< CONTEXT: point to first
778 * in a linked-list of streamtype policies prepared by user code */
779#else
780 const char *pss_policies_json; /**< CONTEXT: point to a string
781 * containing a JSON description of the secure streams policies. Set
782 * to NULL if not using Secure Streams.
783 * If the platform supports files and the string does not begin with
784 * '{', lws treats the string as a filepath to open to get the JSON
785 * policy.
786 */
787#endif
788 const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array
789 * of pointers to plugin structs here, terminated with a NULL ptr.
790 * Set to NULL if not using Secure Streams. */
791 const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0:
792 * point to a string giving the Unix Domain Socket address to use (start
793 * with @ for abstract namespace), ss_proxy_port nonzero: set the
794 * network interface address (not name, it's ambiguous for ipv4/6) to
795 * bind the tcp connection to the proxy to */
796 const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port
797 * nonzero: the tcp address of the ss proxy to connect to */
798 uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a
799 * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else
800 * the socket path given in ss_proxy_bind (start it with a + or +@);
801 * nonzero means connect via a tcp socket to the tcp address in
802 * ss_proxy_bind and the given port */
803#endif
804
805 int rlimit_nofile;
806 /**< 0 = inherit the initial ulimit for files / sockets from the startup
807 * environment. Nonzero = try to set the limit for this process.
808 */
809#if defined(LWS_WITH_PEER_LIMITS)
810 lws_peer_limits_notify_t pl_notify_cb;
811 /**< CONTEXT: NULL, or a callback to receive notifications each time a
812 * connection is being dropped because of peer limits.
813 *
814 * The callback provides the context, and an lws_sockaddr46 with the
815 * peer address and port.
816 */
817 unsigned short ip_limit_ah;
818 /**< CONTEXT: max number of ah a single IP may use simultaneously
819 * 0 is no limit. This is a soft limit: if the limit is
820 * reached, connections from that IP will wait in the ah
821 * waiting list and not be able to acquire an ah until
822 * a connection belonging to the IP relinquishes one it
823 * already has.
824 */
825 unsigned short ip_limit_wsi;
826 /**< CONTEXT: max number of wsi a single IP may use simultaneously.
827 * 0 is no limit. This is a hard limit, connections from
828 * the same IP will simply be dropped once it acquires the
829 * amount of simultaneous wsi / accepted connections
830 * given here.
831 */
832
833#endif /* PEER_LIMITS */
834
835#if defined(LWS_WITH_SYS_FAULT_INJECTION)
836 lws_fi_ctx_t fic;
837 /**< CONTEXT | VHOST: attach external Fault Injection context to the
838 * lws_context or vhost. If creating the context + default vhost in
839 * one step, only the context binds to \p fi. When creating a vhost
840 * otherwise this can bind to the vhost so the faults can be injected
841 * from the start.
842 */
843#endif
844
845#if defined(LWS_WITH_SYS_SMD)
846 lws_smd_notification_cb_t early_smd_cb;
847 /**< CONTEXT: NULL, or an smd notification callback that will be registered
848 * immediately after the smd in the context is initialized. This ensures
849 * you can get all notifications without having to intercept the event loop
850 * creation, eg, when using an event library. Other callbacks can be
851 * registered later manually without problems.
852 */
853 void *early_smd_opaque;
854 lws_smd_class_t early_smd_class_filter;
855 lws_usec_t smd_ttl_us;
856 /**< CONTEXT: SMD messages older than this many us are removed from the
857 * queue and destroyed even if not fully delivered yet. If zero,
858 * defaults to 2 seconds (5 second for FREERTOS).
859 */
860 uint16_t smd_queue_depth;
861 /**< CONTEXT: Maximum queue depth, If zero defaults to 40
862 * (20 for FREERTOS) */
863#endif
864
865#if defined(LWS_WITH_SYS_METRICS)
866 const struct lws_metric_policy *metrics_policies;
867 /**< CONTEXT: non-SS policy metrics policies */
868 const char *metrics_prefix;
869 /**< CONTEXT: prefix for this context's metrics, used to distinguish
870 * metrics pooled from different processes / applications, so, eg what
871 * would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is
872 * set to "myapp". Policies are applied using the name with the prefix,
873 * if present.
874 */
875#endif
876
877 int fo_listen_queue;
878 /**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the
879 * platform supports it, with the given queue length for the listen
880 * socket.
881 */
882
883 const struct lws_plugin_evlib *event_lib_custom;
884 /**< CONTEXT: If non-NULL, override event library selection so it uses
885 * this custom event library implementation, instead of default internal
886 * loop. Don't set any other event lib context creation flags in that
887 * case. it will be used automatically. This is useful for integration
888 * where an existing application is using its own handrolled event loop
889 * instead of an event library, it provides a way to allow lws to use
890 * the custom event loop natively as if it were an "event library".
891 */
892
893#if defined(LWS_WITH_TLS_JIT_TRUST)
894 size_t jitt_cache_max_footprint;
895 /**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache...
896 * LRU items are evicted to keep under this limit */
897 int vh_idle_grace_ms;
898 /**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts
899 * are allowed to live without active connections using them. */
900#endif
901
902 lws_log_cx_t *log_cx;
903 /**< CONTEXT: NULL to use the default, process-scope logging context,
904 * else a specific logging context to associate with this context */
905
906#if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT)
907 const char *http_nsc_filepath;
908 /**< CONTEXT: Filepath to use for http netscape cookiejar file */
909
910 size_t http_nsc_heap_max_footprint;
911 /**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie
912 * cache */
913 size_t http_nsc_heap_max_items;
914 /**< CONTEXT: 0, or the max number of items allowed in the cookie cache
915 * before destroying lru items to keep it under the limit */
916 size_t http_nsc_heap_max_payload;
917 /**< CONTEXT: 0, or the maximum size of a single cookie we are able to
918 * handle */
919#endif
920
921 /* Add new things just above here ---^
922 * This is part of the ABI, don't needlessly break compatibility
923 *
924 * The below is to ensure later library versions with new
925 * members added above will see 0 (default) even if the app
926 * was not built against the newer headers.
927 */
928
929 void *_unused[2]; /**< dummy */
930};
931
932/**
933 * lws_create_context() - Create the websocket handler
934 * \param info: pointer to struct with parameters
935 *
936 * This function creates the listening socket (if serving) and takes care
937 * of all initialization in one step.
938 *
939 * If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
940 * created; you're expected to create your own vhosts afterwards using
941 * lws_create_vhost(). Otherwise a vhost named "default" is also created
942 * using the information in the vhost-related members, for compatibility.
943 *
944 * After initialization, it returns a struct lws_context * that
945 * represents this server. After calling, user code needs to take care
946 * of calling lws_service() with the context pointer to get the
947 * server's sockets serviced. This must be done in the same process
948 * context as the initialization call.
949 *
950 * The protocol callback functions are called for a handful of events
951 * including http requests coming in, websocket connections becoming
952 * established, and data arriving; it's also called periodically to allow
953 * async transmission.
954 *
955 * HTTP requests are sent always to the FIRST protocol in protocol, since
956 * at that time websocket protocol has not been negotiated. Other
957 * protocols after the first one never see any HTTP callback activity.
958 *
959 * The server created is a simple http server by default; part of the
960 * websocket standard is upgrading this http connection to a websocket one.
961 *
962 * This allows the same server to provide files like scripts and favicon /
963 * images or whatever over http and dynamic data over websockets all in
964 * one place; they're all handled in the user callback.
965 */
966LWS_VISIBLE LWS_EXTERN struct lws_context *
967lws_create_context(const struct lws_context_creation_info *info);
968
969
970/**
971 * lws_context_destroy() - Destroy the websocket context
972 * \param context: Websocket context
973 *
974 * This function closes any active connections and then frees the
975 * context. After calling this, any further use of the context is
976 * undefined.
977 */
978LWS_VISIBLE LWS_EXTERN void
979lws_context_destroy(struct lws_context *context);
980
981typedef int (*lws_reload_func)(void);
982
983/**
984 * lws_context_deprecate() - Deprecate the websocket context
985 *
986 * \param context: Websocket context
987 * \param cb: Callback notified when old context listen sockets are closed
988 *
989 * This function is used on an existing context before superceding it
990 * with a new context.
991 *
992 * It closes any listen sockets in the context, so new connections are
993 * not possible.
994 *
995 * And it marks the context to be deleted when the number of active
996 * connections into it falls to zero.
997 *
998 * This is aimed at allowing seamless configuration reloads.
999 *
1000 * The callback cb will be called after the listen sockets are actually
1001 * closed and may be reopened. In the callback the new context should be
1002 * configured and created. (With libuv, socket close happens async after
1003 * more loop events).
1004 */
1005LWS_VISIBLE LWS_EXTERN void
1006lws_context_deprecate(struct lws_context *context, lws_reload_func cb);
1007
1008LWS_VISIBLE LWS_EXTERN int
1009lws_context_is_deprecated(struct lws_context *context);
1010
1011/**
1012 * lws_set_proxy() - Setups proxy to lws_context.
1013 * \param vhost: pointer to struct lws_vhost you want set proxy for
1014 * \param proxy: pointer to c string containing proxy in format address:port
1015 *
1016 * Returns 0 if proxy string was parsed and proxy was setup.
1017 * Returns -1 if proxy is NULL or has incorrect format.
1018 *
1019 * This is only required if your OS does not provide the http_proxy
1020 * environment variable (eg, OSX)
1021 *
1022 * IMPORTANT! You should call this function right after creation of the
1023 * lws_context and before call to connect. If you call this
1024 * function after connect behavior is undefined.
1025 * This function will override proxy settings made on lws_context
1026 * creation with genenv() call.
1027 */
1028LWS_VISIBLE LWS_EXTERN int
1029lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
1030
1031/**
1032 * lws_set_socks() - Setup socks to lws_context.
1033 * \param vhost: pointer to struct lws_vhost you want set socks for
1034 * \param socks: pointer to c string containing socks in format address:port
1035 *
1036 * Returns 0 if socks string was parsed and socks was setup.
1037 * Returns -1 if socks is NULL or has incorrect format.
1038 *
1039 * This is only required if your OS does not provide the socks_proxy
1040 * environment variable (eg, OSX)
1041 *
1042 * IMPORTANT! You should call this function right after creation of the
1043 * lws_context and before call to connect. If you call this
1044 * function after connect behavior is undefined.
1045 * This function will override proxy settings made on lws_context
1046 * creation with genenv() call.
1047 */
1048LWS_VISIBLE LWS_EXTERN int
1049lws_set_socks(struct lws_vhost *vhost, const char *socks);
1050
1051struct lws_vhost;
1052
1053/**
1054 * lws_create_vhost() - Create a vhost (virtual server context)
1055 * \param context: pointer to result of lws_create_context()
1056 * \param info: pointer to struct with parameters
1057 *
1058 * This function creates a virtual server (vhost) using the vhost-related
1059 * members of the info struct. You can create many vhosts inside one context
1060 * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
1061 */
1062LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1063lws_create_vhost(struct lws_context *context,
1064 const struct lws_context_creation_info *info);
1065
1066/**
1067 * lws_vhost_destroy() - Destroy a vhost (virtual server context)
1068 *
1069 * \param vh: pointer to result of lws_create_vhost()
1070 *
1071 * This function destroys a vhost. Normally, if you just want to exit,
1072 * then lws_destroy_context() will take care of everything. If you want
1073 * to destroy an individual vhost and all connections and allocations, you
1074 * can do it with this.
1075 *
1076 * If the vhost has a listen sockets shared by other vhosts, it will be given
1077 * to one of the vhosts sharing it rather than closed.
1078 *
1079 * The vhost close is staged according to the needs of the event loop, and if
1080 * there are multiple service threads. At the point the vhost itself if
1081 * about to be freed, if you provided a finalize callback and optional arg at
1082 * vhost creation time, it will be called just before the vhost is freed.
1083 */
1084LWS_VISIBLE LWS_EXTERN void
1085lws_vhost_destroy(struct lws_vhost *vh);
1086
1087/**
1088 * lwsws_get_config_globals() - Parse a JSON server config file
1089 * \param info: pointer to struct with parameters
1090 * \param d: filepath of the config file
1091 * \param config_strings: storage for the config strings extracted from JSON,
1092 * the pointer is incremented as strings are stored
1093 * \param len: pointer to the remaining length left in config_strings
1094 * the value is decremented as strings are stored
1095 *
1096 * This function prepares a n lws_context_creation_info struct with global
1097 * settings from a file d.
1098 *
1099 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1100 */
1101LWS_VISIBLE LWS_EXTERN int
1102lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
1103 char **config_strings, int *len);
1104
1105/**
1106 * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
1107 * \param context: pointer to result of lws_create_context()
1108 * \param info: pointer to struct with parameters
1109 * \param d: filepath of the config file
1110 * \param config_strings: storage for the config strings extracted from JSON,
1111 * the pointer is incremented as strings are stored
1112 * \param len: pointer to the remaining length left in config_strings
1113 * the value is decremented as strings are stored
1114 *
1115 * This function creates vhosts into a context according to the settings in
1116 *JSON files found in directory d.
1117 *
1118 * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
1119 */
1120LWS_VISIBLE LWS_EXTERN int
1121lwsws_get_config_vhosts(struct lws_context *context,
1122 struct lws_context_creation_info *info, const char *d,
1123 char **config_strings, int *len);
1124
1125/**
1126 * lws_get_vhost() - return the vhost a wsi belongs to
1127 *
1128 * \param wsi: which connection
1129 */
1130LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1131lws_get_vhost(struct lws *wsi);
1132
1133/**
1134 * lws_get_vhost_name() - returns the name of a vhost
1135 *
1136 * \param vhost: which vhost
1137 */
1138LWS_VISIBLE LWS_EXTERN const char *
1139lws_get_vhost_name(struct lws_vhost *vhost);
1140
1141/**
1142 * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
1143 *
1144 * \param context: the lws_context to look in
1145 * \param name: vhost name we are looking for
1146 *
1147 * Returns NULL, or the vhost with the name \p name
1148 */
1149LWS_VISIBLE LWS_EXTERN struct lws_vhost *
1150lws_get_vhost_by_name(struct lws_context *context, const char *name);
1151
1152/**
1153 * lws_get_vhost_port() - returns the port a vhost listens on, or -1
1154 *
1155 * \param vhost: which vhost
1156 */
1157LWS_VISIBLE LWS_EXTERN int
1158lws_get_vhost_port(struct lws_vhost *vhost);
1159
1160/**
1161 * lws_get_vhost_user() - returns the user pointer for the vhost
1162 *
1163 * \param vhost: which vhost
1164 */
1165LWS_VISIBLE LWS_EXTERN void *
1166lws_get_vhost_user(struct lws_vhost *vhost);
1167
1168/**
1169 * lws_get_vhost_iface() - returns the binding for the vhost listen socket
1170 *
1171 * \param vhost: which vhost
1172 */
1173LWS_VISIBLE LWS_EXTERN const char *
1174lws_get_vhost_iface(struct lws_vhost *vhost);
1175
1176/**
1177 * lws_json_dump_vhost() - describe vhost state and stats in JSON
1178 *
1179 * \param vh: the vhost
1180 * \param buf: buffer to fill with JSON
1181 * \param len: max length of buf
1182 */
1183LWS_VISIBLE LWS_EXTERN int
1184lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
1185
1186/**
1187 * lws_json_dump_context() - describe context state and stats in JSON
1188 *
1189 * \param context: the context
1190 * \param buf: buffer to fill with JSON
1191 * \param len: max length of buf
1192 * \param hide_vhosts: nonzero to not provide per-vhost mount etc information
1193 *
1194 * Generates a JSON description of vhost state into buf
1195 */
1196LWS_VISIBLE LWS_EXTERN int
1197lws_json_dump_context(const struct lws_context *context, char *buf, int len,
1198 int hide_vhosts);
1199
1200/**
1201 * lws_vhost_user() - get the user data associated with the vhost
1202 * \param vhost: Websocket vhost
1203 *
1204 * This returns the optional user pointer that can be attached to
1205 * a vhost when it was created. Lws never dereferences this pointer, it only
1206 * sets it when the vhost is created, and returns it using this api.
1207 */
1208LWS_VISIBLE LWS_EXTERN void *
1209lws_vhost_user(struct lws_vhost *vhost);
1210
1211/**
1212 * lws_context_user() - get the user data associated with the context
1213 * \param context: Websocket context
1214 *
1215 * This returns the optional user allocation that can be attached to
1216 * the context the sockets live in at context_create time. It's a way
1217 * to let all sockets serviced in the same context share data without
1218 * using globals statics in the user code.
1219 */
1220LWS_VISIBLE LWS_EXTERN void *
1221lws_context_user(struct lws_context *context);
1222
1223LWS_VISIBLE LWS_EXTERN const char *
1224lws_vh_tag(struct lws_vhost *vh);
1225
1226/**
1227 * lws_context_is_being_destroyed() - find out if context is being destroyed
1228 *
1229 * \param context: the struct lws_context pointer
1230 *
1231 * Returns nonzero if the context has had lws_context_destroy() called on it...
1232 * when using event library loops the destroy process can be asynchronous. In
1233 * the special case of libuv foreign loops, the failure to create the context
1234 * may have to do work on the foreign loop to reverse the partial creation,
1235 * meaning a failed context create cannot unpick what it did and return NULL.
1236 *
1237 * In that condition, a valid context that is already started the destroy
1238 * process is returned, and this test api will return nonzero as a way to
1239 * find out the create is in the middle of failing.
1240 */
1241LWS_VISIBLE LWS_EXTERN int
1242lws_context_is_being_destroyed(struct lws_context *context);
1243
1244/*! \defgroup vhost-mounts Vhost mounts and options
1245 * \ingroup context-and-vhost-creation
1246 *
1247 * ##Vhost mounts and options
1248 */
1249///@{
1250/** struct lws_protocol_vhost_options - linked list of per-vhost protocol
1251 * name=value options
1252 *
1253 * This provides a general way to attach a linked-list of name=value pairs,
1254 * which can also have an optional child link-list using the options member.
1255 */
1256struct lws_protocol_vhost_options {
1257 const struct lws_protocol_vhost_options *next; /**< linked list */
1258 const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */
1259 const char *name; /**< name of name=value pair */
1260 const char *value; /**< value of name=value pair */
1261};
1262
1263/** enum lws_mount_protocols
1264 * This specifies the mount protocol for a mountpoint, whether it is to be
1265 * served from a filesystem, or it is a cgi etc.
1266 */
1267enum lws_mount_protocols {
1268 LWSMPRO_HTTP = 0, /**< http reverse proxy */
1269 LWSMPRO_HTTPS = 1, /**< https reverse proxy */
1270 LWSMPRO_FILE = 2, /**< serve from filesystem directory */
1271 LWSMPRO_CGI = 3, /**< pass to CGI to handle */
1272 LWSMPRO_REDIR_HTTP = 4, /**< redirect to http:// url */
1273 LWSMPRO_REDIR_HTTPS = 5, /**< redirect to https:// url */
1274 LWSMPRO_CALLBACK = 6, /**< hand by named protocol's callback */
1275};
1276
1277/** enum lws_authentication_mode
1278 * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter
1279 * is ignored unless LWSAUTHM_DEFAULT is set.
1280 */
1281enum lws_authentication_mode {
1282 LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */
1283 LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */
1284};
1285
1286/** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */
1287#define AUTH_MODE_MASK 0xF0000000
1288
1289/** struct lws_http_mount
1290 *
1291 * arguments for mounting something in a vhost's url namespace
1292 */
1293struct lws_http_mount {
1294 const struct lws_http_mount *mount_next;
1295 /**< pointer to next struct lws_http_mount */
1296 const char *mountpoint;
1297 /**< mountpoint in http pathspace, eg, "/" */
1298 const char *origin;
1299 /**< path to be mounted, eg, "/var/www/warmcat.com" */
1300 const char *def;
1301 /**< default target, eg, "index.html" */
1302 const char *protocol;
1303 /**<"protocol-name" to handle mount */
1304
1305 const struct lws_protocol_vhost_options *cgienv;
1306 /**< optional linked-list of cgi options. These are created
1307 * as environment variables for the cgi process
1308 */
1309 const struct lws_protocol_vhost_options *extra_mimetypes;
1310 /**< optional linked-list of mimetype mappings */
1311 const struct lws_protocol_vhost_options *interpret;
1312 /**< optional linked-list of files to be interpreted */
1313
1314 int cgi_timeout;
1315 /**< seconds cgi is allowed to live, if cgi://mount type */
1316 int cache_max_age;
1317 /**< max-age for reuse of client cache of files, seconds */
1318 unsigned int auth_mask;
1319 /**< bits set here must be set for authorized client session */
1320
1321 unsigned int cache_reusable:1; /**< set if client cache may reuse this */
1322 unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */
1323 unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */
1324
1325 unsigned char origin_protocol; /**< one of enum lws_mount_protocols */
1326 unsigned char mountpoint_len; /**< length of mountpoint string */
1327
1328 const char *basic_auth_login_file;
1329 /**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */
1330
1331 /* Add new things just above here ---^
1332 * This is part of the ABI, don't needlessly break compatibility
1333 */
1334};
1335
1336///@}
1337///@}
1338