lws-system.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.
 *
 * This provides a clean way to interface lws user code to be able to
 * work unchanged on different systems for fetching common system information,
 * and performing common system operations like reboot.
 */
 
/*
 * Types of system blob that can be set and retreived
 */
 
typedef enum {
        LWS_SYSBLOB_TYPE_AUTH,
        LWS_SYSBLOB_TYPE_CLIENT_CERT_DER = LWS_SYSBLOB_TYPE_AUTH + 2,
        LWS_SYSBLOB_TYPE_CLIENT_KEY_DER,
        LWS_SYSBLOB_TYPE_DEVICE_SERIAL,
        LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION,
        LWS_SYSBLOB_TYPE_DEVICE_TYPE,
        LWS_SYSBLOB_TYPE_NTP_SERVER,
        LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID,
        LWS_SYSBLOB_TYPE_MQTT_USERNAME,
        LWS_SYSBLOB_TYPE_MQTT_PASSWORD,
 
#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
        /* extend 4 more auth blobs, each has 2 slots */
        LWS_SYSBLOB_TYPE_EXT_AUTH1,
        LWS_SYSBLOB_TYPE_EXT_AUTH2 = LWS_SYSBLOB_TYPE_EXT_AUTH1 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH3 = LWS_SYSBLOB_TYPE_EXT_AUTH2 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH4 = LWS_SYSBLOB_TYPE_EXT_AUTH3 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH4_1,
#endif
 
        LWS_SYSBLOB_TYPE_COUNT /* ... always last */
} lws_system_blob_item_t;
 
/* opaque generic blob whose content may be on-the-heap or pointed-to
 * directly case by case.  When it's on the heap, it can be produced by
 * appending (it's a buflist underneath).  Either way, it can be consumed by
 * copying out a given length from a given offset.
 */
 
typedef struct lws_system_blob lws_system_blob_t;
 
LWS_EXTERN LWS_VISIBLE void
lws_system_blob_direct_set(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
 
LWS_EXTERN LWS_VISIBLE void
lws_system_blob_heap_empty(lws_system_blob_t *b);
 
LWS_EXTERN LWS_VISIBLE int
lws_system_blob_heap_append(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
 
LWS_EXTERN LWS_VISIBLE size_t
lws_system_blob_get_size(lws_system_blob_t *b);
 
/* return 0 and sets *ptr to point to blob data if possible, nonzero = fail */
LWS_EXTERN LWS_VISIBLE int
lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr);
 
LWS_EXTERN LWS_VISIBLE int
lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs);
 
LWS_EXTERN LWS_VISIBLE void
lws_system_blob_destroy(lws_system_blob_t *b);
 
/*
 * Get the opaque blob for index idx of various system blobs.  Returns 0 if
 * *b was set otherwise nonzero means out of range
 */
 
LWS_EXTERN LWS_VISIBLE lws_system_blob_t *
lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type,
                    int idx);
 
/*
 * Lws view of system state... normal operation from user code perspective is
 * dependent on implicit (eg, knowing the date for cert validation) and
 * explicit dependencies.
 *
 * Bit of lws and user code can register notification handlers that can enforce
 * dependent operations before state transitions can complete.
 */
 
typedef enum { /* keep system_state_names[] in sync in context.c */
        LWS_SYSTATE_UNKNOWN,
 
        LWS_SYSTATE_CONTEXT_CREATED,     /* context was just created */
        LWS_SYSTATE_INITIALIZED,         /* protocols initialized.  Lws itself
                                          * can operate normally */
        LWS_SYSTATE_IFACE_COLDPLUG,      /* existing net ifaces iterated */
        LWS_SYSTATE_DHCP,                /* at least one net iface configured */
        LWS_SYSTATE_CPD_PRE_TIME,        /* Captive portal detect without valid
                                          * time, good for non-https tests... if
                                          * you care about it, implement and
                                          * call lws_system_ops_t
                                          * .captive_portal_detect_request()
                                          * and move the state forward according
                                          * to the result. */
        LWS_SYSTATE_TIME_VALID,          /* ntpclient ran, or hw time valid...
                                          * tls cannot work until we reach here
                                          */
        LWS_SYSTATE_CPD_POST_TIME,       /* Captive portal detect after time was
                                          * time, good for https tests... if
                                          * you care about it, implement and
                                          * call lws_system_ops_t
                                          * .captive_portal_detect_request()
                                          * and move the state forward according
                                          * to the result. */
 
        LWS_SYSTATE_POLICY_VALID,        /* user code knows how to operate... */
        LWS_SYSTATE_REGISTERED,          /* device has an identity... */
        LWS_SYSTATE_AUTH1,               /* identity used for main auth token */
        LWS_SYSTATE_AUTH2,               /* identity used for optional auth */
 
        LWS_SYSTATE_ONE_TIME_UPDATES,    /* pre-OPERATIONAL one-time updates,
                                          * when a firmware needs to perform
                                          * one-time upgrades to state before
                                          * OPERATIONAL */
 
        LWS_SYSTATE_OPERATIONAL,         /* user code can operate normally */
 
        LWS_SYSTATE_POLICY_INVALID,      /* user code is changing its policies
                                          * drop everything done with old
                                          * policy, switch to new then enter
                                          * LWS_SYSTATE_POLICY_VALID */
        LWS_SYSTATE_CONTEXT_DESTROYING,  /* Context is being destroyed */
        LWS_SYSTATE_AWAITING_MODAL_UPDATING,     /* We're negotiating with the
                                                  * user code for update mode */
        LWS_SYSTATE_MODAL_UPDATING,      /* We're updating the firmware */
} lws_system_states_t;
 
