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
47struct 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
81LWS_VISIBLE LWS_EXTERN void
82lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e);
83
84LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
85lwsl_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
190struct lws_context_standalone {
191 lws_txp_path_client_t txp_cpath;
192 lws_dll2_owner_t ss_client_owner;
193 uint32_t ssidx;
194};
195
196#if defined(STANDALONE)
197#define lws_context lws_context_standalone
198struct lws_context_standalone;
199#endif
200
201LWS_VISIBLE LWS_EXTERN int
202lws_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 */
213LWS_VISIBLE LWS_EXTERN void
214lws_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 */
225LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
226lws_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 */
245LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
246lws_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 */
255LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
256lws_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 */
266LWS_VISIBLE LWS_EXTERN int
267lws_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
278LWS_VISIBLE LWS_EXTERN struct lws_context *
279lws_sspc_get_context(struct lws_sspc_handle *h);
280
281#if defined(LWS_WITH_NETWORK)
282extern const struct lws_protocols lws_sspc_protocols[2];
283#endif
284
285LWS_VISIBLE LWS_EXTERN const char *
286lws_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 */
312LWS_VISIBLE LWS_EXTERN int
313lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name,
314 const void *value, size_t len);
315
316LWS_VISIBLE LWS_EXTERN int
317lws_sspc_get_metadata(struct lws_sspc_handle *h, const char *name,
318 const void **value, size_t *len);
319
320LWS_VISIBLE LWS_EXTERN int
321lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add);
322
323LWS_VISIBLE LWS_EXTERN int
324lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h);
325
326LWS_VISIBLE LWS_EXTERN void
327lws_sspc_start_timeout(struct lws_sspc_handle *h, unsigned int timeout_ms);
328
329LWS_VISIBLE LWS_EXTERN void
330lws_sspc_cancel_timeout(struct lws_sspc_handle *h);
331
332LWS_VISIBLE LWS_EXTERN void *
333lws_sspc_to_user_object(struct lws_sspc_handle *h);
334
335LWS_VISIBLE LWS_EXTERN void
336lws_sspc_change_handlers(struct lws_sspc_handle *h,
337 lws_sscb_rx rx,lws_sscb_tx tx, lws_sscb_state state);
338
339LWS_VISIBLE LWS_EXTERN void
340lws_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 */
354LWS_VISIBLE LWS_EXTERN const char *
355lws_sspc_tag(struct lws_sspc_handle *h);
356
357
358#if defined(STANDALONE)
359#undef lws_context
360#endif
361
362
363