• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2019 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 	/****** add new things just above ---^ ******/
225 
226 
227 #define lws_check_opt(c, f) ((((uint64_t)c) & ((uint64_t)f)) == ((uint64_t)f))
228 
229 struct lws_plat_file_ops;
230 struct lws_ss_policy;
231 struct lws_ss_plugin;
232 
233 typedef int (*lws_context_ready_cb_t)(struct lws_context *context);
234 
235 /** struct lws_context_creation_info - parameters to create context and /or vhost with
236  *
237  * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS
238  * is not given, then for backwards compatibility one vhost is created at
239  * context-creation time using the info from this struct.
240  *
241  * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created
242  * at the same time as the context, they are expected to be created afterwards.
243  */
244 struct lws_context_creation_info {
245 	int port;
246 	/**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress
247 	 * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are
248 	 * writing a server but you are using \ref sock-adopt instead of the
249 	 * built-in listener.
250 	 *
251 	 * You can also set port to 0, in which case the kernel will pick
252 	 * a random port that is not already in use.  You can find out what
253 	 * port the vhost is listening on using lws_get_vhost_listen_port() */
254 	const char *iface;
255 	/**< VHOST: NULL to bind the listen socket to all interfaces, or the
256 	 * interface name, eg, "eth2"
257 	 * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is
258 	 * the pathname of a UNIX domain socket. you can use the UNIX domain
259 	 * sockets in abstract namespace, by prepending an at symbol to the
260 	 * socket name. */
261 	const struct lws_protocols *protocols;
262 	/**< VHOST: Array of structures listing supported protocols and a
263 	 * protocol-specific callback for each one.  The list is ended with an
264 	 * entry that has a NULL callback pointer.  SEE ALSO .pprotocols below,
265 	 * which gives an alternative way to provide an array of pointers to
266 	 * protocol structs. */
267 	const struct lws_extension *extensions;
268 	/**< VHOST: NULL or array of lws_extension structs listing the
269 	 * extensions this context supports. */
270 	const struct lws_token_limits *token_limits;
271 	/**< CONTEXT: NULL or struct lws_token_limits pointer which is
272 	 * initialized with a token length limit for each possible WSI_TOKEN_ */
273 	const char *ssl_private_key_password;
274 	/**< VHOST: NULL or the passphrase needed for the private key. (For
275 	 * backwards compatibility, this can also be used to pass the client
276 	 * cert passphrase when setting up a vhost client SSL context, but it is
277 	 * preferred to use .client_ssl_private_key_password for that.) */
278 	const char *ssl_cert_filepath;
279 	/**< VHOST: If libwebsockets was compiled to use ssl, and you want
280 	 * to listen using SSL, set to the filepath to fetch the
281 	 * server cert from, otherwise NULL for unencrypted.  (For backwards
282 	 * compatibility, this can also be used to pass the client certificate
283 	 * when setting up a vhost client SSL context, but it is preferred to
284 	 * use .client_ssl_cert_filepath for that.)
285 	 *
286 	 * Notice you can alternatively set a single DER or PEM from a memory
287 	 * buffer as the vhost tls cert using \p server_ssl_cert_mem and
288 	 * \p server_ssl_cert_mem_len.
289 	 */
290 	const char *ssl_private_key_filepath;
291 	/**<  VHOST: filepath to private key if wanting SSL mode;
292 	 * if this is set to NULL but ssl_cert_filepath is set, the
293 	 * OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called
294 	 * to allow setting of the private key directly via openSSL
295 	 * library calls.   (For backwards compatibility, this can also be used
296 	 * to pass the client cert private key filepath when setting up a
297 	 * vhost client SSL context, but it is preferred to use
298 	 * .client_ssl_private_key_filepath for that.)
299 	 *
300 	 * Notice you can alternatively set a DER or PEM private key from a
301 	 * memory buffer as the vhost tls private key using
302 	 * \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len.
303 	 */
304 	const char *ssl_ca_filepath;
305 	/**< VHOST: CA certificate filepath or NULL.  (For backwards
306 	 * compatibility, this can also be used to pass the client CA
307 	 * filepath when setting up a vhost client SSL context,
308 	 * but it is preferred to use .client_ssl_ca_filepath for that.)
309 	 *
310 	 * Notice you can alternatively set a DER or PEM CA cert from a memory
311 	 * buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len.
312 	 */
313 	const char *ssl_cipher_list;
314 	/**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg,
315 	 * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
316 	 * or you can leave it as NULL to get "DEFAULT" (For backwards
317 	 * compatibility, this can also be used to pass the client cipher
318 	 * list when setting up a vhost client SSL context,
319 	 * but it is preferred to use .client_ssl_cipher_list for that.)
320 	 * SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list
321 	 * for the equivalent for tls1.3.
322 	 */
323 	const char *http_proxy_address;
324 	/**< VHOST: If non-NULL, attempts to proxy via the given address.
325 	 * If proxy auth is required, use format
326 	 * "username:password\@server:port" */
327 	unsigned int http_proxy_port;
328 	/**< VHOST: If http_proxy_address was non-NULL, uses this port */
329 	int gid;
330 	/**< CONTEXT: group id to change to after setting listen socket,
331 	 *   or -1. See also .username below. */
332 	int uid;
333 	/**< CONTEXT: user id to change to after setting listen socket,
334 	 *   or -1.  See also .groupname below. */
335 	uint64_t options;
336 	/**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */
337 	void *user;
338 	/**< VHOST + CONTEXT: optional user pointer that will be associated
339 	 * with the context when creating the context (and can be retrieved by
340 	 * lws_context_user(context), or with the vhost when creating the vhost
341 	 * (and can be retrieved by lws_vhost_user(vhost)).  You will need to
342 	 * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately
343 	 * if you care about giving the context and vhost different user pointer
344 	 * values.
345 	 */
346 	int ka_time;
347 	/**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive
348 	 * timeout to all libwebsocket sockets, client or server */
349 	int ka_probes;
350 	/**< CONTEXT: if ka_time was nonzero, after the timeout expires how many
351 	 * times to try to get a response from the peer before giving up
352 	 * and killing the connection */
353 	int ka_interval;
354 	/**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes
355 	 * attempt */
356 #if defined(LWS_WITH_TLS) && !defined(LWS_WITH_MBEDTLS)
357 	SSL_CTX *provided_client_ssl_ctx;
358 	/**< CONTEXT: If non-null, swap out libwebsockets ssl
359 	  * implementation for the one provided by provided_ssl_ctx.
360 	  * Libwebsockets no longer is responsible for freeing the context
361 	  * if this option is selected. */
362 #else /* maintain structure layout either way */
363 	void *provided_client_ssl_ctx; /**< dummy if ssl disabled */
364 #endif
365 
366 	unsigned short max_http_header_data;
367 	/**< CONTEXT: The max amount of header payload that can be handled
368 	 * in an http request (unrecognized header payload is dropped) */
369 	unsigned short max_http_header_pool;
370 	/**< CONTEXT: The max number of connections with http headers that
371 	 * can be processed simultaneously (the corresponding memory is
372 	 * allocated and deallocated dynamically as needed).  If the pool is
373 	 * fully busy new incoming connections must wait for accept until one
374 	 * becomes free. 0 = allow as many ah as number of availble fds for
375 	 * the process */
376 
377 	unsigned int count_threads;
378 	/**< CONTEXT: how many contexts to create in an array, 0 = 1 */
379 	unsigned int fd_limit_per_thread;
380 	/**< CONTEXT: nonzero means restrict each service thread to this
381 	 * many fds, 0 means the default which is divide the process fd
382 	 * limit by the number of threads.
383 	 *
384 	 * Note if this is nonzero, and fd_limit_per_thread multiplied by the
385 	 * number of service threads is less than the process ulimit, then lws
386 	 * restricts internal lookup table allocation to the smaller size, and
387 	 * switches to a less efficient lookup scheme.  You should use this to
388 	 * trade off speed against memory usage if you know the lws context
389 	 * will only use a handful of fds.
390 	 *
391 	 * Bear in mind lws may use some fds internally, for example for the
392 	 * cancel pipe, so you may need to allow for some extras for normal
393 	 * operation.
394 	 */
395 	unsigned int timeout_secs;
396 	/**< VHOST: various processes involving network roundtrips in the
397 	 * library are protected from hanging forever by timeouts.  If
398 	 * nonzero, this member lets you set the timeout used in seconds.
399 	 * Otherwise a default timeout is used. */
400 	const char *ecdh_curve;
401 	/**< VHOST: if NULL, defaults to initializing server with
402 	 *   "prime256v1" */
403 	const char *vhost_name;
404 	/**< VHOST: name of vhost, must match external DNS name used to
405 	 * access the site, like "warmcat.com" as it's used to match
406 	 * Host: header and / or SNI name for SSL. */
407 	const char * const *plugin_dirs;
408 	/**< CONTEXT: NULL, or NULL-terminated array of directories to
409 	 * scan for lws protocol plugins at context creation time */
410 	const struct lws_protocol_vhost_options *pvo;
411 	/**< VHOST: pointer to optional linked list of per-vhost
412 	 * options made accessible to protocols */
413 	int keepalive_timeout;
414 	/**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote
415 	 * client to hold on to an idle HTTP/1.1 connection.  Timeout lifetime
416 	 * applied to idle h2 network connections */
417 	const char *log_filepath;
418 	/**< VHOST: filepath to append logs to... this is opened before
419 	 *		any dropping of initial privileges */
420 	const struct lws_http_mount *mounts;
421 	/**< VHOST: optional linked list of mounts for this vhost */
422 	const char *server_string;
423 	/**< CONTEXT: string used in HTTP headers to identify server
424  *		software, if NULL, "libwebsockets". */
425 	unsigned int pt_serv_buf_size;
426 	/**< CONTEXT: 0 = default of 4096.  This buffer is used by
427 	 * various service related features including file serving, it
428 	 * defines the max chunk of file that can be sent at once.
429 	 * At the risk of lws having to buffer failed large sends, it
430 	 * can be increased to, eg, 128KiB to improve throughput. */
431 	unsigned int max_http_header_data2;
432 	/**< CONTEXT: if max_http_header_data is 0 and this
433 	 * is nonzero, this will be used in place of the default.  It's
434 	 * like this for compatibility with the original short version,
435 	 * this is unsigned int length. */
436 	long ssl_options_set;
437 	/**< VHOST: Any bits set here will be set as server SSL options */
438 	long ssl_options_clear;
439 	/**< VHOST: Any bits set here will be cleared as server SSL options */
440 	unsigned short ws_ping_pong_interval;
441 	/**< CONTEXT: 0 for none, else interval in seconds between sending
442 	 * PINGs on idle websocket connections.  When the PING is sent,
443 	 * the PONG must come within the normal timeout_secs timeout period
444 	 * or the connection will be dropped.
445 	 * Any RX or TX traffic on the connection restarts the interval timer,
446 	 * so a connection which always sends or receives something at intervals
447 	 * less than the interval given here will never send PINGs / expect
448 	 * PONGs.  Conversely as soon as the ws connection is established, an
449 	 * idle connection will do the PING / PONG roundtrip as soon as
450 	 * ws_ping_pong_interval seconds has passed without traffic
451 	 */
452 	const struct lws_protocol_vhost_options *headers;
453 		/**< VHOST: pointer to optional linked list of per-vhost
454 		 * canned headers that are added to server responses */
455 
456 	const struct lws_protocol_vhost_options *reject_service_keywords;
457 	/**< CONTEXT: Optional list of keywords and rejection codes + text.
458 	 *
459 	 * The keywords are checked for existing in the user agent string.
460 	 *
461 	 * Eg, "badrobot" "404 Not Found"
462 	 */
463 	void *external_baggage_free_on_destroy;
464 	/**< CONTEXT: NULL, or pointer to something externally malloc'd, that
465 	 * should be freed when the context is destroyed.  This allows you to
466 	 * automatically sync the freeing action to the context destruction
467 	 * action, so there is no need for an external free() if the context
468 	 * succeeded to create.
469 	 */
470 
471 	const char *client_ssl_private_key_password;
472 	/**< VHOST: Client SSL context init: NULL or the passphrase needed
473 	 * for the private key */
474 	const char *client_ssl_cert_filepath;
475 	/**< VHOST: Client SSL context init: The certificate the client
476 	 * should present to the peer on connection */
477 	const void *client_ssl_cert_mem;
478 	/**< VHOST: Client SSL context init: client certificate memory buffer or
479 	 * NULL... use this to load client cert from memory instead of file */
480 	unsigned int client_ssl_cert_mem_len;
481 	/**< VHOST: Client SSL context init: length of client_ssl_cert_mem in
482 	 * bytes */
483 	const char *client_ssl_private_key_filepath;
484 	/**<  VHOST: Client SSL context init: filepath to client private key
485 	 * if this is set to NULL but client_ssl_cert_filepath is set, you
486 	 * can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS
487 	 * callback of protocols[0] to allow setting of the private key directly
488 	 * via tls library calls */
489 	const char *client_ssl_ca_filepath;
490 	/**< VHOST: Client SSL context init: CA certificate filepath or NULL */
491 	const void *client_ssl_ca_mem;
492 	/**< VHOST: Client SSL context init: CA certificate memory buffer or
493 	 * NULL... use this to load CA cert from memory instead of file */
494 	unsigned int client_ssl_ca_mem_len;
495 	/**< VHOST: Client SSL context init: length of client_ssl_ca_mem in
496 	 * bytes */
497 
498 	const char *client_ssl_cipher_list;
499 	/**< VHOST: Client SSL context init: List of valid ciphers to use (eg,
500 	* "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
501 	* or you can leave it as NULL to get "DEFAULT" */
502 
503 	const struct lws_plat_file_ops *fops;
504 	/**< CONTEXT: NULL, or pointer to an array of fops structs, terminated
505 	 * by a sentinel with NULL .open.
506 	 *
507 	 * If NULL, lws provides just the platform file operations struct for
508 	 * backwards compatibility.
509 	 */
510 	int simultaneous_ssl_restriction;
511 	/**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions
512 	 * possible.*/
513 	const char *socks_proxy_address;
514 	/**< VHOST: If non-NULL, attempts to proxy via the given address.
515 	 * If proxy auth is required, use format
516 	 * "username:password\@server:port" */
517 	unsigned int socks_proxy_port;
518 	/**< VHOST: If socks_proxy_address was non-NULL, uses this port
519 	 * if nonzero, otherwise requires "server:port" in .socks_proxy_address
520 	 */
521 #if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
522 	cap_value_t caps[4];
523 	/**< CONTEXT: array holding Linux capabilities you want to
524 	 * continue to be available to the server after it transitions
525 	 * to a noprivileged user.  Usually none are needed but for, eg,
526 	 * .bind_iface, CAP_NET_RAW is required.  This gives you a way
527 	 * to still have the capability but drop root.
528 	 */
529 	char count_caps;
530 	/**< CONTEXT: count of Linux capabilities in .caps[].  0 means
531 	 * no capabilities will be inherited from root (the default) */
532 #endif
533 	int bind_iface;
534 	/**< VHOST: nonzero to strictly bind sockets to the interface name in
535 	 * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
536 	 *
537 	 * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW
538 	 * capability.
539 	 *
540 	 * Notice that common things like access network interface IP from
541 	 * your local machine use your lo / loopback interface and will be
542 	 * disallowed by this.
543 	 */
544 	int ssl_info_event_mask;
545 	/**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO
546 	 * callback for connections on this vhost.  The mask values are of
547 	 * the form SSL_CB_ALERT, defined in openssl/ssl.h.  The default of
548 	 * 0 means no info events will be reported.
549 	 */
550 	unsigned int timeout_secs_ah_idle;
551 	/**< VHOST: seconds to allow a client to hold an ah without using it.
552 	 * 0 defaults to 10s. */
553 	unsigned short ip_limit_ah;
554 	/**< CONTEXT: max number of ah a single IP may use simultaneously
555 	 *	      0 is no limit. This is a soft limit: if the limit is
556 	 *	      reached, connections from that IP will wait in the ah
557 	 *	      waiting list and not be able to acquire an ah until
558 	 *	      a connection belonging to the IP relinquishes one it
559 	 *	      already has.
560 	 */
561 	unsigned short ip_limit_wsi;
562 	/**< CONTEXT: max number of wsi a single IP may use simultaneously.
563 	 *	      0 is no limit.  This is a hard limit, connections from
564 	 *	      the same IP will simply be dropped once it acquires the
565 	 *	      amount of simultaneous wsi / accepted connections
566 	 *	      given here.
567 	 */
568 	uint32_t	http2_settings[7];
569 	/**< VHOST:  if http2_settings[0] is nonzero, the values given in
570 	 *	      http2_settings[1]..[6] are used instead of the lws
571 	 *	      platform default values.
572 	 *	      Just leave all at 0 if you don't care.
573 	 */
574 	const char *error_document_404;
575 	/**< VHOST: If non-NULL, when asked to serve a non-existent file,
576 	 *          lws attempts to server this url path instead.  Eg,
577 	 *          "/404.html" */
578 	const char *alpn;
579 	/**< CONTEXT: If non-NULL, default list of advertised alpn, comma-
580 	 *	      separated
581 	 *
582 	 *     VHOST: If non-NULL, per-vhost list of advertised alpn, comma-
583 	 *	      separated
584 	 */
585 	void **foreign_loops;
586 	/**< CONTEXT: This is ignored if the context is not being started with
587 	 *		an event loop, ie, .options has a flag like
588 	 *		LWS_SERVER_OPTION_LIBUV.
589 	 *
590 	 *		NULL indicates lws should start its own even loop for
591 	 *		each service thread, and deal with closing the loops
592 	 *		when the context is destroyed.
593 	 *
594 	 *		Non-NULL means it points to an array of external
595 	 *		("foreign") event loops that are to be used in turn for
596 	 *		each service thread.  In the default case of 1 service
597 	 *		thread, it can just point to one foreign event loop.
598 	 */
599 	void (*signal_cb)(void *event_lib_handle, int signum);
600 	/**< CONTEXT: NULL: default signal handling.  Otherwise this receives
601 	 *		the signal handler callback.  event_lib_handle is the
602 	 *		native event library signal handle, eg uv_signal_t *
603 	 *		for libuv.
604 	 */
605 	struct lws_context **pcontext;
606 	/**< CONTEXT: if non-NULL, at the end of context destroy processing,
607 	 * the pointer pointed to by pcontext is written with NULL.  You can
608 	 * use this to let foreign event loops know that lws context destruction
609 	 * is fully completed.
610 	 */
611 	void (*finalize)(struct lws_vhost *vh, void *arg);
612 	/**< VHOST: NULL, or pointer to function that will be called back
613 	 *	    when the vhost is just about to be freed.  The arg parameter
614 	 *	    will be set to whatever finalize_arg is below.
615 	 */
616 	void *finalize_arg;
617 	/**< VHOST: opaque pointer lws ignores but passes to the finalize
618 	 *	    callback.  If you don't care, leave it NULL.
619 	 */
620 	unsigned int max_http_header_pool2;
621 	/**< CONTEXT: if max_http_header_pool is 0 and this
622 	 * is nonzero, this will be used in place of the default.  It's
623 	 * like this for compatibility with the original short version:
624 	 * this is unsigned int length. */
625 
626 	long ssl_client_options_set;
627 	/**< VHOST: Any bits set here will be set as CLIENT SSL options */
628 	long ssl_client_options_clear;
629 	/**< VHOST: Any bits set here will be cleared as CLIENT SSL options */
630 
631 	const char *tls1_3_plus_cipher_list;
632 	/**< VHOST: List of valid ciphers to use for incoming server connections
633 	 * ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost
634 	 * or you can leave it as NULL to get "DEFAULT".
635 	 * SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost
636 	 * client SSL_CTX.
637 	 */
638 	const char *client_tls_1_3_plus_cipher_list;
639 	/**< VHOST: List of valid ciphers to use for outgoing client connections
640 	 * ON TLS1.3 AND ABOVE on this vhost (eg,
641 	 * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get
642 	 * "DEFAULT".
643 	 */
644 	const char *listen_accept_role;
645 	/**< VHOST: NULL for default, or force accepted incoming connections to
646 	 * bind to this role.  Uses the role names from their ops struct, eg,
647 	 * "raw-skt".
648 	 */
649 	const char *listen_accept_protocol;
650 	/**< VHOST: NULL for default, or force accepted incoming connections to
651 	 * bind to this vhost protocol name.
652 	 */
653 	const struct lws_protocols **pprotocols;
654 	/**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use
655 	 * this array of pointers to protocols structs.  The end of the array
656 	 * is marked by a NULL pointer.
657 	 *
658 	 * This is preferred over .protocols, because it allows the protocol
659 	 * struct to be opaquely defined elsewhere, with just a pointer to it
660 	 * needed to create the context with it.  .protocols requires also
661 	 * the type of the user data to be known so its size can be given.
662 	 */
663 
664 	const void *server_ssl_cert_mem;
665 	/**< VHOST: Alternative for \p ssl_cert_filepath that allows setting
666 	 * from memory instead of from a file.  At most one of
667 	 * \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */
668 	unsigned int server_ssl_cert_mem_len;
669 	/**< VHOST: Server SSL context init: length of server_ssl_cert_mem in
670 	 * bytes */
671 	const void *server_ssl_private_key_mem;
672 	/**<  VHOST: Alternative for \p ssl_private_key_filepath allowing
673 	 * init from a private key in memory instead of a file.  At most one
674 	 * of \p ssl_private_key_filepath or \p server_ssl_private_key_mem
675 	 * should be non-NULL. */
676 	unsigned int server_ssl_private_key_mem_len;
677 	/**< VHOST: length of \p server_ssl_private_key_mem in memory */
678 	const void *server_ssl_ca_mem;
679 	/**< VHOST: Alternative for \p ssl_ca_filepath allowing
680 	 * init from a CA cert in memory instead of a file.  At most one
681 	 * of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */
682 	unsigned int server_ssl_ca_mem_len;
683 	/**< VHOST: length of \p server_ssl_ca_mem in memory */
684 	const char *username; /**< CONTEXT: string username for post-init
685 	 * permissions.  Like .uid but takes a string username. */
686 	const char *groupname; /**< CONTEXT: string groupname for post-init
687 	 * permissions.  Like .gid but takes a string groupname. */
688 	const char *unix_socket_perms; /**< VHOST: if your vhost is listening
689 	 * on a unix socket, you can give a "username:groupname" string here
690 	 * to control the owner:group it's created with.  It's always created
691 	 * with 0660 mode. */
692 	const lws_system_ops_t *system_ops;
693 	/**< CONTEXT: hook up lws_system_ apis to system-specific
694 	 * implementations */
695 	det_lat_buf_cb_t detailed_latency_cb;
696 	/**< CONTEXT: NULL, or callback to receive detailed latency information
697 	 * collected for each read and write */
698 	const char *detailed_latency_filepath;
699 	/**< CONTEXT: NULL, or filepath to put latency data into */
700 	const lws_retry_bo_t *retry_and_idle_policy;
701 	/**< VHOST: optional retry and idle policy to apply to this vhost.
702 	 *   Currently only the idle parts are applied to the connections.
703 	 */
704 	lws_state_notify_link_t * const *register_notifier_list;
705 	/**< CONTEXT: NULL, or pointer to an array of notifiers that should
706 	 * be registered during context creation, so they can see state change
707 	 * events from very early on.  The array should end with a NULL. */
708 	uint8_t udp_loss_sim_tx_pc;
709 	/**< CONTEXT: percentage of udp writes we could have performed
710 	 * to instead not do, in order to simulate and test udp retry flow */
711 	uint8_t udp_loss_sim_rx_pc;
712 	/**< CONTEXT: percentage of udp reads we actually received
713 	 * to make disappear, in order to simulate and test udp retry flow */
714 #if defined(LWS_WITH_SECURE_STREAMS)
715 	const char *pss_policies_json; /**< CONTEXT: point to a string
716 	 * containing a JSON description of the secure streams policies.  Set
717 	 * to NULL if not using Secure Streams. */
718 	const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array
719 	 * of pointers to plugin structs here, terminated with a NULL ptr.
720 	 * Set to NULL if not using Secure Streams. */
721 	const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0:
722 	 * point to a string giving the Unix Domain Socket address to use (start
723 	 * with @ for abstract namespace), ss_proxy_port nonzero: set the
724 	 * network interface address (not name, it's ambiguous for ipv4/6) to
725 	 * bind the tcp connection to the proxy to */
726 	const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port
727 	 * nonzero: the tcp address of the ss proxy to connect to */
728 	uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a
729 	 * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else
730 	 * the socket path given in ss_proxy_bind (start it with a + or +@);
731 	 * nonzero means connect via a tcp socket to the tcp address in
732 	 * ss_proxy_bind and the given port */
733 #endif
734 
735 	/* Add new things just above here ---^
736 	 * This is part of the ABI, don't needlessly break compatibility
737 	 *
738 	 * The below is to ensure later library versions with new
739 	 * members added above will see 0 (default) even if the app
740 	 * was not built against the newer headers.
741 	 */
742 
743 	void *_unused[2]; /**< dummy */
744 };
745 
746 /**
747  * lws_create_context() - Create the websocket handler
748  * \param info:	pointer to struct with parameters
749  *
750  *	This function creates the listening socket (if serving) and takes care
751  *	of all initialization in one step.
752  *
753  *	If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is
754  *	created; you're expected to create your own vhosts afterwards using
755  *	lws_create_vhost().  Otherwise a vhost named "default" is also created
756  *	using the information in the vhost-related members, for compatibility.
757  *
758  *	After initialization, it returns a struct lws_context * that
759  *	represents this server.  After calling, user code needs to take care
760  *	of calling lws_service() with the context pointer to get the
761  *	server's sockets serviced.  This must be done in the same process
762  *	context as the initialization call.
763  *
764  *	The protocol callback functions are called for a handful of events
765  *	including http requests coming in, websocket connections becoming
766  *	established, and data arriving; it's also called periodically to allow
767  *	async transmission.
768  *
769  *	HTTP requests are sent always to the FIRST protocol in protocol, since
770  *	at that time websocket protocol has not been negotiated.  Other
771  *	protocols after the first one never see any HTTP callback activity.
772  *
773  *	The server created is a simple http server by default; part of the
774  *	websocket standard is upgrading this http connection to a websocket one.
775  *
776  *	This allows the same server to provide files like scripts and favicon /
777  *	images or whatever over http and dynamic data over websockets all in
778  *	one place; they're all handled in the user callback.
779  */
780 LWS_VISIBLE LWS_EXTERN struct lws_context *
781 lws_create_context(const struct lws_context_creation_info *info);
782 
783 
784 /**
785  * lws_context_destroy() - Destroy the websocket context
786  * \param context:	Websocket context
787  *
788  *	This function closes any active connections and then frees the
789  *	context.  After calling this, any further use of the context is
790  *	undefined.
791  */
792 LWS_VISIBLE LWS_EXTERN void
793 lws_context_destroy(struct lws_context *context);
794 
795 typedef int (*lws_reload_func)(void);
796 
797 /**
798  * lws_context_deprecate() - Deprecate the websocket context
799  *
800  * \param context:	Websocket context
801  * \param cb: Callback notified when old context listen sockets are closed
802  *
803  *	This function is used on an existing context before superceding it
804  *	with a new context.
805  *
806  *	It closes any listen sockets in the context, so new connections are
807  *	not possible.
808  *
809  *	And it marks the context to be deleted when the number of active
810  *	connections into it falls to zero.
811  *
812  *	This is aimed at allowing seamless configuration reloads.
813  *
814  *	The callback cb will be called after the listen sockets are actually
815  *	closed and may be reopened.  In the callback the new context should be
816  *	configured and created.  (With libuv, socket close happens async after
817  *	more loop events).
818  */
819 LWS_VISIBLE LWS_EXTERN void
820 lws_context_deprecate(struct lws_context *context, lws_reload_func cb);
821 
822 LWS_VISIBLE LWS_EXTERN int
823 lws_context_is_deprecated(struct lws_context *context);
824 
825 /**
826  * lws_set_proxy() - Setups proxy to lws_context.
827  * \param vhost:	pointer to struct lws_vhost you want set proxy for
828  * \param proxy: pointer to c string containing proxy in format address:port
829  *
830  * Returns 0 if proxy string was parsed and proxy was setup.
831  * Returns -1 if proxy is NULL or has incorrect format.
832  *
833  * This is only required if your OS does not provide the http_proxy
834  * environment variable (eg, OSX)
835  *
836  *   IMPORTANT! You should call this function right after creation of the
837  *   lws_context and before call to connect. If you call this
838  *   function after connect behavior is undefined.
839  *   This function will override proxy settings made on lws_context
840  *   creation with genenv() call.
841  */
842 LWS_VISIBLE LWS_EXTERN int
843 lws_set_proxy(struct lws_vhost *vhost, const char *proxy);
844 
845 /**
846  * lws_set_socks() - Setup socks to lws_context.
847  * \param vhost:	pointer to struct lws_vhost you want set socks for
848  * \param socks: pointer to c string containing socks in format address:port
849  *
850  * Returns 0 if socks string was parsed and socks was setup.
851  * Returns -1 if socks is NULL or has incorrect format.
852  *
853  * This is only required if your OS does not provide the socks_proxy
854  * environment variable (eg, OSX)
855  *
856  *   IMPORTANT! You should call this function right after creation of the
857  *   lws_context and before call to connect. If you call this
858  *   function after connect behavior is undefined.
859  *   This function will override proxy settings made on lws_context
860  *   creation with genenv() call.
861  */
862 LWS_VISIBLE LWS_EXTERN int
863 lws_set_socks(struct lws_vhost *vhost, const char *socks);
864 
865 struct lws_vhost;
866 
867 /**
868  * lws_create_vhost() - Create a vhost (virtual server context)
869  * \param context:	pointer to result of lws_create_context()
870  * \param info:		pointer to struct with parameters
871  *
872  * This function creates a virtual server (vhost) using the vhost-related
873  * members of the info struct.  You can create many vhosts inside one context
874  * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
875  */
876 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
877 lws_create_vhost(struct lws_context *context,
878 		 const struct lws_context_creation_info *info);
879 
880 /**
881  * lws_vhost_destroy() - Destroy a vhost (virtual server context)
882  *
883  * \param vh:		pointer to result of lws_create_vhost()
884  *
885  * This function destroys a vhost.  Normally, if you just want to exit,
886  * then lws_destroy_context() will take care of everything.  If you want
887  * to destroy an individual vhost and all connections and allocations, you
888  * can do it with this.
889  *
890  * If the vhost has a listen sockets shared by other vhosts, it will be given
891  * to one of the vhosts sharing it rather than closed.
892  *
893  * The vhost close is staged according to the needs of the event loop, and if
894  * there are multiple service threads.  At the point the vhost itself if
895  * about to be freed, if you provided a finalize callback and optional arg at
896  * vhost creation time, it will be called just before the vhost is freed.
897  */
898 LWS_VISIBLE LWS_EXTERN void
899 lws_vhost_destroy(struct lws_vhost *vh);
900 
901 /**
902  * lwsws_get_config_globals() - Parse a JSON server config file
903  * \param info:		pointer to struct with parameters
904  * \param d:		filepath of the config file
905  * \param config_strings: storage for the config strings extracted from JSON,
906  * 			  the pointer is incremented as strings are stored
907  * \param len:		pointer to the remaining length left in config_strings
908  *			  the value is decremented as strings are stored
909  *
910  * This function prepares a n lws_context_creation_info struct with global
911  * settings from a file d.
912  *
913  * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
914  */
915 LWS_VISIBLE LWS_EXTERN int
916 lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
917 			 char **config_strings, int *len);
918 
919 /**
920  * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
921  * \param context:	pointer to result of lws_create_context()
922  * \param info:		pointer to struct with parameters
923  * \param d:		filepath of the config file
924  * \param config_strings: storage for the config strings extracted from JSON,
925  * 			  the pointer is incremented as strings are stored
926  * \param len:		pointer to the remaining length left in config_strings
927  *			  the value is decremented as strings are stored
928  *
929  * This function creates vhosts into a context according to the settings in
930  *JSON files found in directory d.
931  *
932  * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
933  */
934 LWS_VISIBLE LWS_EXTERN int
935 lwsws_get_config_vhosts(struct lws_context *context,
936 			struct lws_context_creation_info *info, const char *d,
937 			char **config_strings, int *len);
938 
939 /**
940  * lws_get_vhost() - return the vhost a wsi belongs to
941  *
942  * \param wsi: which connection
943  */
944 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
945 lws_get_vhost(struct lws *wsi);
946 
947 /**
948  * lws_get_vhost_name() - returns the name of a vhost
949  *
950  * \param vhost: which vhost
951  */
952 LWS_VISIBLE LWS_EXTERN const char *
953 lws_get_vhost_name(struct lws_vhost *vhost);
954 
955 /**
956  * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
957  *
958  * \param context: the lws_context to look in
959  * \param name: vhost name we are looking for
960  *
961  * Returns NULL, or the vhost with the name \p name
962  */
963 LWS_VISIBLE LWS_EXTERN struct lws_vhost *
964 lws_get_vhost_by_name(struct lws_context *context, const char *name);
965 
966 /**
967  * lws_get_vhost_port() - returns the port a vhost listens on, or -1
968  *
969  * \param vhost: which vhost
970  */
971 LWS_VISIBLE LWS_EXTERN int
972 lws_get_vhost_port(struct lws_vhost *vhost);
973 
974 /**
975  * lws_get_vhost_user() - returns the user pointer for the vhost
976  *
977  * \param vhost: which vhost
978  */
979 LWS_VISIBLE LWS_EXTERN void *
980 lws_get_vhost_user(struct lws_vhost *vhost);
981 
982 /**
983  * lws_get_vhost_iface() - returns the binding for the vhost listen socket
984  *
985  * \param vhost: which vhost
986  */
987 LWS_VISIBLE LWS_EXTERN const char *
988 lws_get_vhost_iface(struct lws_vhost *vhost);
989 
990 /**
991  * lws_json_dump_vhost() - describe vhost state and stats in JSON
992  *
993  * \param vh: the vhost
994  * \param buf: buffer to fill with JSON
995  * \param len: max length of buf
996  */
997 LWS_VISIBLE LWS_EXTERN int
998 lws_json_dump_vhost(const struct lws_vhost *vh, char *buf, int len);
999 
1000 /**
1001  * lws_json_dump_context() - describe context state and stats in JSON
1002  *
1003  * \param context: the context
1004  * \param buf: buffer to fill with JSON
1005  * \param len: max length of buf
1006  * \param hide_vhosts: nonzero to not provide per-vhost mount etc information
1007  *
1008  * Generates a JSON description of vhost state into buf
1009  */
1010 LWS_VISIBLE LWS_EXTERN int
1011 lws_json_dump_context(const struct lws_context *context, char *buf, int len,
1012 		      int hide_vhosts);
1013 
1014 /**
1015  * lws_vhost_user() - get the user data associated with the vhost
1016  * \param vhost: Websocket vhost
1017  *
1018  * This returns the optional user pointer that can be attached to
1019  * a vhost when it was created.  Lws never dereferences this pointer, it only
1020  * sets it when the vhost is created, and returns it using this api.
1021  */
1022 LWS_VISIBLE LWS_EXTERN void *
1023 lws_vhost_user(struct lws_vhost *vhost);
1024 
1025 /**
1026  * lws_context_user() - get the user data associated with the context
1027  * \param context: Websocket context
1028  *
1029  * This returns the optional user allocation that can be attached to
1030  * the context the sockets live in at context_create time.  It's a way
1031  * to let all sockets serviced in the same context share data without
1032  * using globals statics in the user code.
1033  */
1034 LWS_VISIBLE LWS_EXTERN void *
1035 lws_context_user(struct lws_context *context);
1036 
1037 /*! \defgroup vhost-mounts Vhost mounts and options
1038  * \ingroup context-and-vhost-creation
1039  *
1040  * ##Vhost mounts and options
1041  */
1042 ///@{
1043 /** struct lws_protocol_vhost_options - linked list of per-vhost protocol
1044  * 					name=value options
1045  *
1046  * This provides a general way to attach a linked-list of name=value pairs,
1047  * which can also have an optional child link-list using the options member.
1048  */
1049 struct lws_protocol_vhost_options {
1050 	const struct lws_protocol_vhost_options *next; /**< linked list */
1051 	const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */
1052 	const char *name; /**< name of name=value pair */
1053 	const char *value; /**< value of name=value pair */
1054 };
1055 
1056 /** enum lws_mount_protocols
1057  * This specifies the mount protocol for a mountpoint, whether it is to be
1058  * served from a filesystem, or it is a cgi etc.
1059  */
1060 enum lws_mount_protocols {
1061 	LWSMPRO_HTTP		= 0, /**< http reverse proxy */
1062 	LWSMPRO_HTTPS		= 1, /**< https reverse proxy */
1063 	LWSMPRO_FILE		= 2, /**< serve from filesystem directory */
1064 	LWSMPRO_CGI		= 3, /**< pass to CGI to handle */
1065 	LWSMPRO_REDIR_HTTP	= 4, /**< redirect to http:// url */
1066 	LWSMPRO_REDIR_HTTPS	= 5, /**< redirect to https:// url */
1067 	LWSMPRO_CALLBACK	= 6, /**< hand by named protocol's callback */
1068 };
1069 
1070 /** enum lws_authentication_mode
1071  * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter
1072  * is ignored unless LWSAUTHM_DEFAULT is set.
1073  */
1074 enum lws_authentication_mode {
1075 	LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */
1076 	LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */
1077 };
1078 
1079 /** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */
1080 #define AUTH_MODE_MASK 0xF0000000
1081 
1082 /** struct lws_http_mount
1083  *
1084  * arguments for mounting something in a vhost's url namespace
1085  */
1086 struct lws_http_mount {
1087 	const struct lws_http_mount *mount_next;
1088 	/**< pointer to next struct lws_http_mount */
1089 	const char *mountpoint;
1090 	/**< mountpoint in http pathspace, eg, "/" */
1091 	const char *origin;
1092 	/**< path to be mounted, eg, "/var/www/warmcat.com" */
1093 	const char *def;
1094 	/**< default target, eg, "index.html" */
1095 	const char *protocol;
1096 	/**<"protocol-name" to handle mount */
1097 
1098 	const struct lws_protocol_vhost_options *cgienv;
1099 	/**< optional linked-list of cgi options.  These are created
1100 	 * as environment variables for the cgi process
1101 	 */
1102 	const struct lws_protocol_vhost_options *extra_mimetypes;
1103 	/**< optional linked-list of mimetype mappings */
1104 	const struct lws_protocol_vhost_options *interpret;
1105 	/**< optional linked-list of files to be interpreted */
1106 
1107 	int cgi_timeout;
1108 	/**< seconds cgi is allowed to live, if cgi://mount type */
1109 	int cache_max_age;
1110 	/**< max-age for reuse of client cache of files, seconds */
1111 	unsigned int auth_mask;
1112 	/**< bits set here must be set for authorized client session */
1113 
1114 	unsigned int cache_reusable:1; /**< set if client cache may reuse this */
1115 	unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */
1116 	unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */
1117 
1118 	unsigned char origin_protocol; /**< one of enum lws_mount_protocols */
1119 	unsigned char mountpoint_len; /**< length of mountpoint string */
1120 
1121 	const char *basic_auth_login_file;
1122 	/**<NULL, or filepath to use to check basic auth logins against. (requires LWSAUTHM_DEFAULT) */
1123 
1124 	/* Add new things just above here ---^
1125 	 * This is part of the ABI, don't needlessly break compatibility
1126 	 *
1127 	 * The below is to ensure later library versions with new
1128 	 * members added above will see 0 (default) even if the app
1129 	 * was not built against the newer headers.
1130 	 */
1131 
1132 	void *_unused[2]; /**< dummy */
1133 };
1134 
1135 ///@}
1136 ///@}
1137