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