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 #if defined(LWS_SS_USE_SSPC) 44 #define lws_ss_handle lws_sspc_handle 45 #define lws_ss_create lws_sspc_create 46 #define lws_ss_destroy lws_sspc_destroy 47 #define lws_ss_request_tx lws_sspc_request_tx 48 #define lws_ss_client_connect lws_sspc_client_connect 49 #define lws_ss_get_sequencer lws_sspc_get_sequencer 50 #define lws_ss_proxy_create lws_sspc_proxy_create 51 #define lws_ss_get_context lws_sspc_get_context 52 #define lws_ss_rideshare lws_sspc_rideshare 53 #define lws_ss_set_metadata lws_sspc_set_metadata 54 #define lws_ss_add_peer_tx_credit lws_sspc_add_peer_tx_credit 55 #define lws_ss_get_est_peer_tx_credit lws_sspc_get_est_peer_tx_credit 56 #endif 57 58 59 struct lws_sspc_handle; 60 61 LWS_VISIBLE LWS_EXTERN int 62 lws_sspc_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi, 63 void *opaque_user_data, struct lws_sspc_handle **ppss, 64 struct lws_sequencer *seq_owner, const char **ppayload_fmt); 65 66 /** 67 * lws_sspc_destroy() - Destroy secure stream 68 * 69 * \param ppss: pointer to lws_ss_t pointer to be destroyed 70 * 71 * Destroys the lws_ss_t pointed to by *ppss, and sets *ppss to NULL. 72 */ 73 LWS_VISIBLE LWS_EXTERN void 74 lws_sspc_destroy(struct lws_sspc_handle **ppss); 75 76 /** 77 * lws_sspc_request_tx() - Schedule stream for tx 78 * 79 * \param pss: pointer to lws_ss_t representing stream that wants to transmit 80 * 81 * Schedules a write on the stream represented by \p pss. When it's possible to 82 * write on this stream, the *tx callback will occur with an empty buffer for 83 * the stream owner to fill in. 84 */ 85 LWS_VISIBLE LWS_EXTERN void 86 lws_sspc_request_tx(struct lws_sspc_handle *pss); 87 88 /** 89 * lws_sspc_client_connect() - Attempt the client connect 90 * 91 * \param h: secure streams handle 92 * 93 * Starts the connection process for the secure stream. Returns 0 if OK or 94 * nonzero if we have already failed. 95 */ 96 LWS_VISIBLE LWS_EXTERN int 97 lws_sspc_client_connect(struct lws_sspc_handle *h); 98 99 /** 100 * lws_sspc_get_sequencer() - Return parent sequencer pointer if any 101 * 102 * \param h: secure streams handle 103 * 104 * Returns NULL if the secure stream is not associated with a sequencer. 105 * Otherwise returns a pointer to the owning sequencer. You can use this to 106 * identify which sequencer to direct messages to, from the secure stream 107 * callback. 108 */ 109 LWS_VISIBLE LWS_EXTERN struct lws_sequencer * 110 lws_sspc_get_sequencer(struct lws_sspc_handle *h); 111 112 /** 113 * lws_sspc_proxy_create() - Start a unix domain socket proxy for Secure Streams 114 * 115 * \param context: lws_context 116 * 117 * Creates a vhost that listens on an abstract namespace unix domain socket at 118 * address "proxy.ss.lws". Client connections to this proxy to Secure Streams 119 */ 120 LWS_VISIBLE LWS_EXTERN int 121 lws_sspc_proxy_create(struct lws_context *context); 122 123 /** 124 * lws_ss_get_context() - convenience helper to recover the lws context 125 * 126 * \h: secure streams handle 127 * 128 * Returns the lws context. Dispenses with the need to pass a copy of it into 129 * your secure streams handler. 130 */ 131 132 LWS_VISIBLE LWS_EXTERN struct lws_context * 133 lws_sspc_get_context(struct lws_sspc_handle *h); 134 135 LWS_VISIBLE LWS_EXTERN const struct lws_protocols lws_sspc_protocols[]; 136 137 LWS_VISIBLE LWS_EXTERN const char * 138 lws_sspc_rideshare(struct lws_sspc_handle *h); 139 140 141 /** 142 * lws_sspc_set_metadata() - allow user to bind external data to defined ss metadata 143 * 144 * \h: secure streams handle 145 * \name: metadata name from the policy 146 * \value: pointer to user-managed data to bind to name 147 * \len: length of the user-managed data in value 148 * 149 * Binds user-managed data to the named metadata item from the ss policy. 150 * If present, the metadata item is handled in a protocol-specific way using 151 * the associated policy information. For example, in the policy 152 * 153 * "\"metadata\":" "[" 154 * "{\"uptag\":" "\"X-Upload-Tag:\"}," 155 * "{\"ctype\":" "\"Content-Type:\"}," 156 * "{\"xctype\":" "\"X-Content-Type:\"}" 157 * "]," 158 * 159 * when the policy is using h1 is interpreted to add h1 headers of the given 160 * name with the value of the metadata on the left. 161 * 162 * Return 0 if OK. 163 */ 164 LWS_VISIBLE LWS_EXTERN int 165 lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name, 166 void *value, size_t len); 167 168 LWS_VISIBLE LWS_EXTERN int 169 lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add); 170 171 LWS_VISIBLE LWS_EXTERN int 172 lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h); 173