lws-context-vhost.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
 *
 * 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.
 */

 
/*
 * 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))

#define LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME              (1ll << 2)
#define LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT              ((1ll << 3) | \
                                                                  (1ll << 12))

#define LWS_SERVER_OPTION_LIBEV                                  (1ll << 4)
#define LWS_SERVER_OPTION_DISABLE_IPV6                           (1ll << 5)
#define LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS                    (1ll << 6)
#define LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED                 (1ll << 7)
#define LWS_SERVER_OPTION_VALIDATE_UTF8                          (1ll << 8)
#define LWS_SERVER_OPTION_SSL_ECDH                               ((1ll << 9) | \
                                                                  (1ll << 12))

#define LWS_SERVER_OPTION_LIBUV                                 (1ll << 10)
#define LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS                ((1ll << 11) |\
                                                                 (1ll << 12))

#define LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT                     (1ll << 12)
#define LWS_SERVER_OPTION_EXPLICIT_VHOSTS                        (1ll << 13)
#define LWS_SERVER_OPTION_UNIX_SOCK                              (1ll << 14)
#define LWS_SERVER_OPTION_STS                                    (1ll << 15)
#define LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY                     (1ll << 16)
#define LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE                      (1ll << 17)
#define LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN              (1ll << 18)
#define LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN                    (1ll << 19)
#define LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */   (1ll << 20)
#define LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20)
 
#define LWS_SERVER_OPTION_LIBEVENT                              (1ll << 21)
 
#define LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */ (1ll << 22)
#define LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG      (1ll << 22)
#define LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE                    (1ll << 23)
#define LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX                  (1ll << 24)
#define LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT                    (1ll << 25)
#define LWS_SERVER_OPTION_IGNORE_MISSING_CERT                   (1ll << 26)
#define LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK           (1ll << 27)
#define LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28)
 
#define LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER           (1ll << 29)
#define LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND               (1ll << 30)
 
#define LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW     (1ll << 31)
 
#define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL            (1ll << 32)
#define LWS_SERVER_OPTION_DISABLE_UTF8_VALIDATION                (1ll << 34)
 
        /****** add new things just above ---^ ******/
 
#define LWS_SERVER_OPTION_GLIB                                   (1ll << 33)
 
#define LWS_SERVER_OPTION_QUIC_FORCE_RETRY                      (1ll << 52)
 
#define LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE                     (1ll << 34)
 
#define LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES                   (1ll << 35)
 
#define LWS_SERVER_OPTION_SS_PROXY                               (1ll << 36)
 
#define LWS_SERVER_OPTION_SDEVENT                                (1ll << 37)
 
#define LWS_SERVER_OPTION_ULOOP                                  (1ll << 38)
 
#define LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE              (1ll << 39)
 
#define LWS_SERVER_OPTION_OPENSSL_AUTO_DH_PARAMETERS             (1ll << 40)
 
#define LWS_SERVER_OPTION_MBEDTLS_VERIFY_CLIENT_CERT_POST_HANDSHAKE      ((1ll << 41) | \
                                                                 (1ll << 12))

 
#define LWS_SERVER_OPTION_VH_INSTANTIATE_ALL_PROTOCOLS          (1ll << 42)
 
#define LWS_SERVER_OPTION_VH_SKIP_PRIV_DROP                     (1ll << 43)
 
#define LWS_SERVER_OPTION_CMDLINE_FORCE_H1                      (1ll << 44)
 
#define LWS_SERVER_OPTION_CMDLINE_FORCE_H2                      (1ll << 45)
 
#define LWS_SERVER_OPTION_CMDLINE_FORCE_H3                      (1ll << 46)
 
#define LWS_SERVER_OPTION_ALLOW_EARLY_DATA                      (1ll << 47)
 
#define LWS_SERVER_OPTION_CPD_BYPASS                            (1ll << 48)
 
#define LWS_SERVER_OPTION_QUIC_PAD_CRYPTO                       (1ll << 49)
 
#define LWS_SERVER_OPTION_QUIC_EARLY_KEY_UPDATE                 (1ll << 51)
 
