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