/* Captive Portal Detect -related */
 
typedef enum {
        LWS_CPD_UNKNOWN = 0,    /* test didn't happen ince last DHCP acq yet */
        LWS_CPD_INTERNET_OK,    /* no captive portal: our CPD test passed OK,
                                 * we can go out on the internet */
        LWS_CPD_CAPTIVE_PORTAL, /* we inferred we're behind a captive portal */
        LWS_CPD_NO_INTERNET,    /* we couldn't touch anything */
} lws_cpd_result_t;
 
typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);
struct lws_attach_item;
 
LWS_EXTERN LWS_VISIBLE int
lws_tls_jit_trust_got_cert_cb(struct lws_context *cx, void *got_opaque,
                              const uint8_t *skid, size_t skid_len,
                              const uint8_t *der, size_t der_len);
 
typedef struct lws_system_ops {
        int (*reboot)(void);
        int (*set_clock)(lws_usec_t us);
        int (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb,
                      lws_system_states_t state, void *opaque,
                      struct lws_attach_item **get);
        int (*captive_portal_detect_request)(struct lws_context *context);
#if defined(LWS_WITH_NETWORK)
        int (*metric_report)(lws_metric_pub_t *mdata);
#endif
        int (*jit_trust_query)(struct lws_context *cx, const uint8_t *skid,
                               size_t skid_len, void *got_opaque);
#if defined(LWS_WITH_OTA)
        lws_ota_ops_t           ota_ops;
#endif
 
        uint32_t                wake_latency_us;
} lws_system_ops_t;
 
#if defined(LWS_WITH_SYS_STATE)
 
LWS_EXTERN LWS_VISIBLE lws_state_manager_t *
lws_system_get_state_manager(struct lws_context *context);
 
#endif
 
/* wrappers handle NULL members or no ops struct set at all cleanly */
 
#define LWSSYSGAUTH_HEX (1 << 0)
 
LWS_EXTERN LWS_VISIBLE const lws_system_ops_t *
lws_system_get_ops(struct lws_context *context);
 
#if defined(LWS_WITH_SYS_STATE)
 
LWS_EXTERN LWS_VISIBLE struct lws_context *
lws_system_context_from_system_mgr(lws_state_manager_t *mgr);
 
#endif
 
LWS_EXTERN LWS_VISIBLE int
__lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t cb,
                    lws_system_states_t state, void *opaque,
                    struct lws_attach_item **get);
 
 
enum {
        LWSDH_IPV4_SUBNET_MASK          = 0,
        LWSDH_IPV4_BROADCAST,
        LWSDH_LEASE_SECS,
        LWSDH_REBINDING_SECS,
        LWSDH_RENEWAL_SECS,
 
        _LWSDH_NUMS_COUNT,
 
        LWSDH_SA46_IP                   = 0,
        LWSDH_SA46_DNS_SRV_1,
        LWSDH_SA46_DNS_SRV_2,
        LWSDH_SA46_DNS_SRV_3,
        LWSDH_SA46_DNS_SRV_4,
        LWSDH_SA46_IPV4_ROUTER,
        LWSDH_SA46_NTP_SERVER,
        LWSDH_SA46_DHCP_SERVER,
 
        _LWSDH_SA46_COUNT,
};
 
#if defined(LWS_WITH_NETWORK)
typedef struct lws_dhcpc_ifstate {
        char                            ifname[16];
        char                            domain[64];
        uint8_t                         mac[6];
        uint32_t                        nums[_LWSDH_NUMS_COUNT];
        lws_sockaddr46                  sa46[_LWSDH_SA46_COUNT];
} lws_dhcpc_ifstate_t;
 
typedef int (*dhcpc_cb_t)(void *opaque, lws_dhcpc_ifstate_t *is);
 
LWS_EXTERN LWS_VISIBLE int
lws_dhcpc_request(struct lws_context *c, const char *i, int af, dhcpc_cb_t cb,
                void *opaque);
 
LWS_EXTERN LWS_VISIBLE int
lws_dhcpc_remove(struct lws_context *context, const char *iface);
 
LWS_EXTERN LWS_VISIBLE int
lws_dhcpc_status(struct lws_context *context, lws_sockaddr46 *sa46);
 
LWS_EXTERN LWS_VISIBLE int
lws_system_cpd_start(struct lws_context *context);
 
LWS_EXTERN LWS_VISIBLE void
lws_system_cpd_start_defer(struct lws_context *cx, lws_usec_t defer_us);
 
 
LWS_EXTERN LWS_VISIBLE void
lws_system_cpd_set(struct lws_context *context, lws_cpd_result_t result);
 
 
LWS_EXTERN LWS_VISIBLE lws_cpd_result_t
lws_system_cpd_state_get(struct lws_context *context);
 
#endif