lws-secure-streams-client.h (11513B)
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);