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 43 struct 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 69 LWS_VISIBLE LWS_EXTERN void 70 lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e); 71 72 LWS_VISIBLE LWS_EXTERN struct lws_log_cx * 73 lwsl_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 174 LWS_VISIBLE LWS_EXTERN int 175 lws_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 */ 186 LWS_VISIBLE LWS_EXTERN void 187 lws_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 */ 198 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t 199 lws_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 */ 218 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t 219 lws_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 */ 228 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t 229 lws_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 */ 241 LWS_VISIBLE LWS_EXTERN struct lws_sequencer * 242 lws_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 */ 252 LWS_VISIBLE LWS_EXTERN int 253 lws_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 264 LWS_VISIBLE LWS_EXTERN struct lws_context * 265 lws_sspc_get_context(struct lws_sspc_handle *h); 266 267 LWS_VISIBLE extern const struct lws_protocols lws_sspc_protocols[2]; 268 269 LWS_VISIBLE LWS_EXTERN const char * 270 lws_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 */ 296 LWS_VISIBLE LWS_EXTERN int 297 lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name, 298 const void *value, size_t len); 299 300 LWS_VISIBLE LWS_EXTERN int 301 lws_sspc_get_metadata(struct lws_sspc_handle *h, const char *name, 302 const void **value, size_t *len); 303 304 LWS_VISIBLE LWS_EXTERN int 305 lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add); 306 307 LWS_VISIBLE LWS_EXTERN int 308 lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h); 309 310 LWS_VISIBLE LWS_EXTERN void 311 lws_sspc_start_timeout(struct lws_sspc_handle *h, unsigned int timeout_ms); 312 313 LWS_VISIBLE LWS_EXTERN void 314 lws_sspc_cancel_timeout(struct lws_sspc_handle *h); 315 316 LWS_VISIBLE LWS_EXTERN void * 317 lws_sspc_to_user_object(struct lws_sspc_handle *h); 318 319 LWS_VISIBLE LWS_EXTERN void 320 lws_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 330 const char * 331 lws_sspc_tag(struct lws_sspc_handle *h); 332