#define LWS_SERVER_OPTION_QUIC_LATEST_VERSION                   (1ll << 50)
 
        /****** 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

typedef uint64_t (*lws_quic_tx_credit_cb_t)(struct lws *wsi, uint64_t current_window,
                                            uint64_t consumed_bytes, uint64_t time_since_last_update_us);

struct lws_context_creation_info {
#if defined(LWS_WITH_NETWORK)
        const char *iface;
        const struct lws_protocols *protocols;
#if defined(LWS_ROLE_WS)
        const struct lws_extension *extensions;
#endif
#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_H3)
        const struct lws_token_limits *token_limits;
        const char *http_proxy_address;
        const struct lws_protocol_vhost_options *headers;
 
        const struct lws_protocol_vhost_options *reject_service_keywords;
#endif
        const struct lws_protocol_vhost_options *pvo;
        const char *log_filepath;
#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_H3)
        const struct lws_http_mount *mounts;
        const char *server_string;
 
        const char *error_document_404;
#endif
        int port;
 
#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_H3)
        unsigned int http_proxy_port;
        unsigned int max_http_header_data2;
        unsigned int max_http_header_pool2;
#endif
 
        int keepalive_timeout;
#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_H3)
        uint32_t        http2_settings[7];
 
        unsigned short max_http_header_data;
        unsigned short max_http_header_pool;
 
#endif
 
#if defined(LWS_WITH_TLS)
        const char *ssl_private_key_password;
        const char *ssl_cert_filepath;
        const char *ssl_private_key_filepath;
        const char *ssl_ca_filepath;
        const char *ssl_cipher_list;
        const char *tls_ciphers_iana;
        const char *ecdh_curve;
        const char *client_ecdh_curve;
        const char *tls1_3_plus_cipher_list;
 
        const void *server_ssl_cert_mem;
        const void *server_ssl_private_key_mem;
        const void *server_ssl_ca_mem;
 
        long ssl_options_set;
        long ssl_options_clear;
        int simultaneous_ssl_restriction;
        int simultaneous_ssl_handshake_restriction;
        int ssl_info_event_mask;
        unsigned int server_ssl_cert_mem_len;
        unsigned int server_ssl_private_key_mem_len;
        unsigned int server_ssl_ca_mem_len;
 
        const char *alpn;
 
 
#if defined(LWS_WITH_CLIENT)
        const char *client_ssl_private_key_password;
        const char *client_ssl_cert_filepath;
        const void *client_ssl_cert_mem;
        unsigned int client_ssl_cert_mem_len;
        const char *client_ssl_private_key_filepath;
        const void *client_ssl_key_mem;
        const char *client_ssl_ca_filepath;
        const void *client_ssl_ca_mem;
 
        const char *client_ssl_cipher_list;
        const char *client_tls_ciphers_iana;
        const char *client_tls_1_3_plus_cipher_list;
 
        long ssl_client_options_set;
        long ssl_client_options_clear;
 
 
        unsigned int client_ssl_ca_mem_len;
        unsigned int client_ssl_key_mem_len;
 
#endif
 
#if !defined(LWS_WITH_MBEDTLS) && !defined(LWS_WITH_BEARSSL) && \
        !defined(LWS_WITH_OPENHITLS)
        SSL_CTX *provided_client_ssl_ctx;
#elif defined(LWS_WITH_MBEDTLS)
        const char *mbedtls_client_preload_filepath;
#endif
#endif
 
        int ka_time;
        int ka_probes;
        int ka_interval;
        unsigned int timeout_secs;
        unsigned int connect_timeout_secs;
        int bind_iface;
        unsigned int timeout_secs_ah_idle;
#endif /* WITH_NETWORK */
 
#if defined(LWS_WITH_TLS_SESSIONS)
        uint32_t                        tls_session_timeout;
        uint32_t                        tls_session_cache_max;
#endif
 
        gid_t gid;
        uid_t uid;
        uint64_t options;
        void *user;
        unsigned int count_threads;
        unsigned int fd_limit_per_thread;
        const char *vhost_name;
#if defined(LWS_WITH_PLUGINS)
        const char * const *plugin_dirs;
#endif
        void *external_baggage_free_on_destroy;
 
 
        unsigned int pt_serv_buf_size;
#if defined(LWS_WITH_FILE_OPS)
        const struct lws_plat_file_ops *fops;
#endif
 
#if defined(LWS_WITH_SOCKS5)
        const char *socks_proxy_address;
        unsigned int socks_proxy_port;
