/* * libwebsockets - small server side websockets and web server implementation * * Copyright (C) 2010 - 2021 Andy Green * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to * deal in the Software without restriction, including without limitation the * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or * sell copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS * IN THE SOFTWARE. */ /*! \defgroup context-and-vhost context and vhost related functions * ##Context and Vhost releated functions * \ingroup lwsapi * * * LWS requires that there is one context, in which you may define multiple * vhosts. Each vhost is a virtual host, with either its own listen port * or sharing an existing one. Each vhost has its own SSL context that can * be set up individually or left disabled. * * If you don't care about multiple "site" support, you can ignore it and * lws will create a single default vhost at context creation time. */ ///@{ /* * NOTE: These public enums are part of the abi. If you want to add one, * add it at where specified so existing users are unaffected. */ #define LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT ((1ll << 1) | \ (1ll << 12)) /**< (VH) Don't allow the connection unless the client has a * client cert that we recognize; provides * LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT */ #define LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME (1ll << 2) /**< (CTX) Don't try to get the server's hostname */ #define LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT ((1ll << 3) | \ (1ll << 12)) /**< (VH) Allow non-SSL (plaintext) connections on the same * port as SSL is listening. If combined with * LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS it will try to * force http connections on an https listener (eg, http://x.com:443) to * redirect to an explicit https connection (eg, https://x.com) */ #define LWS_SERVER_OPTION_LIBEV (1ll << 4) /**< (CTX) Use libev event loop */ #define LWS_SERVER_OPTION_DISABLE_IPV6 (1ll << 5) /**< (VH) Disable IPV6 support */ #define LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS (1ll << 6) /**< (VH) Don't load OS CA certs, you will need to load your * own CA cert(s) */ #define LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED (1ll << 7) /**< (VH) Accept connections with no valid Cert (eg, selfsigned) */ #define LWS_SERVER_OPTION_VALIDATE_UTF8 (1ll << 8) /**< (VH) Check UT-8 correctness */ #define LWS_SERVER_OPTION_SSL_ECDH ((1ll << 9) | \ (1ll << 12)) /**< (VH) initialize ECDH ciphers */ #define LWS_SERVER_OPTION_LIBUV (1ll << 10) /**< (CTX) Use libuv event loop */ #define LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS ((1ll << 11) |\ (1ll << 12)) /**< (VH) Use an http redirect to force the client to ask for https. * Notice if your http server issues the STS header and the client has * ever seen that, the client will fail the http connection before it * can actually do the redirect. * * Combine with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS to handle, eg, * http://x.com:443 -> https://x.com * * (deprecated: use mount redirection) */ #define LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT (1ll << 12) /**< (CTX) Initialize the SSL library at all */ #define LWS_SERVER_OPTION_EXPLICIT_VHOSTS (1ll << 13) /**< (CTX) Only create the context when calling context * create api, implies user code will create its own vhosts */ #define LWS_SERVER_OPTION_UNIX_SOCK (1ll << 14) /**< (VH) Use Unix socket */ #define LWS_SERVER_OPTION_STS (1ll << 15) /**< (VH) Send Strict Transport Security header, making * clients subsequently go to https even if user asked for http */ #define LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY (1ll << 16) /**< (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect */ #define LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE (1ll << 17) /**< (VH) if set, only ipv6 allowed on the vhost */ #define LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN (1ll << 18) /**< (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE. A segfault * normally makes the lib spin so you can attach a debugger to it * even if it happened without a debugger in place. You can disable * that by giving this option. */ #define LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN (1ll << 19) /**< For backwards-compatibility reasons, by default * lws prepends "http://" to the origin you give in the client * connection info struct. If you give this flag when you create * the context, only the string you give in the client connect * info for .origin (if any) will be used directly. */ #define LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */ (1ll << 20) #define LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20) /**< (VH) if invalid http is coming in the first line, then abandon * trying to treat the connection as http, and belatedly apply the * .listen_accept_role / .listen_accept_protocol info struct members to * the connection. If they are NULL, for backwards-compatibility the * connection is bound to "raw-skt" role, and in order of priority: * 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a * pvo named "default", or 3) protocols[0]. * * Must be combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT * to work with a socket listening with tls. */ #define LWS_SERVER_OPTION_LIBEVENT (1ll << 21) /**< (CTX) Use libevent event loop */ #define LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */ (1ll << 22) #define LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 22) /**< (VH) All connections to this vhost / port are bound to the * role and protocol given in .listen_accept_role / * .listen_accept_protocol. * * If those explicit user-controlled names are NULL, for backwards- * compatibility the connection is bound to "raw-skt" role, and in order * of priority: 1) the vh protocol with a pvo named "raw", 2) the vh * protocol with a pvo named "default", or 3) protocols[0]. * * It's much preferred to specify the role + protocol using the * .listen_accept_role and .listen_accept_protocol in the info struct. */ #define LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE (1ll << 23) /**< (VH) Set to allow multiple listen sockets on one interface + * address + port. The default is to strictly allow only one * listen socket at a time. This is automatically selected if you * have multiple service threads. Linux only. */ #define LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX (1ll << 24) /**< (VH) Force setting up the vhost SSL_CTX, even though the user * code doesn't explicitly provide a cert in the info struct. It * implies the user code is going to provide a cert at the * LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback, which * provides the vhost SSL_CTX * in the user parameter. */ #define LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT (1ll << 25) /**< (VH) You probably don't want this. It forces this vhost to not * call LWS_CALLBACK_PROTOCOL_INIT on its protocols. It's used in the * special case of a temporary vhost bound to a single protocol. */ #define LWS_SERVER_OPTION_IGNORE_MISSING_CERT (1ll << 26) /**< (VH) Don't fail if the vhost TLS cert or key are missing, just * continue. The vhost won't be able to serve anything, but if for * example the ACME plugin was configured to fetch a cert, this lets * you bootstrap your vhost from having no cert to start with. */ #define LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK (1ll << 27) /**< (VH) On this vhost, if the connection is being upgraded, insist * that there's a Host: header and that the contents match the vhost * name + port (443 / 80 are assumed if no :port given based on if the * connection is using TLS). * * By default, without this flag, on upgrade lws just checks that the * Host: header was given without checking the contents... this is to * allow lax hostname mappings like localhost / 127.0.0.1, and CNAME * mappings like www.mysite.com / mysite.com */ #define LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28) /**< (VH) Send lws default HTTP headers recommended by Mozilla * Observatory for security. This is a helper option that sends canned * headers on each http response enabling a VERY strict Content Security * Policy. The policy is so strict, for example it won't let the page * run its own inline JS nor show images or take CSS from a different * server. In many cases your JS only comes from your server as do the * image sources and CSS, so that is what you want... attackers hoping * to inject JS into your DOM are completely out of luck since even if * they succeed, it will be rejected for execution by the browser * according to the strict CSP. In other cases you have to deviate from * the complete strictness, in which case don't use this flag: use the * .headers member in the vhost init described in struct * lws_context_creation_info instead to send the adapted headers * yourself. */ #define LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER (1ll << 29) /**< (VH) If you really want to allow HTTP connections on a tls * listener, you can do it with this combined with * LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT. But this is allowing * accidental loss of the security assurances provided by tls depending * on the client using http when he meant https... it's not * recommended. */ #define LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND (1ll << 30) /**< (VH) When instantiating a new vhost and the specified port is * already in use, a null value shall be return to signal the error. */ #define LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW (1ll << 31) /**< (VH) Indicates the connections using this vhost should ignore * h2 WINDOW_UPDATE from broken peers and fix them up */ #define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL (1ll << 32) /**< (VH) Tell the vhost to treat half-closed remote clients as * entered into an immortal (ie, not subject to normal timeouts) long * poll mode. */ #define LWS_SERVER_OPTION_GLIB (1ll << 33) /**< (CTX) Use glib event loop */ #define LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE (1ll << 34) /**< (VH) Tell the vhost to treat plain text http connections as * H2 with prior knowledge (no upgrade request involved) */ #define LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES (1ll << 35) /**< (CTX) Disable lws_system state, eg, because we are a secure streams * proxy client that is not trying to track system state by itself. */ #define LWS_SERVER_OPTION_SS_PROXY (1ll << 36) /**< (VH) We are being a SS Proxy listen socket for the vhost */ #define LWS_SERVER_OPTION_SDEVENT (1ll << 37) /**< (CTX) Use sd-event loop */ #define LWS_SERVER_OPTION_ULOOP (1ll << 38) /**< (CTX) Use libubox / uloop event loop */ #define LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE (1ll << 39) /**< (VHOST) Disallow use of client tls caching (on by default) */ #define LWS_SERVER_OPTION_OPENSSL_AUTO_DH_PARAMETERS (1ll << 40) /**< Configure openssl to use the default built-in DH parameters * to support TLSv1.2 Kx=DH ciphers (by calling SSL_CTX_set_dh_auto) * This is needed when you want to enable TLSv1.2 ephemeral * Diffie-Hellman (DH) key exchange ciphers * (e.g. TLS_DHE_RSA_WITH_AES_256_GCM_SHA384). It's not recommended. */ #define LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE ((1ll << 41) | \ (1ll << 12)) /**< (VH) An option to be used with mbedtls only, forces server to load * and store the client cert (without CA dependent check) * to be able to verify it later (after the handshake); * provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT. * Note: LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT and * LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED are ignored if * LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE is set */ #define LWS_SERVER_OPTION_VH_INSTANTIATE_ALL_PROTOCOLS (1ll << 42) /**< (VH) force instantiation of all protocols for this vhost */ /****** add new things just above ---^ ******/ #define lws_check_opt(c, f) ((((uint64_t)c) & ((uint64_t)f)) == ((uint64_t)f)) struct lws_plat_file_ops; struct lws_ss_policy; struct lws_ss_plugin; struct lws_metric_policy; struct lws_sss_ops; typedef int (*lws_context_ready_cb_t)(struct lws_context *context); #if defined(LWS_WITH_NETWORK) typedef int (*lws_peer_limits_notify_t)(struct lws_context *ctx, lws_sockfd_type sockfd, lws_sockaddr46 *sa46); #endif /** struct lws_context_creation_info - parameters to create context and /or vhost with * * This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS * is not given, then for backwards compatibility one vhost is created at * context-creation time using the info from this struct. * * If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created * at the same time as the context, they are expected to be created afterwards. */ struct lws_context_creation_info { #if defined(LWS_WITH_NETWORK) const char *iface; /**< VHOST: NULL to bind the listen socket to all interfaces, or the * interface name, eg, "eth2" * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is * the pathname of a UNIX domain socket. you can use the UNIX domain * sockets in abstract namespace, by prepending an at symbol to the * socket name. */ const struct lws_protocols *protocols; /**< VHOST: Array of structures listing supported protocols and a * protocol-specific callback for each one. The list is ended with an * entry that has a NULL callback pointer. SEE ALSO .pprotocols below, * which gives an alternative way to provide an array of pointers to * protocol structs. */ #if defined(LWS_ROLE_WS) const struct lws_extension *extensions; /**< VHOST: NULL or array of lws_extension structs listing the * extensions this context supports. */ #endif #if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) const struct lws_token_limits *token_limits; /**< CONTEXT: NULL or struct lws_token_limits pointer which is * initialized with a token length limit for each possible WSI_TOKEN_ */ const char *http_proxy_address; /**< VHOST: If non-NULL, attempts to proxy via the given address. * If proxy auth is required, use format * "username:password\@server:port" */ const struct lws_protocol_vhost_options *headers; /**< VHOST: pointer to optional linked list of per-vhost * canned headers that are added to server responses */ const struct lws_protocol_vhost_options *reject_service_keywords; /**< CONTEXT: Optional list of keywords and rejection codes + text. * * The keywords are checked for existing in the user agent string. * * Eg, "badrobot" "404 Not Found" */ const struct lws_protocol_vhost_options *pvo; /**< VHOST: pointer to optional linked list of per-vhost * options made accessible to protocols */ const char *log_filepath; /**< VHOST: filepath to append logs to... this is opened before * any dropping of initial privileges */ const struct lws_http_mount *mounts; /**< VHOST: optional linked list of mounts for this vhost */ const char *server_string; /**< CONTEXT: string used in HTTP headers to identify server * software, if NULL, "libwebsockets". */ const char *error_document_404; /**< VHOST: If non-NULL, when asked to serve a non-existent file, * lws attempts to server this url path instead. Eg, * "/404.html" */ int port; /**< VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress * listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are * writing a server but you are using \ref sock-adopt instead of the * built-in listener. * * You can also set port to 0, in which case the kernel will pick * a random port that is not already in use. You can find out what * port the vhost is listening on using lws_get_vhost_listen_port() * * If options specifies LWS_SERVER_OPTION_UNIX_SOCK, you should set * port to 0 */ unsigned int http_proxy_port; /**< VHOST: If http_proxy_address was non-NULL, uses this port */ unsigned int max_http_header_data2; /**< CONTEXT: if max_http_header_data is 0 and this * is nonzero, this will be used in place of the default. It's * like this for compatibility with the original short version, * this is unsigned int length. */ unsigned int max_http_header_pool2; /**< CONTEXT: if max_http_header_pool is 0 and this * is nonzero, this will be used in place of the default. It's * like this for compatibility with the original short version: * this is unsigned int length. */ int keepalive_timeout; /**< VHOST: (default = 0 = 5s, 31s for http/2) seconds to allow remote * client to hold on to an idle HTTP/1.1 connection. Timeout lifetime * applied to idle h2 network connections */ uint32_t http2_settings[7]; /**< VHOST: if http2_settings[0] is nonzero, the values given in * http2_settings[1]..[6] are used instead of the lws * platform default values. * Just leave all at 0 if you don't care. */ unsigned short max_http_header_data; /**< CONTEXT: The max amount of header payload that can be handled * in an http request (unrecognized header payload is dropped) */ unsigned short max_http_header_pool; /**< CONTEXT: The max number of connections with http headers that * can be processed simultaneously (the corresponding memory is * allocated and deallocated dynamically as needed). If the pool is * fully busy new incoming connections must wait for accept until one * becomes free. 0 = allow as many ah as number of availble fds for * the process */ #endif #if defined(LWS_WITH_TLS) const char *ssl_private_key_password; /**< VHOST: NULL or the passphrase needed for the private key. (For * backwards compatibility, this can also be used to pass the client * cert passphrase when setting up a vhost client SSL context, but it is * preferred to use .client_ssl_private_key_password for that.) */ const char *ssl_cert_filepath; /**< VHOST: If libwebsockets was compiled to use ssl, and you want * to listen using SSL, set to the filepath to fetch the * server cert from, otherwise NULL for unencrypted. (For backwards * compatibility, this can also be used to pass the client certificate * when setting up a vhost client SSL context, but it is preferred to * use .client_ssl_cert_filepath for that.) * * Notice you can alternatively set a single DER or PEM from a memory * buffer as the vhost tls cert using \p server_ssl_cert_mem and * \p server_ssl_cert_mem_len. */ const char *ssl_private_key_filepath; /**< VHOST: filepath to private key if wanting SSL mode; * this should not be set to NULL when ssl_cert_filepath is set. * * Alteratively, the certificate and private key can both be set in * the OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback directly via * openSSL library calls. This requires that * LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX is set in the vhost info options * to force initializtion of the SSL_CTX context. * * (For backwards compatibility, this can also be used * to pass the client cert private key filepath when setting up a * vhost client SSL context, but it is preferred to use * .client_ssl_private_key_filepath for that.) * * Notice you can alternatively set a DER or PEM private key from a * memory buffer as the vhost tls private key using * \p server_ssl_private_key_mem and \p server_ssl_private_key_mem_len. */ const char *ssl_ca_filepath; /**< VHOST: CA certificate filepath or NULL. (For backwards * compatibility, this can also be used to pass the client CA * filepath when setting up a vhost client SSL context, * but it is preferred to use .client_ssl_ca_filepath for that.) * * Notice you can alternatively set a DER or PEM CA cert from a memory * buffer using \p server_ssl_ca_mem and \p server_ssl_ca_mem_len. */ const char *ssl_cipher_list; /**< VHOST: List of valid ciphers to use ON TLS1.2 AND LOWER ONLY (eg, * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" * or you can leave it as NULL to get "DEFAULT" (For backwards * compatibility, this can also be used to pass the client cipher * list when setting up a vhost client SSL context, * but it is preferred to use .client_ssl_cipher_list for that.) * SEE .tls1_3_plus_cipher_list and .client_tls_1_3_plus_cipher_list * for the equivalent for tls1.3. */ const char *ecdh_curve; /**< VHOST: if NULL, defaults to initializing server with * "prime256v1" */ const char *tls1_3_plus_cipher_list; /**< VHOST: List of valid ciphers to use for incoming server connections * ON TLS1.3 AND ABOVE (eg, "TLS_CHACHA20_POLY1305_SHA256" on this vhost * or you can leave it as NULL to get "DEFAULT". * SEE .client_tls_1_3_plus_cipher_list to do the same on the vhost * client SSL_CTX. */ const void *server_ssl_cert_mem; /**< VHOST: Alternative for \p ssl_cert_filepath that allows setting * from memory instead of from a file. At most one of * \p ssl_cert_filepath or \p server_ssl_cert_mem should be non-NULL. */ const void *server_ssl_private_key_mem; /**< VHOST: Alternative for \p ssl_private_key_filepath allowing * init from a private key in memory instead of a file. At most one * of \p ssl_private_key_filepath or \p server_ssl_private_key_mem * should be non-NULL. */ const void *server_ssl_ca_mem; /**< VHOST: Alternative for \p ssl_ca_filepath allowing * init from a CA cert in memory instead of a file. At most one * of \p ssl_ca_filepath or \p server_ssl_ca_mem should be non-NULL. */ long ssl_options_set; /**< VHOST: Any bits set here will be set as server SSL options */ long ssl_options_clear; /**< VHOST: Any bits set here will be cleared as server SSL options */ int simultaneous_ssl_restriction; /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions * possible.*/ int simultaneous_ssl_handshake_restriction; /**< CONTEXT: 0 (no limit) or limit of simultaneous SSL handshakes ongoing */ int ssl_info_event_mask; /**< VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO * callback for connections on this vhost. The mask values are of * the form SSL_CB_ALERT, defined in openssl/ssl.h. The default of * 0 means no info events will be reported. */ unsigned int server_ssl_cert_mem_len; /**< VHOST: Server SSL context init: length of server_ssl_cert_mem in * bytes */ unsigned int server_ssl_private_key_mem_len; /**< VHOST: length of \p server_ssl_private_key_mem in memory */ unsigned int server_ssl_ca_mem_len; /**< VHOST: length of \p server_ssl_ca_mem in memory */ const char *alpn; /**< CONTEXT: If non-NULL, default list of advertised alpn, comma- * separated * * VHOST: If non-NULL, per-vhost list of advertised alpn, comma- * separated */ #if defined(LWS_WITH_CLIENT) const char *client_ssl_private_key_password; /**< VHOST: Client SSL context init: NULL or the passphrase needed * for the private key */ const char *client_ssl_cert_filepath; /**< VHOST: Client SSL context init: The certificate the client * should present to the peer on connection */ const void *client_ssl_cert_mem; /**< VHOST: Client SSL context init: client certificate memory buffer or * NULL... use this to load client cert from memory instead of file */ unsigned int client_ssl_cert_mem_len; /**< VHOST: Client SSL context init: length of client_ssl_cert_mem in * bytes */ const char *client_ssl_private_key_filepath; /**< VHOST: Client SSL context init: filepath to client private key * if this is set to NULL but client_ssl_cert_filepath is set, you * can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS * callback of protocols[0] to allow setting of the private key directly * via tls library calls */ const void *client_ssl_key_mem; /**< VHOST: Client SSL context init: client key memory buffer or * NULL... use this to load client key from memory instead of file */ const char *client_ssl_ca_filepath; /**< VHOST: Client SSL context init: CA certificate filepath or NULL */ const void *client_ssl_ca_mem; /**< VHOST: Client SSL context init: CA certificate memory buffer or * NULL... use this to load CA cert from memory instead of file */ const char *client_ssl_cipher_list; /**< VHOST: Client SSL context init: List of valid ciphers to use (eg, * "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" * or you can leave it as NULL to get "DEFAULT" */ const char *client_tls_1_3_plus_cipher_list; /**< VHOST: List of valid ciphers to use for outgoing client connections * ON TLS1.3 AND ABOVE on this vhost (eg, * "TLS_CHACHA20_POLY1305_SHA256") or you can leave it as NULL to get * "DEFAULT". */ long ssl_client_options_set; /**< VHOST: Any bits set here will be set as CLIENT SSL options */ long ssl_client_options_clear; /**< VHOST: Any bits set here will be cleared as CLIENT SSL options */ unsigned int client_ssl_ca_mem_len; /**< VHOST: Client SSL context init: length of client_ssl_ca_mem in * bytes */ unsigned int client_ssl_key_mem_len; /**< VHOST: Client SSL context init: length of client_ssl_key_mem in * bytes */ #endif #if !defined(LWS_WITH_MBEDTLS) SSL_CTX *provided_client_ssl_ctx; /**< CONTEXT: If non-null, swap out libwebsockets ssl * implementation for the one provided by provided_ssl_ctx. * Libwebsockets no longer is responsible for freeing the context * if this option is selected. */ #else /* WITH_MBEDTLS */ const char *mbedtls_client_preload_filepath; /**< CONTEXT: If NULL, no effect. Otherwise it should point to a * filepath where every created client SSL_CTX is preloaded from the * system trust bundle. * * This sets a processwide variable that affects all contexts. * * Requires that the mbedtls provides mbedtls_x509_crt_parse_file(), * else disabled. */ #endif #endif int ka_time; /**< CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive * timeout to all libwebsocket sockets, client or server */ int ka_probes; /**< CONTEXT: if ka_time was nonzero, after the timeout expires how many * times to try to get a response from the peer before giving up * and killing the connection */ int ka_interval; /**< CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes * attempt */ unsigned int timeout_secs; /**< VHOST: various processes involving network roundtrips in the * library are protected from hanging forever by timeouts. If * nonzero, this member lets you set the timeout used in seconds. * Otherwise a default timeout is used. */ unsigned int connect_timeout_secs; /**< VHOST: client connections have this long to find a working server * from the DNS results, or the whole connection times out. If zero, * a default timeout is used */ int bind_iface; /**< VHOST: nonzero to strictly bind sockets to the interface name in * .iface (eg, "eth2"), using SO_BIND_TO_DEVICE. * * Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW * capability. * * Notice that common things like access network interface IP from * your local machine use your lo / loopback interface and will be * disallowed by this. */ unsigned int timeout_secs_ah_idle; /**< VHOST: seconds to allow a client to hold an ah without using it. * 0 defaults to 10s. */ #endif /* WITH_NETWORK */ #if defined(LWS_WITH_TLS_SESSIONS) uint32_t tls_session_timeout; /**< VHOST: seconds until timeout/ttl for newly created sessions. * 0 means default timeout (defined per protocol, usually 300s). */ uint32_t tls_session_cache_max; /**< VHOST: 0 for default limit of 10, or the maximum number of * client tls sessions we are willing to cache */ #endif gid_t gid; /**< CONTEXT: group id to change to after setting listen socket, * or -1. See also .username below. */ uid_t uid; /**< CONTEXT: user id to change to after setting listen socket, * or -1. See also .groupname below. */ uint64_t options; /**< VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields */ void *user; /**< VHOST + CONTEXT: optional user pointer that will be associated * with the context when creating the context (and can be retrieved by * lws_context_user(context), or with the vhost when creating the vhost * (and can be retrieved by lws_vhost_user(vhost)). You will need to * use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately * if you care about giving the context and vhost different user pointer * values. */ unsigned int count_threads; /**< CONTEXT: how many contexts to create in an array, 0 = 1 */ unsigned int fd_limit_per_thread; /**< CONTEXT: nonzero means restrict each service thread to this * many fds, 0 means the default which is divide the process fd * limit by the number of threads. * * Note if this is nonzero, and fd_limit_per_thread multiplied by the * number of service threads is less than the process ulimit, then lws * restricts internal lookup table allocation to the smaller size, and * switches to a less efficient lookup scheme. You should use this to * trade off speed against memory usage if you know the lws context * will only use a handful of fds. * * Bear in mind lws may use some fds internally, for example for the * cancel pipe, so you may need to allow for some extras for normal * operation. */ const char *vhost_name; /**< VHOST: name of vhost, must match external DNS name used to * access the site, like "warmcat.com" as it's used to match * Host: header and / or SNI name for SSL. * CONTEXT: NULL, or the name to associate with the context for * context-specific logging */ #if defined(LWS_WITH_PLUGINS) const char * const *plugin_dirs; /**< CONTEXT: NULL, or NULL-terminated array of directories to * scan for lws protocol plugins at context creation time */ #endif void *external_baggage_free_on_destroy; /**< CONTEXT: NULL, or pointer to something externally malloc'd, that * should be freed when the context is destroyed. This allows you to * automatically sync the freeing action to the context destruction * action, so there is no need for an external free() if the context * succeeded to create. */ unsigned int pt_serv_buf_size; /**< CONTEXT: 0 = default of 4096. This buffer is used by * various service related features including file serving, it * defines the max chunk of file that can be sent at once. * At the risk of lws having to buffer failed large sends, it * can be increased to, eg, 128KiB to improve throughput. */ #if defined(LWS_WITH_FILE_OPS) const struct lws_plat_file_ops *fops; /**< CONTEXT: NULL, or pointer to an array of fops structs, terminated * by a sentinel with NULL .open. * * If NULL, lws provides just the platform file operations struct for * backwards compatibility. */ #endif #if defined(LWS_WITH_SOCKS5) const char *socks_proxy_address; /**< VHOST: If non-NULL, attempts to proxy via the given address. * If proxy auth is required, use format * "username:password\@server:port" */ unsigned int socks_proxy_port; /**< VHOST: If socks_proxy_address was non-NULL, uses this port * if nonzero, otherwise requires "server:port" in .socks_proxy_address */ #endif #if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP) cap_value_t caps[4]; /**< CONTEXT: array holding Linux capabilities you want to * continue to be available to the server after it transitions * to a noprivileged user. Usually none are needed but for, eg, * .bind_iface, CAP_NET_RAW is required. This gives you a way * to still have the capability but drop root. */ char count_caps; /**< CONTEXT: count of Linux capabilities in .caps[]. 0 means * no capabilities will be inherited from root (the default) */ #endif void **foreign_loops; /**< CONTEXT: This is ignored if the context is not being started with * an event loop, ie, .options has a flag like * LWS_SERVER_OPTION_LIBUV. * * NULL indicates lws should start its own even loop for * each service thread, and deal with closing the loops * when the context is destroyed. * * Non-NULL means it points to an array of external * ("foreign") event loops that are to be used in turn for * each service thread. In the default case of 1 service * thread, it can just point to one foreign event loop. */ void (*signal_cb)(void *event_lib_handle, int signum); /**< CONTEXT: NULL: default signal handling. Otherwise this receives * the signal handler callback. event_lib_handle is the * native event library signal handle, eg uv_signal_t * * for libuv. */ struct lws_context **pcontext; /**< CONTEXT: if non-NULL, at the end of context destroy processing, * the pointer pointed to by pcontext is written with NULL. You can * use this to let foreign event loops know that lws context destruction * is fully completed. */ void (*finalize)(struct lws_vhost *vh, void *arg); /**< VHOST: NULL, or pointer to function that will be called back * when the vhost is just about to be freed. The arg parameter * will be set to whatever finalize_arg is below. */ void *finalize_arg; /**< VHOST: opaque pointer lws ignores but passes to the finalize * callback. If you don't care, leave it NULL. */ const char *listen_accept_role; /**< VHOST: NULL for default, or force accepted incoming connections to * bind to this role. Uses the role names from their ops struct, eg, * "raw-skt". */ const char *listen_accept_protocol; /**< VHOST: NULL for default, or force accepted incoming connections to * bind to this vhost protocol name. */ const struct lws_protocols **pprotocols; /**< VHOST: NULL: use .protocols, otherwise ignore .protocols and use * this array of pointers to protocols structs. The end of the array * is marked by a NULL pointer. * * This is preferred over .protocols, because it allows the protocol * struct to be opaquely defined elsewhere, with just a pointer to it * needed to create the context with it. .protocols requires also * the type of the user data to be known so its size can be given. */ const char *username; /**< CONTEXT: string username for post-init * permissions. Like .uid but takes a string username. */ const char *groupname; /**< CONTEXT: string groupname for post-init * permissions. Like .gid but takes a string groupname. */ const char *unix_socket_perms; /**< VHOST: if your vhost is listening * on a unix socket, you can give a "username:groupname" string here * to control the owner:group it's created with. It's always created * with 0660 mode. */ const lws_system_ops_t *system_ops; /**< CONTEXT: hook up lws_system_ apis to system-specific * implementations */ const lws_retry_bo_t *retry_and_idle_policy; /**< VHOST: optional retry and idle policy to apply to this vhost. * Currently only the idle parts are applied to the connections. */ #if defined(LWS_WITH_SYS_STATE) lws_state_notify_link_t * const *register_notifier_list; /**< CONTEXT: NULL, or pointer to an array of notifiers that should * be registered during context creation, so they can see state change * events from very early on. The array should end with a NULL. */ #endif #if defined(LWS_WITH_SECURE_STREAMS) #if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY) const struct lws_ss_policy *pss_policies; /**< CONTEXT: point to first * in a linked-list of streamtype policies prepared by user code */ #else const char *pss_policies_json; /**< CONTEXT: point to a string * containing a JSON description of the secure streams policies. Set * to NULL if not using Secure Streams. * If the platform supports files and the string does not begin with * '{', lws treats the string as a filepath to open to get the JSON * policy. */ #endif const struct lws_ss_plugin **pss_plugins; /**< CONTEXT: point to an array * of pointers to plugin structs here, terminated with a NULL ptr. * Set to NULL if not using Secure Streams. */ const char *ss_proxy_bind; /**< CONTEXT: NULL, or: ss_proxy_port == 0: * point to a string giving the Unix Domain Socket address to use (start * with @ for abstract namespace), ss_proxy_port nonzero: set the * network interface address (not name, it's ambiguous for ipv4/6) to * bind the tcp connection to the proxy to */ const char *ss_proxy_address; /**< CONTEXT: NULL, or if ss_proxy_port * nonzero: the tcp address of the ss proxy to connect to */ uint16_t ss_proxy_port; /* 0 = if connecting to ss proxy, do it via a * Unix Domain Socket, "+@proxy.ss.lws" if ss_proxy_bind is NULL else * the socket path given in ss_proxy_bind (start it with a + or +@); * nonzero means connect via a tcp socket to the tcp address in * ss_proxy_bind and the given port */ const struct lws_transport_proxy_ops *txp_ops_ssproxy; /**< CONTEXT: NULL, or * custom sss transport ops used for ss proxy communication. NULL means * to use the default wsi-based proxy server */ const void *txp_ssproxy_info; /**< CONTEXT: NULL, or extra transport- * specifi creation info to be used at \p txp_ops_ssproxy creation */ const struct lws_transport_client_ops *txp_ops_sspc; /**< CONTEXT: NULL, or * custom sss transport ops used for ss client communication to the ss * proxy. NULL means to use the default wsi-based client support */ #endif #if defined(LWS_WITH_SECURE_STREAMS_PROXY_API) #endif int rlimit_nofile; /**< 0 = inherit the initial ulimit for files / sockets from the startup * environment. Nonzero = try to set the limit for this process. */ #if defined(LWS_WITH_PEER_LIMITS) lws_peer_limits_notify_t pl_notify_cb; /**< CONTEXT: NULL, or a callback to receive notifications each time a * connection is being dropped because of peer limits. * * The callback provides the context, and an lws_sockaddr46 with the * peer address and port. */ unsigned short ip_limit_ah; /**< CONTEXT: max number of ah a single IP may use simultaneously * 0 is no limit. This is a soft limit: if the limit is * reached, connections from that IP will wait in the ah * waiting list and not be able to acquire an ah until * a connection belonging to the IP relinquishes one it * already has. */ unsigned short ip_limit_wsi; /**< CONTEXT: max number of wsi a single IP may use simultaneously. * 0 is no limit. This is a hard limit, connections from * the same IP will simply be dropped once it acquires the * amount of simultaneous wsi / accepted connections * given here. */ #endif /* PEER_LIMITS */ #if defined(LWS_WITH_SYS_FAULT_INJECTION) lws_fi_ctx_t fic; /**< CONTEXT | VHOST: attach external Fault Injection context to the * lws_context or vhost. If creating the context + default vhost in * one step, only the context binds to \p fi. When creating a vhost * otherwise this can bind to the vhost so the faults can be injected * from the start. */ #endif #if defined(LWS_WITH_SYS_SMD) lws_smd_notification_cb_t early_smd_cb; /**< CONTEXT: NULL, or an smd notification callback that will be registered * immediately after the smd in the context is initialized. This ensures * you can get all notifications without having to intercept the event loop * creation, eg, when using an event library. Other callbacks can be * registered later manually without problems. */ void *early_smd_opaque; lws_smd_class_t early_smd_class_filter; lws_usec_t smd_ttl_us; /**< CONTEXT: SMD messages older than this many us are removed from the * queue and destroyed even if not fully delivered yet. If zero, * defaults to 2 seconds (5 second for FREERTOS). */ uint16_t smd_queue_depth; /**< CONTEXT: Maximum queue depth, If zero defaults to 40 * (20 for FREERTOS) */ #endif #if defined(LWS_WITH_SYS_METRICS) const struct lws_metric_policy *metrics_policies; /**< CONTEXT: non-SS policy metrics policies */ const char *metrics_prefix; /**< CONTEXT: prefix for this context's metrics, used to distinguish * metrics pooled from different processes / applications, so, eg what * would be "cpu.svc" if this is NULL becomes "myapp.cpu.svc" is this is * set to "myapp". Policies are applied using the name with the prefix, * if present. */ #endif int fo_listen_queue; /**< VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the * platform supports it, with the given queue length for the listen * socket. */ const struct lws_plugin_evlib *event_lib_custom; /**< CONTEXT: If non-NULL, override event library selection so it uses * this custom event library implementation, instead of default internal * loop. Don't set any other event lib context creation flags in that * case. it will be used automatically. This is useful for integration * where an existing application is using its own handrolled event loop * instead of an event library, it provides a way to allow lws to use * the custom event loop natively as if it were an "event library". */ #if defined(LWS_WITH_TLS_JIT_TRUST) size_t jitt_cache_max_footprint; /**< CONTEXT: 0 for no limit, else max bytes used by JIT Trust cache... * LRU items are evicted to keep under this limit */ int vh_idle_grace_ms; /**< CONTEXT: 0 for default of 5000ms, or number of ms JIT Trust vhosts * are allowed to live without active connections using them. */ #endif lws_log_cx_t *log_cx; /**< CONTEXT: NULL to use the default, process-scope logging context, * else a specific logging context to associate with this context */ #if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT) const char *http_nsc_filepath; /**< CONTEXT: Filepath to use for http netscape cookiejar file */ size_t http_nsc_heap_max_footprint; /**< CONTEXT: 0, or limit in bytes for heap usage of memory cookie * cache */ size_t http_nsc_heap_max_items; /**< CONTEXT: 0, or the max number of items allowed in the cookie cache * before destroying lru items to keep it under the limit */ size_t http_nsc_heap_max_payload; /**< CONTEXT: 0, or the maximum size of a single cookie we are able to * handle */ #endif #if defined(LWS_WITH_SYS_ASYNC_DNS) const char **async_dns_servers; /**< CONTEXT: NULL, or a pointer to an array of strings containing the * numeric IP like "8.8.8.8" or "2001:4860:4860::8888" for a list of DNS * server to forcibly add. If given, the list of strings must be * terminated with a NULL. */ #endif #if defined(WIN32) unsigned int win32_connect_check_interval_usec; /**< CONTEXT: win32 needs client connection status checking at intervals * to work reliably. This sets the interval in us, up to 999999. By * default, it's 500us. */ #endif int default_loglevel; /**< CONTEXT: 0 for LLL_USER, LLL_ERR, LLL_WARN, LLL_NOTICE enabled by default when * using lws_cmdline_option_handle_builtin(), else set to the LLL_ flags you want * to be the default before calling lws_cmdline_option_handle_builtin(). Your * selected default loglevel can then be cleanly overridden using -d 1039 etc * commandline switch */ lws_sockfd_type vh_listen_sockfd; /**< VHOST: 0 for normal vhost listen socket fd creation, if any. * Nonzero to force the selection of an already-existing fd for the * vhost's listen socket, which is already prepared. This is intended * for an external process having chosen the fd, which cannot then be * zero. */ #if defined(LWS_WITH_NETWORK) const char *wol_if; /**< CONTEXT: NULL, or interface name to bind outgoing WOL packet to */ #endif int argc; /**< CONTEXT: optionally pass the app commandline to the context, so we can use it * as part of lws_cmdline_option_cx() */ const char **argv; /**< CONTEXT: optionally pass the app commandline to the context, so we can use it * as part of lws_cmdline_option_cx() */ /* Add new things just above here ---^ * This is part of the ABI, don't needlessly break compatibility * * The below is to ensure later library versions with new * members added above will see 0 (default) even if the app * was not built against the newer headers. */ void *_unused[2]; /**< dummy */ }; /** * lws_create_context() - Create the websocket handler * \param info: pointer to struct with parameters * * This function creates the listening socket (if serving) and takes care * of all initialization in one step. * * If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is * created; you're expected to create your own vhosts afterwards using * lws_create_vhost(). Otherwise a vhost named "default" is also created * using the information in the vhost-related members, for compatibility. * * After initialization, it returns a struct lws_context * that * represents this server. After calling, user code needs to take care * of calling lws_service() with the context pointer to get the * server's sockets serviced. This must be done in the same process * context as the initialization call. * * The protocol callback functions are called for a handful of events * including http requests coming in, websocket connections becoming * established, and data arriving; it's also called periodically to allow * async transmission. * * HTTP requests are sent always to the FIRST protocol in protocol, since * at that time websocket protocol has not been negotiated. Other * protocols after the first one never see any HTTP callback activity. * * The server created is a simple http server by default; part of the * websocket standard is upgrading this http connection to a websocket one. * * This allows the same server to provide files like scripts and favicon / * images or whatever over http and dynamic data over websockets all in * one place; they're all handled in the user callback. */ LWS_VISIBLE LWS_EXTERN struct lws_context * lws_create_context(const struct lws_context_creation_info *info); /** * lws_context_destroy() - Destroy the websocket context * \param context: Websocket context * * This function closes any active connections and then frees the * context. After calling this, any further use of the context is * undefined. */ LWS_VISIBLE LWS_EXTERN void lws_context_destroy(struct lws_context *context); typedef int (*lws_reload_func)(void); /** * lws_context_deprecate() - Deprecate the websocket context * * \param context: Websocket context * \param cb: Callback notified when old context listen sockets are closed * * This function is used on an existing context before superceding it * with a new context. * * It closes any listen sockets in the context, so new connections are * not possible. * * And it marks the context to be deleted when the number of active * connections into it falls to zero. * * This is aimed at allowing seamless configuration reloads. * * The callback cb will be called after the listen sockets are actually * closed and may be reopened. In the callback the new context should be * configured and created. (With libuv, socket close happens async after * more loop events). */ LWS_VISIBLE LWS_EXTERN void lws_context_deprecate(struct lws_context *context, lws_reload_func cb); LWS_VISIBLE LWS_EXTERN int lws_context_is_deprecated(struct lws_context *context); /** * lws_set_proxy() - Setups proxy to lws_context. * \param vhost: pointer to struct lws_vhost you want set proxy for * \param proxy: pointer to c string containing proxy in format address:port * * Returns 0 if proxy string was parsed and proxy was setup. * Returns -1 if proxy is NULL or has incorrect format. * * This is only required if your OS does not provide the http_proxy * environment variable (eg, OSX) * * IMPORTANT! You should call this function right after creation of the * lws_context and before call to connect. If you call this * function after connect behavior is undefined. * This function will override proxy settings made on lws_context * creation with genenv() call. */ LWS_VISIBLE LWS_EXTERN int lws_set_proxy(struct lws_vhost *vhost, const char *proxy); /** * lws_set_socks() - Setup socks to lws_context. * \param vhost: pointer to struct lws_vhost you want set socks for * \param socks: pointer to c string containing socks in format address:port * * Returns 0 if socks string was parsed and socks was setup. * Returns -1 if socks is NULL or has incorrect format. * * This is only required if your OS does not provide the socks_proxy * environment variable (eg, OSX) * * IMPORTANT! You should call this function right after creation of the * lws_context and before call to connect. If you call this * function after connect behavior is undefined. * This function will override proxy settings made on lws_context * creation with genenv() call. */ LWS_VISIBLE LWS_EXTERN int lws_set_socks(struct lws_vhost *vhost, const char *socks); struct lws_vhost; /** * lws_create_vhost() - Create a vhost (virtual server context) * \param context: pointer to result of lws_create_context() * \param info: pointer to struct with parameters * * This function creates a virtual server (vhost) using the vhost-related * members of the info struct. You can create many vhosts inside one context * if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS */ LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_create_vhost(struct lws_context *context, const struct lws_context_creation_info *info); /** * lws_vhost_destroy() - Destroy a vhost (virtual server context) * * \param vh: pointer to result of lws_create_vhost() * * This function destroys a vhost. Normally, if you just want to exit, * then lws_destroy_context() will take care of everything. If you want * to destroy an individual vhost and all connections and allocations, you * can do it with this. * * If the vhost has a listen sockets shared by other vhosts, it will be given * to one of the vhosts sharing it rather than closed. * * The vhost close is staged according to the needs of the event loop, and if * there are multiple service threads. At the point the vhost itself if * about to be freed, if you provided a finalize callback and optional arg at * vhost creation time, it will be called just before the vhost is freed. */ LWS_VISIBLE LWS_EXTERN void lws_vhost_destroy(struct lws_vhost *vh); /** * lwsws_get_config_globals() - Parse a JSON server config file * \param info: pointer to struct with parameters * \param d: filepath of the config file * \param config_strings: storage for the config strings extracted from JSON, * the pointer is incremented as strings are stored * \param len: pointer to the remaining length left in config_strings * the value is decremented as strings are stored * * This function prepares a n lws_context_creation_info struct with global * settings from a file d. * * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled */ LWS_VISIBLE LWS_EXTERN int lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d, char **config_strings, int *len); /** * lwsws_get_config_vhosts() - Create vhosts from a JSON server config file * \param context: pointer to result of lws_create_context() * \param info: pointer to struct with parameters * \param d: filepath of the config file * \param config_strings: storage for the config strings extracted from JSON, * the pointer is incremented as strings are stored * \param len: pointer to the remaining length left in config_strings * the value is decremented as strings are stored * * This function creates vhosts into a context according to the settings in *JSON files found in directory d. * * Requires CMake option LWS_WITH_LEJP_CONF to have been enabled */ LWS_VISIBLE LWS_EXTERN int lwsws_get_config_vhosts(struct lws_context *context, struct lws_context_creation_info *info, const char *d, char **config_strings, int *len); /** * lws_get_vhost() - return the vhost a wsi belongs to * * \param wsi: which connection */ LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_get_vhost(struct lws *wsi); /** * lws_get_vhost_name() - returns the name of a vhost * * \param vhost: which vhost */ LWS_VISIBLE LWS_EXTERN const char * lws_get_vhost_name(struct lws_vhost *vhost); /** * lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL * * \param context: the lws_context to look in * \param name: vhost name we are looking for * * Returns NULL, or the vhost with the name \p name */ LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_get_vhost_by_name(struct lws_context *context, const char *name); /** * lws_get_vhost_port() - returns the port a vhost listens on, or -1 * * \param vhost: which vhost */ LWS_VISIBLE LWS_EXTERN int lws_get_vhost_port(struct lws_vhost *vhost); /** * lws_get_vhost_user() - returns the user pointer for the vhost * * \param vhost: which vhost */ LWS_VISIBLE LWS_EXTERN void * lws_get_vhost_user(struct lws_vhost *vhost); /** * lws_get_vhost_iface() - returns the binding for the vhost listen socket * * \param vhost: which vhost */ LWS_VISIBLE LWS_EXTERN const char * lws_get_vhost_iface(struct lws_vhost *vhost); /** * lws_vhost_user() - get the user data associated with the vhost * \param vhost: Websocket vhost * * This returns the optional user pointer that can be attached to * a vhost when it was created. Lws never dereferences this pointer, it only * sets it when the vhost is created, and returns it using this api. */ LWS_VISIBLE LWS_EXTERN void * lws_vhost_user(struct lws_vhost *vhost); /** * lws_context_user() - get the user data associated with the context * \param context: Websocket context * * This returns the optional user allocation that can be attached to * the context the sockets live in at context_create time. It's a way * to let all sockets serviced in the same context share data without * using globals statics in the user code. */ LWS_VISIBLE LWS_EXTERN void * lws_context_user(struct lws_context *context); LWS_VISIBLE LWS_EXTERN const char * lws_vh_tag(struct lws_vhost *vh); LWS_VISIBLE LWS_EXTERN void _lws_context_info_defaults(struct lws_context_creation_info *info, const char *sspol); LWS_VISIBLE LWS_EXTERN void lws_default_loop_exit(struct lws_context *cx); LWS_VISIBLE LWS_EXTERN void lws_context_default_loop_run_destroy(struct lws_context *cx); LWS_VISIBLE LWS_EXTERN int lws_cmdline_passfail(int argc, const char **argv, int actual); /** * lws_systemd_inherited_fd() - prepare vhost creation info for systemd exported fd if any * * \param index: 0+ index of exported fd * \param info: info struct to be prepared with related info, if any * * Returns 0 and points info to the related fd, aligning the other information * to the type of fd and port it is bound to, or returns nonzero if no such * inherited fd. */ LWS_VISIBLE LWS_EXTERN int lws_systemd_inherited_fd(unsigned int index, struct lws_context_creation_info *info); /** * lws_context_is_being_destroyed() - find out if context is being destroyed * * \param context: the struct lws_context pointer * * Returns nonzero if the context has had lws_context_destroy() called on it... * when using event library loops the destroy process can be asynchronous. In * the special case of libuv foreign loops, the failure to create the context * may have to do work on the foreign loop to reverse the partial creation, * meaning a failed context create cannot unpick what it did and return NULL. * * In that condition, a valid context that is already started the destroy * process is returned, and this test api will return nonzero as a way to * find out the create is in the middle of failing. */ LWS_VISIBLE LWS_EXTERN int lws_context_is_being_destroyed(struct lws_context *context); /*! \defgroup vhost-mounts Vhost mounts and options * \ingroup context-and-vhost-creation * * ##Vhost mounts and options */ ///@{ /** struct lws_protocol_vhost_options - linked list of per-vhost protocol * name=value options * * This provides a general way to attach a linked-list of name=value pairs, * which can also have an optional child link-list using the options member. */ struct lws_protocol_vhost_options { const struct lws_protocol_vhost_options *next; /**< linked list */ const struct lws_protocol_vhost_options *options; /**< child linked-list of more options for this node */ const char *name; /**< name of name=value pair */ const char *value; /**< value of name=value pair */ }; /** enum lws_mount_protocols * This specifies the mount protocol for a mountpoint, whether it is to be * served from a filesystem, or it is a cgi etc. */ enum lws_mount_protocols { LWSMPRO_HTTP = 0, /**< http reverse proxy */ LWSMPRO_HTTPS = 1, /**< https reverse proxy */ LWSMPRO_FILE = 2, /**< serve from filesystem directory */ LWSMPRO_CGI = 3, /**< pass to CGI to handle */ LWSMPRO_REDIR_HTTP = 4, /**< redirect to http:// url */ LWSMPRO_REDIR_HTTPS = 5, /**< redirect to https:// url */ LWSMPRO_CALLBACK = 6, /**< handle by named protocol's callback */ LWSMPRO_NO_MOUNT = 7, /**< matches fall back to no match processing */ }; /** enum lws_authentication_mode * This specifies the authentication mode of the mount. The basic_auth_login_file mount parameter * is ignored unless LWSAUTHM_DEFAULT is set. */ enum lws_authentication_mode { LWSAUTHM_DEFAULT = 0, /**< default authenticate only if basic_auth_login_file is provided */ LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 /**< Basic auth with a custom verifier */ }; /** The authentication mode is stored in the top 4 bits of lws_http_mount.auth_mask */ #define AUTH_MODE_MASK 0xF0000000 /** struct lws_http_mount * * arguments for mounting something in a vhost's url namespace */ struct lws_http_mount { const struct lws_http_mount *mount_next; /**< pointer to next struct lws_http_mount */ const char *mountpoint; /**< mountpoint in http pathspace, eg, "/" */ const char *origin; /**< path to be mounted, eg, "/var/www/warmcat.com" */ const char *def; /**< default target, eg, "index.html" */ const char *protocol; /**<"protocol-name" to handle mount */ const struct lws_protocol_vhost_options *cgienv; /**< optional linked-list of cgi options. These are created * as environment variables for the cgi process */ const struct lws_protocol_vhost_options *extra_mimetypes; /**< optional linked-list of mimetype mappings */ const struct lws_protocol_vhost_options *interpret; /**< optional linked-list of files to be interpreted */ int cgi_timeout; /**< seconds cgi is allowed to live, if cgi://mount type */ int cache_max_age; /**< max-age for reuse of client cache of files, seconds */ unsigned int auth_mask; /**< bits set here must be set for authorized client session */ unsigned int cache_reusable:1; /**< set if client cache may reuse this */ unsigned int cache_revalidate:1; /**< set if client cache should revalidate on use */ unsigned int cache_intermediaries:1; /**< set if intermediaries are allowed to cache */ unsigned int cache_no:1; /**< set if client should check cache always*/ unsigned char origin_protocol; /**< one of enum lws_mount_protocols */ unsigned char mountpoint_len; /**< length of mountpoint string */ const char *basic_auth_login_file; /**