1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2021 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
25/*! \defgroup client Client related functions
26 * ##Client releated functions
27 * \ingroup lwsapi
28 *
29 * */
30///@{
31
32/** enum lws_client_connect_ssl_connection_flags - flags that may be used
33 * with struct lws_client_connect_info ssl_connection member to control if
34 * and how SSL checks apply to the client connection being created
35 */
36
37enum lws_client_connect_ssl_connection_flags {
38 LCCSCF_USE_SSL = (1 << 0),
39 LCCSCF_ALLOW_SELFSIGNED = (1 << 1),
40 LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK = (1 << 2),
41 LCCSCF_ALLOW_EXPIRED = (1 << 3),
42 LCCSCF_ALLOW_INSECURE = (1 << 4),
43 LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM = (1 << 5),
44 LCCSCF_H2_QUIRK_OVERFLOWS_TXCR = (1 << 6),
45 LCCSCF_H2_AUTH_BEARER = (1 << 7),
46 LCCSCF_H2_HEXIFY_AUTH_TOKEN = (1 << 8),
47 LCCSCF_H2_MANUAL_RXFLOW = (1 << 9),
48 LCCSCF_HTTP_MULTIPART_MIME = (1 << 10),
49 LCCSCF_HTTP_X_WWW_FORM_URLENCODED = (1 << 11),
50 LCCSCF_HTTP_NO_FOLLOW_REDIRECT = (1 << 12),
51 LCCSCF_HTTP_NO_CACHE_CONTROL = (1 << 13),
52
53 LCCSCF_ALLOW_REUSE_ADDR = (1 << 14),
54 /**< allow reuse local addresses in a bind call
55 * When the listening socket is bound to INADDR_ANY with a specific port
56 * then it is not possible to bind to this port for any local address
57 */
58
59 LCCSCF_IPV6_PREFER_PUBLIC_ADDR = (1 << 15),
60 /**< RFC5014 - For IPv6 systems with SLAAC config, allow for preference
61 * to bind a socket to public address vs temporary private address
62 */
63
64 LCCSCF_PIPELINE = (1 << 16),
65 /**< Serialize / pipeline multiple client connections
66 * on a single connection where possible.
67 *
68 * HTTP/1.0: possible if Keep-Alive: yes sent by server
69 * HTTP/1.1: always possible... uses pipelining
70 * HTTP/2: always possible... uses parallel streams
71 */
72 LCCSCF_MUXABLE_STREAM = (1 << 17),
73 LCCSCF_H2_PRIOR_KNOWLEDGE = (1 << 18),
74 LCCSCF_WAKE_SUSPEND__VALIDITY = (1 << 19),
75 /* our validity checks are important enough to wake from suspend */
76 LCCSCF_PRIORITIZE_READS = (1 << 20),
77 /**<
78 * Normally lws balances reads and writes on all connections, so both
79 * are possible even on busy connections, and we go around the event
80 * loop more often to facilitate that, even if there is pending data.
81 *
82 * This flag indicates that you want to handle any pending reads on this
83 * connection without yielding the service loop for anything else. This
84 * means you may block other connection processing in favour of incoming
85 * data processing on this one if it receives back to back incoming rx.
86 */
87 LCCSCF_SECSTREAM_CLIENT = (1 << 21),
88 /**< used to mark client wsi as bound to secure stream */
89 LCCSCF_SECSTREAM_PROXY_LINK = (1 << 22),
90 /**< client is a link between SS client and SS proxy */
91 LCCSCF_SECSTREAM_PROXY_ONWARD = (1 << 23),
92 /**< client the SS proxy's onward connection */
93
94 LCCSCF_IP_LOW_LATENCY = (1 << 24),
95 /**< set the "low delay" bit on the IP packets of this connection */
96 LCCSCF_IP_HIGH_THROUGHPUT = (1 << 25),
97 /**< set the "high throughput" bit on the IP packets of this
98 * connection */
99 LCCSCF_IP_HIGH_RELIABILITY = (1 << 26),
100 /**< set the "high reliability" bit on the IP packets of this
101 * connection */
102 LCCSCF_IP_LOW_COST = (1 << 27),
103 /**< set the "minimize monetary cost" bit on the IP packets of this
104 * connection */
105 LCCSCF_CONMON = (1 << 28),
106 /**< If LWS_WITH_CONMON enabled for build, keeps a copy of the
107 * getaddrinfo results so they can be queried subsequently */
108 LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS = (1 << 29),
109 /**< By default lws rejects https redirecting to http. Set this
110 * flag on the client connection to allow it. */
111 LCCSCF_CACHE_COOKIES = (1 << 30),
112 /**< If built with -DLWS_WITH_CACHE_NSCOOKIEJAR, store and reapply
113 * http cookies in a Netscape Cookie Jar on this connection */
114};
115
116/** struct lws_client_connect_info - parameters to connect with when using
117 * lws_client_connect_via_info() */
118
119struct lws_client_connect_info {
120 struct lws_context *context;
121 /**< lws context to create connection in */
122 const char *address;
123 /**< remote address to connect to */
124 int port;
125 /**< remote port to connect to */
126 int ssl_connection;
127 /**< 0, or a combination of LCCSCF_ flags */
128 const char *path;
129 /**< URI path. Prefix with + for a UNIX socket. (+@ for
130 * a Linux abstract-namespace socket) */
131 const char *host;
132 /**< content of host header */
133 const char *origin;
134 /**< content of origin header */
135 const char *protocol;
136 /**< list of ws protocols we could accept */
137 int ietf_version_or_minus_one;
138 /**< deprecated: currently leave at 0 or -1 */
139 void *userdata;
140 /**< if non-NULL, use this as wsi user_data instead of malloc it */
141 const void *client_exts;
142 /**< UNUSED... provide in info.extensions at context creation time */
143 const char *method;
144 /**< if non-NULL, do this http method instead of ws[s] upgrade.
145 * use "GET" to be a simple http client connection. "RAW" gets
146 * you a connected socket that lws itself will leave alone once
147 * connected. */
148 struct lws *parent_wsi;
149 /**< if another wsi is responsible for this connection, give it here.
150 * this is used to make sure if the parent closes so do any
151 * child connections first. */
152 const char *uri_replace_from;
153 /**< if non-NULL, when this string is found in URIs in
154 * text/html content-encoding, it's replaced with uri_replace_to */
155 const char *uri_replace_to;
156 /**< see uri_replace_from */
157 struct lws_vhost *vhost;
158 /**< vhost to bind to (used to determine related SSL_CTX) */
159 struct lws **pwsi;
160 /**< if not NULL, store the new wsi here early in the connection
161 * process. Although we return the new wsi, the call to create the
162 * client connection does progress the connection somewhat and may
163 * meet an error that will result in the connection being scrubbed and
164 * NULL returned. While the wsi exists though, he may process a
165 * callback like CLIENT_CONNECTION_ERROR with his wsi: this gives the
166 * user callback a way to identify which wsi it is that faced the error
167 * even before the new wsi is returned and even if ultimately no wsi
168 * is returned.
169 */
170 const char *iface;
171 /**< NULL to allow routing on any interface, or interface name or IP
172 * to bind the socket to */
173 int local_port;
174 /**< 0 to pick an ephemeral port, or a specific local port
175 * to bind the socket to */
176 const char *local_protocol_name;
177 /**< NULL: .protocol is used both to select the local protocol handler
178 * to bind to and as the list of remote ws protocols we could
179 * accept.
180 * non-NULL: this protocol name is used to bind the connection to
181 * the local protocol handler. .protocol is used for the
182 * list of remote ws protocols we could accept */
183 const char *alpn;
184 /**< NULL: allow lws default ALPN list, from vhost if present or from
185 * list of roles built into lws
186 * non-NULL: require one from provided comma-separated list of alpn
187 * tokens
188 */
189
190 void *opaque_user_data;
191 /**< This data has no meaning to lws but is applied to the client wsi
192 * and can be retrieved by user code with lws_get_opaque_user_data().
193 * It's also provided with sequencer messages if the wsi is bound to
194 * an lws_seq_t.
195 */
196
197 const lws_retry_bo_t *retry_and_idle_policy;
198 /**< optional retry and idle policy to apply to this connection.
199 * Currently only the idle parts are applied to the connection.
200 */
201
202 int manual_initial_tx_credit;
203 /**< if LCCSCF_H2_MANUAL_REFLOW is set, this becomes the initial tx
204 * credit for the stream.
205 */
206
207 uint8_t sys_tls_client_cert;
208 /**< 0 means no client cert. 1+ means apply lws_system client cert 0+
209 * to the client connection.
210 */
211
212 uint8_t priority;
213 /**< 0 means normal priority... otherwise sets the IP priority on
214 * packets coming from this connection, from 1 - 7. Setting 7
215 * (network management priority) requires CAP_NET_ADMIN capability but
216 * the others can be set by anyone.
217 */
218
219#if defined(LWS_ROLE_MQTT)
220 const lws_mqtt_client_connect_param_t *mqtt_cp;
221#else
222 void *mqtt_cp;
223#endif
224
225#if defined(LWS_WITH_SYS_FAULT_INJECTION)
226 lws_fi_ctx_t fic;
227 /**< Attach external Fault Injection context to the client wsi,
228 * hierarchy is wsi -> vhost -> context */
229#endif
230 /* for convenience, available when FI disabled in build */
231 const char *fi_wsi_name;
232 /**< specific Fault Injection namespace name for wsi created for this
233 * connection, allows targeting by "wsi=XXX/..." if you give XXX here.
234 */
235
236 uint16_t keep_warm_secs;
237 /**< 0 means 5s. If the client connection to the endpoint becomes idle,
238 * defer closing it for this many seconds in case another outgoing
239 * connection to the same endpoint turns up.
240 */
241
242 lws_log_cx_t *log_cx;
243 /**< NULL to use lws_context log context, else a pointer to a log
244 * context template to take a copy of for this wsi. Used to isolate
245 * wsi-specific logs into their own stream or file.
246 */
247 const char *auth_username;
248 const char *auth_password;
249
250#if defined(LWS_ROLE_WS)
251 uint8_t allow_reserved_bits;
252 /**< non-zero to allow reserved bits. You can get it by lws_get_reserved_bits().
253 * Note: default zero means close the websocket connection for non-zero rsv.
254 */
255
256 uint8_t allow_unknown_opcode;
257 /**< non-zero to allow unknown opcode. You can get it by `lws_get_opcode`.
258 * None: default zero means close the websocket connection for unknown opcode.
259 */
260#endif
261
262 /* Add new things just above here ---^
263 * This is part of the ABI, don't needlessly break compatibility
264 *
265 * The below is to ensure later library versions with new
266 * members added above will see 0 (default) even if the app
267 * was not built against the newer headers.
268 */
269
270 void *_unused[4]; /**< dummy */
271};
272
273/**
274 * lws_client_connect_via_info() - Connect to another websocket server
275 * \param ccinfo: pointer to lws_client_connect_info struct
276 *
277 * This function creates a connection to a remote server using the
278 * information provided in ccinfo.
279 */
280LWS_VISIBLE LWS_EXTERN struct lws *
281lws_client_connect_via_info(const struct lws_client_connect_info *ccinfo);
282
283/**
284 * lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost
285 *
286 * \param info: client ssl related info
287 * \param vhost: which vhost to initialize client ssl operations on
288 *
289 * You only need to call this if you plan on using SSL client connections on
290 * the vhost. For non-SSL client connections, it's not necessary to call this.
291 *
292 * The following members of info are used during the call
293 *
294 * - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
295 * otherwise the call does nothing
296 * - provided_client_ssl_ctx must be NULL to get a generated client
297 * ssl context, otherwise you can pass a prepared one in by setting it
298 * - ssl_cipher_list may be NULL or set to the client valid cipher list
299 * - ssl_ca_filepath may be NULL or client cert filepath
300 * - ssl_cert_filepath may be NULL or client cert filepath
301 * - ssl_private_key_filepath may be NULL or client cert private key
302 *
303 * You must create your vhost explicitly if you want to use this, so you have
304 * a pointer to the vhost. Create the context first with the option flag
305 * LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with
306 * the same info struct.
307 */
308LWS_VISIBLE LWS_EXTERN int
309lws_init_vhost_client_ssl(const struct lws_context_creation_info *info,
310 struct lws_vhost *vhost);
311/**
312 * lws_http_client_read() - consume waiting received http client data
313 *
314 * \param wsi: client connection
315 * \param buf: pointer to buffer pointer - fill with pointer to your buffer
316 * \param len: pointer to chunk length - fill with max length of buffer
317 *
318 * This is called when the user code is notified client http data has arrived.
319 * The user code may choose to delay calling it to consume the data, for example
320 * waiting until an onward connection is writeable.
321 *
322 * For non-chunked connections, up to len bytes of buf are filled with the
323 * received content. len is set to the actual amount filled before return.
324 *
325 * For chunked connections, the linear buffer content contains the chunking
326 * headers and it cannot be passed in one lump. Instead, this function will
327 * call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the
328 * chunk start and len set to the chunk length. There will be as many calls
329 * as there are chunks or partial chunks in the buffer.
330 */
331LWS_VISIBLE LWS_EXTERN int
332lws_http_client_read(struct lws *wsi, char **buf, int *len);
333
334/**
335 * lws_http_client_http_response() - get last HTTP response code
336 *
337 * \param wsi: client connection
338 *
339 * Returns the last server response code, eg, 200 for client http connections.
340 * If there is no valid response, it will return 0.
341 *
342 * You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP
343 * callback, because after that the memory reserved for storing the related
344 * headers is freed and this value is lost.
345 */
346LWS_VISIBLE LWS_EXTERN unsigned int
347lws_http_client_http_response(struct lws *wsi);
348
349/**
350 * lws_tls_client_vhost_extra_cert_mem() - add more certs to vh client tls ctx
351 *
352 * \param vh: the vhost to give more client certs to
353 * \param der: pointer to der format additional cert
354 * \param der_len: size in bytes of der
355 *
356 * After the vhost is created with one cert for client verification, you
357 * can add additional, eg, intermediate, certs to the client tls context
358 * of the vhost, for use with validating the incoming server cert(s).
359 */
360LWS_VISIBLE LWS_EXTERN int
361lws_tls_client_vhost_extra_cert_mem(struct lws_vhost *vh,
362 const uint8_t *der, size_t der_len);
363
364/**
365 * lws_client_http_body_pending() - control if client connection needs to send body
366 *
367 * \param wsi: client connection
368 * \param something_left_to_send: nonzero if need to send more body, 0 (default)
369 * if nothing more to send
370 *
371 * If you will send payload data with your HTTP client connection, eg, for POST,
372 * when you set the related http headers in
373 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call
374 * this API with something_left_to_send nonzero, and call
375 * lws_callback_on_writable(wsi);
376 *
377 * After sending the headers, lws will call your callback with
378 * LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the
379 * next part of the http body payload, calling lws_callback_on_writable(wsi);
380 * if there is more to come, or lws_client_http_body_pending(wsi, 0); to
381 * let lws know the last part is sent and the connection can move on.
382 */
383LWS_VISIBLE LWS_EXTERN void
384lws_client_http_body_pending(struct lws *wsi, int something_left_to_send);
385
386/**
387 * lws_client_http_multipart() - issue appropriate multipart header or trailer
388 *
389 * \param wsi: client connection
390 * \param name: multipart header name field, or NULL if end of multipart
391 * \param filename: multipart header filename field, or NULL if none
392 * \param content_type: multipart header content-type part, or NULL if none
393 * \param p: pointer to position in buffer
394 * \param end: end of buffer
395 *
396 * This issues a multipart mime boundary, or terminator if name = NULL.
397 *
398 * Returns 0 if OK or nonzero if couldn't fit in buffer
399 */
400LWS_VISIBLE LWS_EXTERN int
401lws_client_http_multipart(struct lws *wsi, const char *name,
402 const char *filename, const char *content_type,
403 char **p, char *end);
404
405/**
406 * lws_http_basic_auth_gen() - helper to encode client basic auth string
407 *
408 * \param user: user name
409 * \param pw: password
410 * \param buf: where to store base64 result
411 * \param len: max usable size of buf
412 *
413 * Encodes a username and password in Basic Auth format for use with the
414 * Authorization header. On return, buf is filled with something like
415 * "Basic QWxhZGRpbjpPcGVuU2VzYW1l".
416 */
417LWS_VISIBLE LWS_EXTERN int
418lws_http_basic_auth_gen(const char *user, const char *pw, char *buf, size_t len);
419
420/**
421 * lws_http_basic_auth_gen2() - helper to encode client basic auth string
422 *
423 * \param user: user name
424 * \param pw: password
425 * \param pwd_len: count of bytes in password
426 * \param buf: where to store base64 result
427 * \param len: max usable size of buf
428 *
429 * Encodes a username and password in Basic Auth format for use with the
430 * Authorization header. On return, buf is filled with something like
431 * "Basic QWxhZGRpbjpPcGVuU2VzYW1l".
432 *
433 * This differs from lws_http_baic_auth_gen() in that NUL bytes can
434 * appear in the password due to an explicit password length argument.
435 */
436LWS_VISIBLE LWS_EXTERN int
437lws_http_basic_auth_gen2(const char *user, const void *pw, size_t pwd_len,
438 char *buf, size_t len);
439
440/**
441 * lws_tls_session_is_reused() - returns nonzero if tls session was cached
442 *
443 * \param wsi: the wsi
444 *
445 * Returns zero if the tls session is fresh, else nonzero if the tls session was
446 * taken from the cache. If lws is built with LWS_WITH_TLS_SESSIONS and the vhost
447 * was created with the option LWS_SERVER_OPTION_ENABLE_TLS_SESSION_CACHE, then
448 * on full tls session establishment of a client connection, the session is added
449 * to the tls cache.
450 *
451 * This lets you find out if your session was new (0) or from the cache (nonzero),
452 * it'a mainly useful for stats and testing.
453 */
454LWS_VISIBLE LWS_EXTERN int
455lws_tls_session_is_reused(struct lws *wsi);
456
457///@}
458