#endif
 
#if defined(LWS_HAVE_SYS_CAPABILITY_H) && defined(LWS_HAVE_LIBCAP)
        cap_value_t caps[4];
        char count_caps;
#endif
        void **foreign_loops;
        void (*signal_cb)(void *event_lib_handle, int signum);
        struct lws_context **pcontext;
        void (*finalize)(struct lws_vhost *vh, void *arg);
        void *finalize_arg;
        const char *listen_accept_role;
        const char *listen_accept_protocol;
        const struct lws_protocols **pprotocols;
 
        const char *username; 
        const char *groupname; 
        const char *unix_socket_perms; 
        const lws_system_ops_t *system_ops;
        const lws_retry_bo_t *retry_and_idle_policy;
#if defined(LWS_WITH_SYS_STATE)
        lws_state_notify_link_t * const *register_notifier_list;
#endif
#if defined(LWS_WITH_SECURE_STREAMS)
#if defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
        const struct lws_ss_policy *pss_policies; 
#else
        const char *pss_policies_json; 
#endif
        const struct lws_ss_plugin **pss_plugins; 
        const char *ss_proxy_bind; 
        const char *ss_proxy_address; 
        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; 
        const void *txp_ssproxy_info; 
        const struct lws_transport_client_ops *txp_ops_sspc; 
#endif
 
#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
#endif
 
        int rlimit_nofile;
#if defined(LWS_WITH_PEER_LIMITS)
        lws_peer_limits_notify_t pl_notify_cb;
        unsigned short ip_limit_ah;
        unsigned short ip_limit_wsi;
 
#endif /* PEER_LIMITS */
 
#if defined(LWS_WITH_SYS_FAULT_INJECTION)
        lws_fi_ctx_t                            fic;
#endif
 
#if defined(LWS_WITH_SYS_SMD)
        lws_smd_notification_cb_t               early_smd_cb;
        void                                    *early_smd_opaque;
        lws_smd_class_t                         early_smd_class_filter;
        lws_usec_t                              smd_ttl_us;
        uint16_t                                smd_queue_depth;
#endif
 
#if defined(LWS_WITH_SYS_METRICS)
        const struct lws_metric_policy          *metrics_policies;
        const char                              *metrics_prefix;
#endif
 
        int                                     fo_listen_queue;
 
        const struct lws_plugin_evlib           *event_lib_custom;
 
#if defined(LWS_WITH_TLS_JIT_TRUST)
        size_t                                  jitt_cache_max_footprint;
        int                                     vh_idle_grace_ms;
#endif
 
        lws_log_cx_t                            *log_cx;
 
#if defined(LWS_WITH_CACHE_NSCOOKIEJAR) && defined(LWS_WITH_CLIENT)
        const char                              *http_nsc_filepath;
 
        size_t                                  http_nsc_heap_max_footprint;
        size_t                                  http_nsc_heap_max_items;
        size_t                                  http_nsc_heap_max_payload;
#endif
 
#if defined(LWS_WITH_SYS_ASYNC_DNS)
        const char                              **async_dns_servers;
 
#endif
 
#if defined(WIN32)
        unsigned int win32_connect_check_interval_usec;
#endif
 
        int default_loglevel;
 
        lws_sockfd_type         vh_listen_sockfd;
 
#if defined(LWS_WITH_NETWORK)
        const char              *wol_if;
#endif
 
        const char              *lws_stub;
        int                     argc;
        const char              **argv;
 
#if defined(LWS_WITH_ASYNC_QUEUE)
        uint8_t                 count_async_threads;
#endif
 
        /* 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.
         */
 
        uint32_t                        quic_mtu;
 
        lws_quic_tx_credit_cb_t         quic_tx_credit_cb;
 
        const struct lws_cc_ops         *quic_cc_ops;
 
        const char                      *quic_preferred_addresses;
 
        uint32_t                        quic_initial_cwnd;
 
        uint32_t                        quic_0rtt_max_size;
 
        uint64_t                        max_http_body_size;
 
#if !defined(__STRICT_ANSI__)
        void *_unused[1]; 
#endif
};

LWS_VISIBLE LWS_EXTERN struct lws_context *
lws_create_context(const struct lws_context_creation_info *info);
 

LWS_VISIBLE LWS_EXTERN void
lws_context_destroy(struct lws_context *context);

