libwebsockets
Lightweight C library for HTML5 websockets
lws-system.h
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 
33 typedef 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 
63 typedef struct lws_system_blob lws_system_blob_t;
64 
65 LWS_EXTERN LWS_VISIBLE void
66 lws_system_blob_direct_set(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
67 
68 LWS_EXTERN LWS_VISIBLE void
69 lws_system_blob_heap_empty(lws_system_blob_t *b);
70 
71 LWS_EXTERN LWS_VISIBLE int
72 lws_system_blob_heap_append(lws_system_blob_t *b, const uint8_t *ptr, size_t len);
73 
74 LWS_EXTERN LWS_VISIBLE size_t
75 lws_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 */
78 LWS_EXTERN LWS_VISIBLE int
79 lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr);
80 
81 LWS_EXTERN LWS_VISIBLE int
82 lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs);
83 
84 LWS_EXTERN LWS_VISIBLE void
85 lws_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 
92 LWS_EXTERN LWS_VISIBLE lws_system_blob_t *
93 lws_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 
105 typedef 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 
147 typedef 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 
155 typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);
156 struct lws_attach_item;
157 
158 LWS_EXTERN LWS_VISIBLE int
159 lws_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 
163 typedef 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);
183  int (*captive_portal_detect_request)(struct lws_context *context);
190 #if defined(LWS_WITH_NETWORK)
191  int (*metric_report)(lws_metric_pub_t *mdata);
195 #endif
196  int (*jit_trust_query)(struct lws_context *cx, const uint8_t *skid,
197  size_t skid_len, void *got_opaque);
205  uint32_t wake_latency_us;
209 
210 #if defined(LWS_WITH_SYS_STATE)
211 
220 LWS_EXTERN LWS_VISIBLE lws_state_manager_t *
221 lws_system_get_state_manager(struct lws_context *context);
222 
223 #endif
224 
225 /* wrappers handle NULL members or no ops struct set at all cleanly */
226 
227 #define LWSSYSGAUTH_HEX (1 << 0)
228 
237 LWS_EXTERN LWS_VISIBLE const lws_system_ops_t *
238 lws_system_get_ops(struct lws_context *context);
239 
240 #if defined(LWS_WITH_SYS_STATE)
241 
250 LWS_EXTERN LWS_VISIBLE struct lws_context *
251 lws_system_context_from_system_mgr(lws_state_manager_t *mgr);
252 
253 #endif
254 
286 LWS_EXTERN LWS_VISIBLE int
287 __lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t cb,
288  lws_system_states_t state, void *opaque,
289  struct lws_attach_item **get);
290 
291 
292 enum {
293  LWSDH_IPV4_SUBNET_MASK = 0,
294  LWSDH_IPV4_BROADCAST,
295  LWSDH_LEASE_SECS,
296  LWSDH_REBINDING_SECS,
297  LWSDH_RENEWAL_SECS,
298 
299  _LWSDH_NUMS_COUNT,
300 
301  LWSDH_SA46_IP = 0,
302  LWSDH_SA46_DNS_SRV_1,
303  LWSDH_SA46_DNS_SRV_2,
304  LWSDH_SA46_DNS_SRV_3,
305  LWSDH_SA46_DNS_SRV_4,
306  LWSDH_SA46_IPV4_ROUTER,
307  LWSDH_SA46_NTP_SERVER,
308  LWSDH_SA46_DHCP_SERVER,
309 
310  _LWSDH_SA46_COUNT,
311 };
312 
313 #if defined(LWS_WITH_NETWORK)
314 typedef struct lws_dhcpc_ifstate {
315  char ifname[16];
316  char domain[64];
317  uint8_t mac[6];
318  uint32_t nums[_LWSDH_NUMS_COUNT];
319  lws_sockaddr46 sa46[_LWSDH_SA46_COUNT];
320 } lws_dhcpc_ifstate_t;
321 
322 typedef int (*dhcpc_cb_t)(void *opaque, lws_dhcpc_ifstate_t *is);
323 
336 LWS_EXTERN LWS_VISIBLE int
337 lws_dhcpc_request(struct lws_context *c, const char *i, int af, dhcpc_cb_t cb,
338  void *opaque);
339 
348 LWS_EXTERN LWS_VISIBLE int
349 lws_dhcpc_remove(struct lws_context *context, const char *iface);
350 
360 LWS_EXTERN LWS_VISIBLE int
361 lws_dhcpc_status(struct lws_context *context, lws_sockaddr46 *sa46);
362 
372 LWS_EXTERN LWS_VISIBLE int
373 lws_system_cpd_start(struct lws_context *context);
374 
375 LWS_EXTERN LWS_VISIBLE void
376 lws_system_cpd_start_defer(struct lws_context *cx, lws_usec_t defer_us);
377 
378 
388 LWS_EXTERN LWS_VISIBLE void
389 lws_system_cpd_set(struct lws_context *context, lws_cpd_result_t result);
390 
391 
400 LWS_EXTERN LWS_VISIBLE lws_cpd_result_t
401 lws_system_cpd_state_get(struct lws_context *context);
402 
403 #endif
404 
Definition: lws-system.h:163
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)
Definition: lws-system.h:166
int(* jit_trust_query)(struct lws_context *cx, const uint8_t *skid, size_t skid_len, void *got_opaque)
Definition: lws-system.h:196
int(* captive_portal_detect_request)(struct lws_context *context)
Definition: lws-system.h:183
uint32_t wake_latency_us
Definition: lws-system.h:205
Definition: lws-adopt.h:87