libwebsockets
Lightweight C library for HTML5 websockets
lws-secure-streams-client.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2019 - 2020 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 is the headers for secure stream api variants that deal with clients in
25  * different threads or even different processes.
26  *
27  * lws_ss_ when client is directly using the event loop
28  * lws_sstc_ when client is in a different thread to the event loop
29  * lws_sspc_ when client is in a different process to the event loop
30  *
31  * The client api is almost the same except the slightly diffent names.
32  *
33  * This header is included as part of libwebsockets.h, for link against the
34  * libwebsockets library.
35  */
36 
37 /*
38  * lws_sspc_ apis... different process
39  */
40 
41 /*
42  * Helper translation so user code written to lws_ss_ can be built for
43  * lws_sspc_ in one step by #define LWS_SS_USE_SSPC before including
44  */
45 
46 
47 struct lws_sspc_handle;
48 
49 #if defined(LWS_SS_USE_SSPC)
50 #define lws_ss_handle lws_sspc_handle
51 #define lws_ss_create lws_sspc_create
52 #define lws_ss_destroy lws_sspc_destroy
53 #define lws_ss_request_tx lws_sspc_request_tx
54 #define lws_ss_request_tx_len lws_sspc_request_tx_len
55 #define lws_ss_client_connect lws_sspc_client_connect
56 #define lws_ss_get_sequencer lws_sspc_get_sequencer
57 #define lws_ss_proxy_create lws_sspc_proxy_create
58 #define lws_ss_get_context lws_sspc_get_context
59 #define lws_ss_rideshare lws_sspc_rideshare
60 #define lws_ss_set_metadata lws_sspc_set_metadata
61 #define lws_ss_get_metadata lws_sspc_get_metadata
62 #define lws_ss_add_peer_tx_credit lws_sspc_add_peer_tx_credit
63 #define lws_ss_get_est_peer_tx_credit lws_sspc_get_est_peer_tx_credit
64 #define lws_ss_start_timeout lws_sspc_start_timeout
65 #define lws_ss_cancel_timeout lws_sspc_cancel_timeout
66 #define lws_ss_to_user_object lws_sspc_to_user_object
67 #define lws_ss_change_handlers lws_sspc_change_handlers
68 #define lws_smd_ss_rx_forward lws_smd_sspc_rx_forward
69 #define lws_ss_server_ack lws_sspc_server_ack
70 #define lws_ss_tag lws_sspc_tag
71 #define _lws_fi_user_ss_fi _lws_fi_user_sspc_fi
72 #define lwsl_ss_get_cx lwsl_sspc_get_cx
73 
74 #undef lwsl_ss
75 #define lwsl_ss lwsl_sspc
76 
77 #undef lwsl_hexdump_ss
78 #define lwsl_hexdump_ss lwsl_hexdump_sspc
79 #endif
80 
81 LWS_VISIBLE LWS_EXTERN void
82 lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e);
83 
84 LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
85 lwsl_sspc_get_cx(struct lws_sspc_handle *ss);
86 
87 #define lwsl_sspc(_h, _fil, ...)
88  _lws_log_cx(lwsl_sspc_get_cx(_h), lws_log_prepend_sspc, _h,
89  _fil, __func__, __VA_ARGS__)
90 
91 #define lwsl_hexdump_sspc(_h, _fil, _buf, _len)
92  lwsl_hexdump_level_cx(lwsl_sspc_get_cx(_h),
93  lws_log_prepend_sspc,
94  _h, _fil, _buf, _len)
95 
96 /*
97  * lwsl_sspc
98  */
99 
100 #if (_LWS_ENABLED_LOGS & LLL_ERR)
101 #define lwsl_sspc_err(_w, ...) lwsl_sspc(_w, LLL_ERR, __VA_ARGS__)
102 #else
103 #define lwsl_sspc_err(_w, ...) do {} while(0)
104 #endif
105 
106 #if (_LWS_ENABLED_LOGS & LLL_WARN)
107 #define lwsl_sspc_warn(_w, ...) lwsl_sspc(_w, LLL_WARN, __VA_ARGS__)
108 #else
109 #define lwsl_sspc_warn(_w, ...) do {} while(0)
110 #endif
111 
112 #if (_LWS_ENABLED_LOGS & LLL_NOTICE)
113 #define lwsl_sspc_notice(_w, ...) lwsl_sspc(_w, LLL_NOTICE, __VA_ARGS__)
114 #else
115 #define lwsl_sspc_notice(_w, ...) do {} while(0)
116 #endif
117 
118 #if (_LWS_ENABLED_LOGS & LLL_INFO)
119 #define lwsl_sspc_info(_w, ...) lwsl_sspc(_w, LLL_INFO, __VA_ARGS__)
120 #else
121 #define lwsl_sspc_info(_w, ...) do {} while(0)
122 #endif
123 
124 #if (_LWS_ENABLED_LOGS & LLL_DEBUG)
125 #define lwsl_sspc_debug(_w, ...) lwsl_sspc(_w, LLL_DEBUG, __VA_ARGS__)
126 #else
127 #define lwsl_sspc_debug(_w, ...) do {} while(0)
128 #endif
129 
130 #if (_LWS_ENABLED_LOGS & LLL_PARSER)
131 #define lwsl_sspc_parser(_w, ...) lwsl_sspc(_w, LLL_PARSER, __VA_ARGS__)
132 #else
133 #define lwsl_sspc_parser(_w, ...) do {} while(0)
134 #endif
135 
136 #if (_LWS_ENABLED_LOGS & LLL_HEADER)
137 #define lwsl_sspc_header(_w, ...) lwsl_sspc(_w, LLL_HEADER, __VA_ARGS__)
138 #else
139 #define lwsl_sspc_header(_w, ...) do {} while(0)
140 #endif
141 
142 #if (_LWS_ENABLED_LOGS & LLL_EXT)
143 #define lwsl_sspc_ext(_w, ...) lwsl_sspc(_w, LLL_EXT, __VA_ARGS__)
144 #else
145 #define lwsl_sspc_ext(_w, ...) do {} while(0)
146 #endif
147 
148 #if (_LWS_ENABLED_LOGS & LLL_CLIENT)
149 #define lwsl_sspc_client(_w, ...) lwsl_sspc(_w, LLL_CLIENT, __VA_ARGS__)
150 #else
151 #define lwsl_sspc_client(_w, ...) do {} while(0)
152 #endif
153 
154 #if (_LWS_ENABLED_LOGS & LLL_LATENCY)
155 #define lwsl_sspc_latency(_w, ...) lwsl_sspc(_w, LLL_LATENCY, __VA_ARGS__)
156 #else
157 #define lwsl_sspc_latency(_w, ...) do {} while(0)
158 #endif
159 
160 #if (_LWS_ENABLED_LOGS & LLL_THREAD)
161 #define lwsl_sspc_thread(_w, ...) lwsl_sspc(_w, LLL_THREAD, __VA_ARGS__)
162 #else
163 #define lwsl_sspc_thread(_w, ...) do {} while(0)
164 #endif
165 
166 #if (_LWS_ENABLED_LOGS & LLL_USER)
167 #define lwsl_sspc_user(_w, ...) lwsl_sspc(_w, LLL_USER, __VA_ARGS__)
168 #else
169 #define lwsl_sspc_user(_w, ...) do {} while(0)
170 #endif
171 
172 #define lwsl_hexdump_sspc_err(_v, ...) lwsl_hexdump_sspc(_v, LLL_ERR, __VA_ARGS__)
173 #define lwsl_hexdump_sspc_warn(_v, ...) lwsl_hexdump_sspc(_v, LLL_WARN, __VA_ARGS__)
174 #define lwsl_hexdump_sspc_notice(_v, ...) lwsl_hexdump_sspc(_v, LLL_NOTICE, __VA_ARGS__)
175 #define lwsl_hexdump_sspc_info(_v, ...) lwsl_hexdump_sspc(_v, LLL_INFO, __VA_ARGS__)
176 #define lwsl_hexdump_sspc_debug(_v, ...) lwsl_hexdump_sspc(_v, LLL_DEBUG, __VA_ARGS__)
177 
178 /*
179  * How lws refers to your per-proxy-link private data... not allocated or freed
180  * by lws, nor used except to pass a pointer to it through to ops callbacks
181  * below. Should be set to your transport private instance object, it's set to
182  * the wsi for the wsi transport. Notice it is provided as a ** (ptr-to-ptr) in
183  * most apis.
184  */
185 
186 /*
187  * Stub context when using LWS_ONLY_SSPC
188  */
189 
194 };
195 
196 #if defined(STANDALONE)
197 #define lws_context lws_context_standalone
198 struct lws_context_standalone;
199 #endif
200 
201 LWS_VISIBLE LWS_EXTERN int
202 lws_sspc_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi,
203  void *opaque_user_data, struct lws_sspc_handle **ppss,
204  void *reserved, const char **ppayload_fmt);
205 
206 /**
207  * lws_sspc_destroy() - Destroy secure stream
208  *
209  * \param ppss: pointer to lws_ss_t pointer to be destroyed
210  *
211  * Destroys the lws_ss_t pointed to by *ppss, and sets *ppss to NULL.
212  */
213 LWS_VISIBLE LWS_EXTERN void
214 lws_sspc_destroy(struct lws_sspc_handle **ppss);
215 
216 /**
217  * lws_sspc_request_tx() - Schedule stream for tx
218  *
219  * \param pss: pointer to lws_ss_t representing stream that wants to transmit
220  *
221  * Schedules a write on the stream represented by \p pss. When it's possible to
222  * write on this stream, the *tx callback will occur with an empty buffer for
223  * the stream owner to fill in.
224  */
225 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
226 lws_sspc_request_tx(struct lws_sspc_handle *pss);
227 
228 /**
229  * lws_sspc_request_tx_len() - Schedule stream for tx with length hint
230  *
231  * \param h: pointer to handle representing stream that wants to transmit
232  * \param len: the length of the write in bytes
233  *
234  * Schedules a write on the stream represented by \p pss. When it's possible to
235  * write on this stream, the *tx callback will occur with an empty buffer for
236  * the stream owner to fill in.
237  *
238  * This api variant should be used when it's possible the payload will go out
239  * over h1 with x-web-form-urlencoded or similar Content-Type.
240  *
241  * The serialized, sspc type api actually serializes and forwards the length
242  * hint to its upstream proxy, where it's available for use to produce the
243  * internet-capable protocol framing.
244  */
245 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
246 lws_sspc_request_tx_len(struct lws_sspc_handle *h, unsigned long len);
247 
248 /**
249  * lws_sspc_client_connect() - Attempt the client connect
250  *
251  * \param h: secure streams handle
252  *
253  * Starts the connection process for the secure stream. Returns 0.
254  */
255 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
256 lws_sspc_client_connect(struct lws_sspc_handle *h);
257 
258 /**
259  * lws_sspc_proxy_create() - Start a unix domain socket proxy for Secure Streams
260  *
261  * \param context: lws_context
262  *
263  * Creates a vhost that listens on an abstract namespace unix domain socket at
264  * address "proxy.ss.lws". Client connections to this proxy to Secure Streams
265  */
266 LWS_VISIBLE LWS_EXTERN int
267 lws_sspc_proxy_create(struct lws_context *context);
268 
269 /**
270  * lws_ss_get_context() - convenience helper to recover the lws context
271  *
272  * \h: secure streams handle
273  *
274  * Returns the lws context. Dispenses with the need to pass a copy of it into
275  * your secure streams handler.
276  */
277 
278 LWS_VISIBLE LWS_EXTERN struct lws_context *
279 lws_sspc_get_context(struct lws_sspc_handle *h);
280 
281 #if defined(LWS_WITH_NETWORK)
282 extern const struct lws_protocols lws_sspc_protocols[2];
283 #endif
284 
285 LWS_VISIBLE LWS_EXTERN const char *
286 lws_sspc_rideshare(struct lws_sspc_handle *h);
287 
288 
289 /**
290  * lws_sspc_set_metadata() - allow user to bind external data to defined ss metadata
291  *
292  * \h: secure streams handle
293  * \name: metadata name from the policy
294  * \value: pointer to user-managed data to bind to name
295  * \len: length of the user-managed data in value
296  *
297  * Binds user-managed data to the named metadata item from the ss policy.
298  * If present, the metadata item is handled in a protocol-specific way using
299  * the associated policy information. For example, in the policy
300  *
301  * "\"metadata\":" "["
302  * "{\"uptag\":" "\"X-Upload-Tag:\"},"
303  * "{\"ctype\":" "\"Content-Type:\"},"
304  * "{\"xctype\":" "\"X-Content-Type:\"}"
305  * "],"
306  *
307  * when the policy is using h1 is interpreted to add h1 headers of the given
308  * name with the value of the metadata on the left.
309  *
310  * Return 0 if OK, or nonzero if failed.
311  */
312 LWS_VISIBLE LWS_EXTERN int
313 lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name,
314  const void *value, size_t len);
315 
316 LWS_VISIBLE LWS_EXTERN int
317 lws_sspc_get_metadata(struct lws_sspc_handle *h, const char *name,
318  const void **value, size_t *len);
319 
320 LWS_VISIBLE LWS_EXTERN int
321 lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add);
322 
323 LWS_VISIBLE LWS_EXTERN int
324 lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h);
325 
326 LWS_VISIBLE LWS_EXTERN void
327 lws_sspc_start_timeout(struct lws_sspc_handle *h, unsigned int timeout_ms);
328 
329 LWS_VISIBLE LWS_EXTERN void
330 lws_sspc_cancel_timeout(struct lws_sspc_handle *h);
331 
332 LWS_VISIBLE LWS_EXTERN void *
333 lws_sspc_to_user_object(struct lws_sspc_handle *h);
334 
335 LWS_VISIBLE LWS_EXTERN void
336 lws_sspc_change_handlers(struct lws_sspc_handle *h,
337  lws_sscb_rx rx,lws_sscb_tx tx, lws_sscb_state state);
338 
339 LWS_VISIBLE LWS_EXTERN void
340 lws_sspc_server_ack(struct lws_sspc_handle *h, int nack);
341 
342 
343 /*
344  * Helpers offered by lws to handle transport SSPC-side proxy link events
345  */
346 
347 /**
348  * lws_sspc_tag() - get the sspc log tag
349  *
350  * \param h: the sspc handle
351  *
352  * Returns the sspc log tag, to assist in logging traceability
353  */
354 LWS_VISIBLE LWS_EXTERN const char *
355 lws_sspc_tag(struct lws_sspc_handle *h);
356 
357 
358 #if defined(STANDALONE)
359 #undef lws_context
360 #endif