libwebsockets
Lightweight C library for HTML5 websockets
lws-secure-streams-policy.h
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2019 - 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  * included from libwebsockets.h
25  */
26 
27 typedef int (*plugin_auth_status_cb)(struct lws_ss_handle *ss, int status);
28 
54 #if defined(LWS_WITH_SSPLUGINS)
55 typedef struct lws_ss_plugin {
56  struct lws_ss_plugin *next;
57  const char *name;
58  size_t alloc;
60  int (*create)(struct lws_ss_handle *ss, void *info,
61  plugin_auth_status_cb status);
67  int (*destroy)(struct lws_ss_handle *ss);
71  int (*munge)(struct lws_ss_handle *ss, char *path,
72  size_t path_len);
77 } lws_ss_plugin_t;
78 #endif
79 
80 /* the public, const metrics policy definition */
81 
82 typedef struct lws_metric_policy {
83  /* order of first two mandated by JSON policy parsing scope union */
84  const struct lws_metric_policy *next;
85  const char *name;
86 
87  const char *report;
88 
90  uint64_t us_schedule;
93  uint32_t us_decay_unit;
98 
99 typedef struct lws_ss_x509 {
100  struct lws_ss_x509 *next;
101  const char *vhost_name;
102  const uint8_t *ca_der;
103  size_t ca_der_len;
104  uint8_t keep:1;
105 } lws_ss_x509_t;
106 
107 enum {
108  LWSSSPOLF_OPPORTUNISTIC = (1 << 0),
110  LWSSSPOLF_NAILED_UP = (1 << 1),
112  LWSSSPOLF_URGENT_TX = (1 << 2),
114  LWSSSPOLF_URGENT_RX = (1 << 3),
116  LWSSSPOLF_TLS = (1 << 4),
118  LWSSSPOLF_LONG_POLL = (1 << 5),
120  LWSSSPOLF_AUTH_BEARER = (1 << 6),
122  LWSSSPOLF_HTTP_NO_CONTENT_LENGTH = (1 << 7),
124  LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM = (1 << 8),
126  LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR = (1 << 9),
128  LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE = (1 << 10),
130  LWSSSPOLF_HTTP_MULTIPART = (1 << 11),
136  LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED = (1 << 12),
138  LWSSSPOLF_LOCAL_SINK = (1 << 13),
140  LWSSSPOLF_WAKE_SUSPEND__VALIDITY = (1 << 14),
144  LWSSSPOLF_SERVER = (1 << 15),
146  LWSSSPOLF_ALLOW_REDIRECTS = (1 << 16),
148  LWSSSPOLF_HTTP_MULTIPART_IN = (1 << 17),
151  LWSSSPOLF_ATTR_LOW_LATENCY = (1 << 18),
153  LWSSSPOLF_ATTR_HIGH_THROUGHPUT = (1 << 19),
155  LWSSSPOLF_ATTR_HIGH_RELIABILITY = (1 << 20),
157  LWSSSPOLF_ATTR_LOW_COST = (1 << 21),
159  LWSSSPOLF_PERF = (1 << 22),
161  LWSSSPOLF_DIRECT_PROTO_STR = (1 << 23),
163  LWSSSPOLF_HTTP_CACHE_COOKIES = (1 << 24),
165  LWSSSPOLF_PRIORITIZE_READS = (1 << 25),
168 };
169 
170 typedef struct lws_ss_trust_store {
171  struct lws_ss_trust_store *next;
172  const char *name;
173 
174  const lws_ss_x509_t *ssx509[6];
175  int count;
177 
178 enum {
179  LWSSSP_H1,
180  LWSSSP_H2,
181  LWSSSP_WS,
182  LWSSSP_MQTT,
183  LWSSSP_RAW,
184 
185 
186  LWSSS_HBI_AUTH = 0,
187  LWSSS_HBI_DSN,
188  LWSSS_HBI_FWV,
189  LWSSS_HBI_TYPE,
190 
191  _LWSSS_HBI_COUNT /* always last */
192 };
193 
194 /*
195  * This does for both the static policy metadata entry, and the runtime metadata
196  * handling object.
197  */
198 
199 typedef struct lws_ss_metadata {
200  struct lws_ss_metadata *next;
201  const char *name;
202  void *value__may_own_heap;
203  size_t length;
204 
205  uint8_t value_length; /* only valid if set by policy */
206  uint8_t value_is_http_token; /* valid if set by policy */
207 #if defined(LWS_WITH_SS_DIRECT_PROTOCOL_STR)
208  uint8_t name_on_lws_heap:1; /* proxy metatadata does this */
209 #endif
210  uint8_t value_on_lws_heap:1; /* proxy + rx metadata does this */
211 #if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
212  uint8_t pending_onward:1;
213 #endif
215 
216 typedef struct lws_ss_http_respmap {
217  uint16_t resp; /* the http response code */
218  uint16_t state; /* low 16-bits of associated state */
220 
221 /*
222  * This is a mapping between an auth streamtype and a name and other information
223  * that can be independently instantiated. Other streamtypes can indicate they
224  * require this authentication on their connection.
225  */
226 
227 typedef struct lws_ss_auth {
228  struct lws_ss_auth *next;
229  const char *name;
230 
231  const char *type;
232  const char *streamtype;
233  uint8_t blob_index;
234 } lws_ss_auth_t;
235 
249 typedef struct lws_ss_policy {
250  struct lws_ss_policy *next;
251  const char *streamtype;
253  const char *endpoint;
254  const char *rideshare_streamtype;
257  const char *payload_fmt;
258  const char *socks5_proxy;
259  lws_ss_metadata_t *metadata; /* linked-list of metadata */
260  const lws_metric_policy_t *metrics; /* linked-list of metric policies */
261  const lws_ss_auth_t *auth; /* NULL or auth object we bind to */
262 
263  /* protocol-specific connection policy details */
264 
265  union {
266 
267 #if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2) || defined(LWS_ROLE_WS)
268 
269  /* details for http-related protocols... */
270 
271  struct {
272 
273  /* common to all http-related protocols */
274 
275  const char *method;
276  const char *url;
277 
278  const char *multipart_name;
279  const char *multipart_filename;
280  const char *multipart_content_type;
281 
282  const char *blob_header[_LWSSS_HBI_COUNT];
283  const char *auth_preamble;
284 
285  const lws_ss_http_respmap_t *respmap;
286 
287  union {
288 // struct { /* LWSSSP_H1 */
289 // } h1;
290 // struct { /* LWSSSP_H2 */
291 // } h2;
292  struct { /* LWSSSP_WS */
293  const char *subprotocol;
294  uint8_t binary;
295  /* false = TEXT, true = BINARY */
296  } ws;
297  } u;
298 
299  uint16_t resp_expect;
300  uint8_t count_respmap;
301  uint8_t fail_redirect:1;
302  } http;
303 
304 #endif
305 
306 #if defined(LWS_ROLE_MQTT)
307 
308  struct {
309  const char *topic; /* stream sends on this topic */
310  const char *subscribe; /* stream subscribes to this topic */
311 
312  const char *will_topic;
313  const char *will_message;
314 
315  const char *birth_topic;
316  const char *birth_message;
317 
318  uint16_t keep_alive;
319  uint8_t qos;
320  uint8_t clean_start;
321  uint8_t will_qos;
322  uint8_t will_retain;
323  uint8_t birth_qos;
324  uint8_t birth_retain;
325  uint8_t aws_iot;
326  uint8_t retain;
327 
328  } mqtt;
329 
330 #endif
331 
332  /* details for non-http related protocols... */
333  } u;
334 
335 #if defined(LWS_WITH_SSPLUGINS)
336  const
337  struct lws_ss_plugin *plugins[2];
338  const void *plugins_info[2];
339 #endif
340 
341 #if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
342  /* directly point to the metadata name, no need to expand */
343  const char *aws_region;
344  const char *aws_service;
345 #endif
346  /*
347  * We're either a client connection policy that wants a trust store,
348  * or we're a server policy that wants a mem cert and key... Hold
349  * these mutually-exclusive things in a union.
350  */
351 
352  union {
356  struct {
361  } server;
362  } trust;
363 
366  uint32_t proxy_buflen;
367  uint32_t proxy_buflen_rxflow_on_above;
368  uint32_t proxy_buflen_rxflow_off_below;
369 
370  uint32_t client_buflen;
371  uint32_t client_buflen_rxflow_on_above;
372  uint32_t client_buflen_rxflow_off_below;
373 
374 
375  uint32_t timeout_ms;
377  uint32_t flags;
379  uint16_t port;
381  uint8_t metadata_count;
382  uint8_t protocol;
383  uint8_t client_cert;
385  uint8_t priority; /* 0 = normal, 6 = max normal,
386  * 7 = network management */
388 
389 #if !defined(LWS_WITH_SECURE_STREAMS_STATIC_POLICY_ONLY)
390 
391 /*
392  * These only exist / have meaning if there's a dynamic JSON policy enabled
393  */
394 
395 LWS_VISIBLE LWS_EXTERN int
396 lws_ss_policy_parse_begin(struct lws_context *context, int overlay);
397 
398 LWS_VISIBLE LWS_EXTERN int
399 lws_ss_policy_parse_abandon(struct lws_context *context);
400 
401 LWS_VISIBLE LWS_EXTERN int
402 lws_ss_policy_parse(struct lws_context *context, const uint8_t *buf, size_t len);
403 
404 LWS_VISIBLE LWS_EXTERN int
405 lws_ss_policy_overlay(struct lws_context *context, const char *overlay);
406 
407 /*
408  * You almost certainly don't want these, they return the first policy or auth
409  * object in a linked-list of objects created by lws_ss_policy_parse above,
410  * they are exported to generate static policy with
411  */
412 LWS_VISIBLE LWS_EXTERN const lws_ss_policy_t *
413 lws_ss_policy_get(struct lws_context *context);
414 
415 LWS_VISIBLE LWS_EXTERN const lws_ss_auth_t *
416 lws_ss_auth_get(struct lws_context *context);
417 
418 #endif
Definition: lws-secure-streams-policy.h:82
uint32_t us_decay_unit
Definition: lws-secure-streams-policy.h:93
uint8_t min_contributors
Definition: lws-secure-streams-policy.h:95
uint64_t us_schedule
Definition: lws-secure-streams-policy.h:90
const char * report
Definition: lws-secure-streams-policy.h:87
Definition: lws-retry.h:25
Definition: lws-secure-streams-policy.h:227
Definition: lws-secure-streams-policy.h:216
Definition: lws-secure-streams-policy.h:199
Definition: lws-secure-streams-policy.h:249
uint32_t flags
Definition: lws-secure-streams-policy.h:377
uint8_t metadata_count
Definition: lws-secure-streams-policy.h:381
uint32_t timeout_ms
Definition: lws-secure-streams-policy.h:375
const lws_ss_x509_t * cert
Definition: lws-secure-streams-policy.h:357
const char * streamtype
Definition: lws-secure-streams-policy.h:251
const char * rideshare_streamtype
Definition: lws-secure-streams-policy.h:254
uint8_t client_cert
Definition: lws-secure-streams-policy.h:383
const char * endpoint
Definition: lws-secure-streams-policy.h:253
const lws_ss_trust_store_t * store
Definition: lws-secure-streams-policy.h:353
const lws_retry_bo_t * retry_bo
Definition: lws-secure-streams-policy.h:364
uint16_t port
Definition: lws-secure-streams-policy.h:379
uint8_t protocol
Definition: lws-secure-streams-policy.h:382
uint32_t client_buflen
Definition: lws-secure-streams-policy.h:370
const lws_ss_x509_t * key
Definition: lws-secure-streams-policy.h:359
uint32_t proxy_buflen
Definition: lws-secure-streams-policy.h:366
Definition: lws-secure-streams-policy.h:170
Definition: lws-secure-streams-policy.h:99
uint8_t keep
Definition: lws-secure-streams-policy.h:104
size_t ca_der_len
Definition: lws-secure-streams-policy.h:103
const uint8_t * ca_der
Definition: lws-secure-streams-policy.h:102
const char * vhost_name
Definition: lws-secure-streams-policy.h:101