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 * This provides a clean way to interface lws user code to be able to 25 * work unchanged on different systems for fetching common system information, 26 * and performing common system operations like reboot. 27 */ 28 29/* 30 * Types of system blob that can be set and retreived 31 */ 32 33typedef enum { 34 LWS_SYSBLOB_TYPE_AUTH, 35 LWS_SYSBLOB_TYPE_CLIENT_CERT_DER = LWS_SYSBLOB_TYPE_AUTH + 2, 36 LWS_SYSBLOB_TYPE_CLIENT_KEY_DER, 37 LWS_SYSBLOB_TYPE_DEVICE_SERIAL, 38 LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION, 39 LWS_SYSBLOB_TYPE_DEVICE_TYPE, 40 LWS_SYSBLOB_TYPE_NTP_SERVER, 41 LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID, 42 LWS_SYSBLOB_TYPE_MQTT_USERNAME, 43 LWS_SYSBLOB_TYPE_MQTT_PASSWORD, 44 45#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4) 46 /* extend 4 more auth blobs, each has 2 slots */ 47 LWS_SYSBLOB_TYPE_EXT_AUTH1, 48 LWS_SYSBLOB_TYPE_EXT_AUTH2 = LWS_SYSBLOB_TYPE_EXT_AUTH1 + 2, 49 LWS_SYSBLOB_TYPE_EXT_AUTH3 = LWS_SYSBLOB_TYPE_EXT_AUTH2 + 2, 50 LWS_SYSBLOB_TYPE_EXT_AUTH4 = LWS_SYSBLOB_TYPE_EXT_AUTH3 + 2, 51 LWS_SYSBLOB_TYPE_EXT_AUTH4_1, 52#endif 53 54 LWS_SYSBLOB_TYPE_COUNT /* ... always last */ 55} lws_system_blob_item_t; 56 57/* opaque generic blob whose content may be on-the-heap or pointed-to 58 * directly case by case. When it's on the heap, it can be produced by 59 * appending (it's a buflist underneath). Either way, it can be consumed by 60 * copying out a given length from a given offset. 61 */ 62 63typedef struct lws_system_blob lws_system_blob_t; 64 65LWS_EXTERN LWS_VISIBLE void 66lws_system_blob_direct_set(lws_system_blob_t *b, const uint8_t *ptr, size_t len); 67 68LWS_EXTERN LWS_VISIBLE void 69lws_system_blob_heap_empty(lws_system_blob_t *b); 70 71LWS_EXTERN LWS_VISIBLE int 72lws_system_blob_heap_append(lws_system_blob_t *b, const uint8_t *ptr, size_t len); 73 74LWS_EXTERN LWS_VISIBLE size_t 75lws_system_blob_get_size(lws_system_blob_t *b); 76 77/* return 0 and sets *ptr to point to blob data if possible, nonzero = fail */ 78LWS_EXTERN LWS_VISIBLE int 79lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr); 80 81LWS_EXTERN LWS_VISIBLE int 82lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs); 83 84LWS_EXTERN LWS_VISIBLE void 85lws_system_blob_destroy(lws_system_blob_t *b); 86 87/* 88 * Get the opaque blob for index idx of various system blobs. Returns 0 if 89 * *b was set otherwise nonzero means out of range 90 */ 91 92LWS_EXTERN LWS_VISIBLE lws_system_blob_t * 93lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type, 94 int idx); 95 96/* 97 * Lws view of system state... normal operation from user code perspective is 98 * dependent on implicit (eg, knowing the date for cert validation) and 99 * explicit dependencies. 100 * 101 * Bit of lws and user code can register notification handlers that can enforce 102 * dependent operations before state transitions can complete. 103 */ 104 105typedef enum { /* keep system_state_names[] in sync in context.c */ 106 LWS_SYSTATE_UNKNOWN, 107 108 LWS_SYSTATE_CONTEXT_CREATED, /* context was just created */ 109 LWS_SYSTATE_INITIALIZED, /* protocols initialized. Lws itself 110 * can operate normally */ 111 LWS_SYSTATE_IFACE_COLDPLUG, /* existing net ifaces iterated */ 112 LWS_SYSTATE_DHCP, /* at least one net iface configured */ 113 LWS_SYSTATE_CPD_PRE_TIME, /* Captive portal detect without valid 114 * time, good for non-https tests... if 115 * you care about it, implement and 116 * call lws_system_ops_t 117 * .captive_portal_detect_request() 118 * and move the state forward according 119 * to the result. */ 120 LWS_SYSTATE_TIME_VALID, /* ntpclient ran, or hw time valid... 121 * tls cannot work until we reach here 122 */ 123 LWS_SYSTATE_CPD_POST_TIME, /* Captive portal detect after time was 124 * time, good for https tests... if 125 * you care about it, implement and 126 * call lws_system_ops_t 127 * .captive_portal_detect_request() 128 * and move the state forward according 129 * to the result. */ 130 131 LWS_SYSTATE_POLICY_VALID, /* user code knows how to operate... */ 132 LWS_SYSTATE_REGISTERED, /* device has an identity... */ 133 LWS_SYSTATE_AUTH1, /* identity used for main auth token */ 134 LWS_SYSTATE_AUTH2, /* identity used for optional auth */ 135 136 LWS_SYSTATE_OPERATIONAL, /* user code can operate normally */ 137 138 LWS_SYSTATE_POLICY_INVALID, /* user code is changing its policies 139 * drop everything done with old 140 * policy, switch to new then enter 141 * LWS_SYSTATE_POLICY_VALID */ 142 LWS_SYSTATE_CONTEXT_DESTROYING, /* Context is being destroyed */ 143} lws_system_states_t; 144 145/* Captive Portal Detect -related */ 146 147typedef enum { 148 LWS_CPD_UNKNOWN = 0, /* test didn't happen ince last DHCP acq yet */ 149 LWS_CPD_INTERNET_OK, /* no captive portal: our CPD test passed OK, 150 * we can go out on the internet */ 151 LWS_CPD_CAPTIVE_PORTAL, /* we inferred we're behind a captive portal */ 152 LWS_CPD_NO_INTERNET, /* we couldn't touch anything */ 153} lws_cpd_result_t; 154 155typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque); 156struct lws_attach_item; 157 158LWS_EXTERN LWS_VISIBLE int 159lws_tls_jit_trust_got_cert_cb(struct lws_context *cx, void *got_opaque, 160 const uint8_t *skid, size_t skid_len, 161 const uint8_t *der, size_t der_len); 162 163typedef struct lws_system_ops { 164 int (*reboot)(void); 165 int (*set_clock)(lws_usec_t us); 166 int (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb, 167 lws_system_states_t state, void *opaque, 168 struct lws_attach_item **get); 169 /**< if \p get is NULL, add an attach callback request to the pt for 170 * \p cb with arg \p opaque, that should be called when we're at or past 171 * system state \p state. 172 * 173 * If \p get is non-NULL, look for the first listed item on the pt whose 174 * state situation is ready, and set *get to point to it. If no items, 175 * or none where the system state is right, set *get to NULL. 176 * 177 * It's done like this so (*attach) can perform system-specific 178 * locking outside of lws core, for both getting and adding items the 179 * same so it is thread-safe. A non-threadsafe helper 180 * __lws_system_attach() is provided to do the actual work inside the 181 * system-specific locking. 182 */ 183 int (*captive_portal_detect_request)(struct lws_context *context); 184 /**< Check if we can go out on the internet cleanly, or if we are being 185 * redirected or intercepted by a captive portal. 186 * Start the check that proceeds asynchronously, and report the results 187 * by calling lws_captive_portal_detect_result() api 188 */ 189 190 int (*metric_report)(lws_metric_pub_t *mdata); 191 /**< metric \p item is reporting an event of kind \p rpt, 192 * held in \p mdata... return 0 to leave the metric object as it is, 193 * or nonzero to reset it. */ 194 195 int (*jit_trust_query)(struct lws_context *cx, const uint8_t *skid, 196 size_t skid_len, void *got_opaque); 197 /**< user defined trust store search, if we do trust a cert with SKID 198 * matching skid / skid_len, then it should get hold of the DER for the 199 * matching root CA and call 200 * lws_tls_jit_trust_got_cert_cb(..., got_opaque) before cleaning up and 201 * returning. The DER should be destroyed if in heap before returning. 202 */ 203 204 uint32_t wake_latency_us; 205 /**< time taken for this device to wake from suspend, in us 206 */ 207} lws_system_ops_t; 208 209#if defined(LWS_WITH_SYS_STATE) 210 211/** 212 * lws_system_get_state_manager() - return the state mgr object for system state 213 * 214 * \param context: the lws_context 215 * 216 * The returned pointer can be used with the lws_state_ apis 217 */ 218 219LWS_EXTERN LWS_VISIBLE lws_state_manager_t * 220lws_system_get_state_manager(struct lws_context *context); 221 222#endif 223 224/* wrappers handle NULL members or no ops struct set at all cleanly */ 225 226#define LWSSYSGAUTH_HEX (1 << 0) 227 228/** 229 * lws_system_get_ops() - get ahold of the system ops struct from the context 230 * 231 * \param context: the lws_context 232 * 233 * Returns the system ops struct. It may return NULL and if not, anything in 234 * there may be NULL. 235 */ 236LWS_EXTERN LWS_VISIBLE const lws_system_ops_t * 237lws_system_get_ops(struct lws_context *context); 238 239#if defined(LWS_WITH_SYS_STATE) 240 241/** 242 * lws_system_context_from_system_mgr() - return context from system state mgr 243 * 244 * \param mgr: pointer to specifically the system state mgr 245 * 246 * Returns the context from the system state mgr. Helper since the lws_context 247 * is opaque. 248 */ 249LWS_EXTERN LWS_VISIBLE struct lws_context * 250lws_system_context_from_system_mgr(lws_state_manager_t *mgr); 251 252#endif 253 254/** 255 * __lws_system_attach() - get and set items on context attach list 256 * 257 * \param context: context to get or set attach items to 258 * \param tsi: thread service index (normally 0) 259 * \param cb: callback to call from context event loop thread 260 * \param state: the lws_system state we have to be in or have passed through 261 * \param opaque: optional pointer to user specific info given to callback 262 * \param get: NULL, or pointer to pointer to take detached tail item on exit 263 * 264 * This allows other threads to enqueue callback requests to happen from a pt's 265 * event loop thread safely. The callback gets the context pointer and a user 266 * opaque pointer that can be optionally given when the item is added to the 267 * attach list. 268 * 269 * This api is the no-locking core function for getting and setting items on the 270 * pt's attach list. The lws_system operation (*attach) is the actual 271 * api that user and internal code calls for this feature, it should perform 272 * system-specific locking, call this helper, release the locking and then 273 * return the result. This api is public only so it can be used in the locked 274 * implementation of (*attach). 275 * 276 * If get is NULL, then the call adds to the head of the pt attach list using 277 * cb, state, and opaque; if get is non-NULL, then *get is set to the first 278 * waiting attached item that meets the state criteria and that item is removed 279 * from the list. 280 * 281 * This is a non-threadsafe helper only designed to be called from 282 * implementations of struct lws_system's (*attach) operation where system- 283 * specific locking has been applied around it, making it threadsafe. 284 */ 285LWS_EXTERN LWS_VISIBLE int 286__lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t cb, 287 lws_system_states_t state, void *opaque, 288 struct lws_attach_item **get); 289 290 291enum { 292 LWSDH_IPV4_SUBNET_MASK = 0, 293 LWSDH_IPV4_BROADCAST, 294 LWSDH_LEASE_SECS, 295 LWSDH_REBINDING_SECS, 296 LWSDH_RENEWAL_SECS, 297 298 _LWSDH_NUMS_COUNT, 299 300 LWSDH_SA46_IP = 0, 301 LWSDH_SA46_DNS_SRV_1, 302 LWSDH_SA46_DNS_SRV_2, 303 LWSDH_SA46_DNS_SRV_3, 304 LWSDH_SA46_DNS_SRV_4, 305 LWSDH_SA46_IPV4_ROUTER, 306 LWSDH_SA46_NTP_SERVER, 307 LWSDH_SA46_DHCP_SERVER, 308 309 _LWSDH_SA46_COUNT, 310}; 311 312typedef struct lws_dhcpc_ifstate { 313 char ifname[16]; 314 char domain[64]; 315 uint8_t mac[6]; 316 uint32_t nums[_LWSDH_NUMS_COUNT]; 317 lws_sockaddr46 sa46[_LWSDH_SA46_COUNT]; 318} lws_dhcpc_ifstate_t; 319 320typedef int (*dhcpc_cb_t)(void *opaque, lws_dhcpc_ifstate_t *is); 321 322/** 323 * lws_dhcpc_request() - add a network interface to dhcpc management 324 * 325 * \param c: the lws_context 326 * \param i: the interface name, like "eth0" 327 * \param af: address family 328 * \param cb: the change callback 329 * \param opaque: opaque pointer given to the callback 330 * 331 * Register a network interface as being managed by DHCP. lws will proceed to 332 * try to acquire an IP. Requires LWS_WITH_SYS_DHCP_CLIENT at cmake. 333 */ 334LWS_EXTERN LWS_VISIBLE int 335lws_dhcpc_request(struct lws_context *c, const char *i, int af, dhcpc_cb_t cb, 336 void *opaque); 337 338/** 339 * lws_dhcpc_remove() - remove a network interface to dhcpc management 340 * 341 * \param context: the lws_context 342 * \param iface: the interface name, like "eth0" 343 * 344 * Remove handling of the network interface from dhcp. 345 */ 346LWS_EXTERN LWS_VISIBLE int 347lws_dhcpc_remove(struct lws_context *context, const char *iface); 348 349/** 350 * lws_dhcpc_status() - has any interface reached BOUND state 351 * 352 * \param context: the lws_context 353 * \param sa46: set to a DNS server from a bound interface, or NULL 354 * 355 * Returns 1 if any network interface managed by dhcpc has reached the BOUND 356 * state (has acquired an IP, gateway and DNS server), otherwise 0. 357 */ 358LWS_EXTERN LWS_VISIBLE int 359lws_dhcpc_status(struct lws_context *context, lws_sockaddr46 *sa46); 360 361/** 362 * lws_system_cpd_start() - helper to initiate captive portal detection 363 * 364 * \param context: the lws_context 365 * 366 * Resets the context's captive portal state to LWS_CPD_UNKNOWN and calls the 367 * lws_system_ops_t captive_portal_detect_request() implementation to begin 368 * testing the captive portal state. 369 */ 370LWS_EXTERN LWS_VISIBLE int 371lws_system_cpd_start(struct lws_context *context); 372 373LWS_EXTERN LWS_VISIBLE void 374lws_system_cpd_start_defer(struct lws_context *cx, lws_usec_t defer_us); 375 376 377/** 378 * lws_system_cpd_set() - report the result of the captive portal detection 379 * 380 * \param context: the lws_context 381 * \param result: one of the LWS_CPD_ constants representing captive portal state 382 * 383 * Sets the context's captive portal detection state to result. User captive 384 * portal detection code would call this once it had a result from its test. 385 */ 386LWS_EXTERN LWS_VISIBLE void 387lws_system_cpd_set(struct lws_context *context, lws_cpd_result_t result); 388 389 390/** 391 * lws_system_cpd_state_get() - returns the last tested captive portal state 392 * 393 * \param context: the lws_context 394 * 395 * Returns one of the LWS_CPD_ constants indicating the system's understanding 396 * of the current captive portal situation. 397 */ 398LWS_EXTERN LWS_VISIBLE lws_cpd_result_t 399lws_system_cpd_state_get(struct lws_context *context); 400