LWS_VISIBLE LWS_EXTERN void
lws_tls_cleanup_process(void);
 
typedef int (*lws_reload_func)(void);

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_VISIBLE LWS_EXTERN int
lws_set_proxy(struct lws_vhost *vhost, const char *proxy);

LWS_VISIBLE LWS_EXTERN int
lws_set_socks(struct lws_vhost *vhost, const char *socks);
 
struct lws_vhost;

LWS_VISIBLE LWS_EXTERN struct lws_vhost *
lws_create_vhost(struct lws_context *context,
                 const struct lws_context_creation_info *info);

LWS_VISIBLE LWS_EXTERN void
lws_vhost_destroy(struct lws_vhost *vh);

LWS_VISIBLE LWS_EXTERN int
lwsws_get_config_globals(struct lws_context_creation_info *info, const char *d,
                         char **config_strings, int *len);

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_VISIBLE LWS_EXTERN struct lws_vhost *
lws_get_vhost(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN const char *
lws_get_vhost_name(struct lws_vhost *vhost);

LWS_VISIBLE LWS_EXTERN struct lws_vhost *
lws_get_vhost_by_name(struct lws_context *context, const char *name);

LWS_VISIBLE LWS_EXTERN int
lws_get_vhost_port(struct lws_vhost *vhost);

LWS_VISIBLE LWS_EXTERN void *
lws_get_vhost_user(struct lws_vhost *vhost);

LWS_VISIBLE LWS_EXTERN const char *
lws_get_vhost_iface(struct lws_vhost *vhost);

LWS_VISIBLE LWS_EXTERN void *
lws_vhost_user(struct lws_vhost *vhost);

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_VISIBLE LWS_EXTERN int
lws_systemd_inherited_fd(unsigned int index,
                         struct lws_context_creation_info *info);

LWS_VISIBLE LWS_EXTERN int
lws_context_is_being_destroyed(struct lws_context *context);


struct lws_protocol_vhost_options {
        const struct lws_protocol_vhost_options *next; 
        const struct lws_protocol_vhost_options *options; 
        const char *name; 
        const char *value; 
};

enum lws_mount_protocols {
        LWSMPRO_HTTP            = 0, 
        LWSMPRO_HTTPS           = 1, 
        LWSMPRO_FILE            = 2, 
        LWSMPRO_CGI             = 3, 
        LWSMPRO_REDIR_HTTP      = 4, 
        LWSMPRO_REDIR_HTTPS     = 5, 
        LWSMPRO_CALLBACK        = 6, 
        LWSMPRO_NO_MOUNT        = 7, 
};

enum lws_authentication_mode {
        LWSAUTHM_DEFAULT = 0, 
        LWSAUTHM_BASIC_AUTH_CALLBACK = 1 << 28 
};

#define AUTH_MODE_MASK 0xF0000000

struct lws_http_mount {
        const struct lws_http_mount *mount_next;
        const char *mountpoint;
        const char *origin;
        const char *def;
        const char *protocol;
 
        const struct lws_protocol_vhost_options *cgienv;
        const struct lws_protocol_vhost_options *extra_mimetypes;
        const struct lws_protocol_vhost_options *interpret;
 
        int cgi_timeout;
        int cache_max_age;
        unsigned int auth_mask;
 
        unsigned int cache_reusable:1; 
        unsigned int cache_revalidate:1; 
        unsigned int cache_intermediaries:1; 
        unsigned int cache_no:1; 
        unsigned int exact_match:1; 
        unsigned int append_path:1; 
        unsigned int no_ws_upgrades:1; 
 
        unsigned char origin_protocol; 
        unsigned char mountpoint_len; 
 
        const char *basic_auth_login_file;
 
        const char *cgi_chroot_path;
 
        const char *cgi_wd;
 
        const struct lws_protocol_vhost_options *headers;
        unsigned int keepalive_timeout;
#if defined(LWS_WITH_JOSE)
        const char *interceptor_path;
#endif
 
        uint64_t max_http_body_size;
 
        /* Add new things just above here ---^
         * This is part of the ABI, don't needlessly break compatibility
         */
};
 
LWS_VISIBLE LWS_EXTERN void
lws_vhost_set_mounts(struct lws_vhost *v, const struct lws_http_mount *mounts);