lsquic.h revision 71eb4000
1/* Copyright (c) 2017 - 2020 LiteSpeed Technologies Inc. See LICENSE. */ 2#ifndef __LSQUIC_H__ 3#define __LSQUIC_H__ 4 5/** 6 * @file 7 * public API for using liblsquic is defined in this file. 8 * 9 */ 10 11#include <stdarg.h> 12#include <lsquic_types.h> 13#ifndef WIN32 14#include <sys/uio.h> 15#include <time.h> 16#else 17#include <vc_compat.h> 18#endif 19 20struct sockaddr; 21 22#ifdef __cplusplus 23extern "C" { 24#endif 25 26#define LSQUIC_MAJOR_VERSION 2 27#define LSQUIC_MINOR_VERSION 26 28#define LSQUIC_PATCH_VERSION 1 29 30/** 31 * Engine flags: 32 */ 33 34/** Server mode */ 35#define LSENG_SERVER (1 << 0) 36 37/** Use HTTP behavior */ 38#define LSENG_HTTP (1 << 1) 39 40#define LSENG_HTTP_SERVER (LSENG_SERVER|LSENG_HTTP) 41 42/** 43 * This is a list of QUIC versions that we know of. List of supported 44 * versions is in LSQUIC_SUPPORTED_VERSIONS. 45 */ 46enum lsquic_version 47{ 48 /** 49 * Q043. Support for processing PRIORITY frames. Since this library 50 * has supported PRIORITY frames from the beginning, this version is 51 * exactly the same as LSQVER_042. 52 */ 53 LSQVER_043, 54 55 /** 56 * Q046. Use IETF Draft-17 compatible packet headers. 57 */ 58 LSQVER_046, 59 60 /** 61 * Q050. Variable-length QUIC server connection IDs. Use CRYPTO frames 62 * for handshake. IETF header format matching invariants-06. Packet 63 * number encryption. Initial packets are obfuscated. 64 */ 65 LSQVER_050, 66 67#if LSQUIC_USE_Q098 68 /** 69 * Q098. This is a made-up, experimental version used to test version 70 * negotiation. The choice of 98 is similar to Google's choice of 99 71 * as the "IETF" version. 72 */ 73 LSQVER_098, 74#define LSQUIC_EXPERIMENTAL_Q098 (1 << LSQVER_098) 75#else 76#define LSQUIC_EXPERIMENTAL_Q098 0 77#endif 78 79 /** 80 * IETF QUIC Draft-27 81 */ 82 LSQVER_ID27, 83 84 /** 85 * IETF QUIC Draft-28; this version is deprecated. 86 */ 87 LSQVER_ID28, 88 89 /** 90 * IETF QUIC Draft-29 91 */ 92 LSQVER_ID29, 93 94 /** 95 * IETF QUIC Draft-32 96 */ 97 LSQVER_ID32, 98 99 /** 100 * Special version to trigger version negotiation. 101 * [draft-ietf-quic-transport-11], Section 3. 102 */ 103 LSQVER_VERNEG, 104 105 N_LSQVER 106}; 107 108/** 109 * We currently support versions 43, 46, 50, Draft-27, Draft-28, Draft-29, 110 * and Draft-32. 111 * @see lsquic_version 112 */ 113#define LSQUIC_SUPPORTED_VERSIONS ((1 << N_LSQVER) - 1) 114 115/** 116 * List of versions in which the server never includes CID in short packets. 117 */ 118#define LSQUIC_FORCED_TCID0_VERSIONS ((1 << LSQVER_046)|(1 << LSQVER_050)) 119 120#define LSQUIC_EXPERIMENTAL_VERSIONS ( \ 121 (1 << LSQVER_VERNEG) | LSQUIC_EXPERIMENTAL_Q098) 122 123#define LSQUIC_DEPRECATED_VERSIONS ((1 << LSQVER_ID27) | (1 << LSQVER_ID28)) 124 125#define LSQUIC_GQUIC_HEADER_VERSIONS (1 << LSQVER_043) 126 127#define LSQUIC_IETF_VERSIONS ((1 << LSQVER_ID27) | (1 << LSQVER_ID28) \ 128 | (1 << LSQVER_ID29) \ 129 | (1 << LSQVER_ID32) | (1 << LSQVER_VERNEG)) 130 131#define LSQUIC_IETF_DRAFT_VERSIONS ((1 << LSQVER_ID27) | (1 << LSQVER_ID28) \ 132 | (1 << LSQVER_ID29) \ 133 | (1 << LSQVER_ID32) | (1 << LSQVER_VERNEG)) 134 135enum lsquic_hsk_status 136{ 137 /** 138 * The handshake failed. 139 */ 140 LSQ_HSK_FAIL, 141 /** 142 * The handshake succeeded without session resumption. 143 */ 144 LSQ_HSK_OK, 145 /** 146 * The handshake succeeded with session resumption. 147 */ 148 LSQ_HSK_RESUMED_OK, 149 /** 150 * Session resumption failed. Retry the connection without session 151 * resumption. 152 */ 153 LSQ_HSK_RESUMED_FAIL, 154}; 155 156/** 157 * @struct lsquic_stream_if 158 * @brief The definitions of callback functions called by lsquic_stream to 159 * process events. 160 * 161 */ 162struct lsquic_stream_if { 163 164 /** 165 * Use @ref lsquic_conn_get_ctx to get back the context. It is 166 * OK for this function to return NULL. 167 */ 168 lsquic_conn_ctx_t *(*on_new_conn)(void *stream_if_ctx, 169 lsquic_conn_t *c); 170 171 /** This is called when our side received GOAWAY frame. After this, 172 * new streams should not be created. The callback is optional. 173 */ 174 void (*on_goaway_received)(lsquic_conn_t *c); 175 void (*on_conn_closed)(lsquic_conn_t *c); 176 177 /** If you need to initiate a connection, call lsquic_conn_make_stream(). 178 * This will cause `on_new_stream' callback to be called when appropriate 179 * (this operation is delayed when maximum number of outgoing streams is 180 * reached). 181 * 182 * After `on_close' is called, the stream is no longer accessible. 183 */ 184 lsquic_stream_ctx_t * 185 (*on_new_stream)(void *stream_if_ctx, lsquic_stream_t *s); 186 187 void (*on_read) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 188 void (*on_write) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 189 void (*on_close) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 190 /* Called when datagram is ready to be written */ 191 ssize_t (*on_dg_write)(lsquic_conn_t *c, void *, size_t); 192 /* Called when datagram is read from a packet. This callback is required 193 * when es_datagrams is true. Take care to process it quickly, as this 194 * is called during lsquic_engine_packet_in(). 195 */ 196 void (*on_datagram)(lsquic_conn_t *, const void *buf, size_t); 197 /* This callback in only called in client mode */ 198 /** 199 * When handshake is completed, this optional callback is called. 200 */ 201 void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s); 202 /** 203 * When client receives a token in NEW_TOKEN frame, this callback is called. 204 * The callback is optional. 205 */ 206 void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token, 207 size_t token_size); 208 /** 209 * This optional callback lets client record information needed to 210 * perform a session resumption next time around. 211 */ 212 void (*on_sess_resume_info)(lsquic_conn_t *c, const unsigned char *, size_t); 213 /** 214 * Optional callback is called as soon as the peer resets a stream. 215 * The argument `how' is either 0, 1, or 2, meaning "read", "write", and 216 * "read and write", respectively (just like in shutdown(2)). This 217 * signals the user to stop reading, writing, or both. 218 * 219 * Note that resets differ in gQUIC and IETF QUIC. In gQUIC, `how' is 220 * always 2; in IETF QUIC, `how' is either 0 or 1 because on can reset 221 * just one direction in IETF QUIC. 222 */ 223 void (*on_reset) (lsquic_stream_t *s, lsquic_stream_ctx_t *h, int how); 224}; 225 226struct ssl_ctx_st; 227struct ssl_st; 228struct lsxpack_header; 229 230/** 231 * QUIC engine in server mode needs access to certificates. This is 232 * accomplished by providing a callback and a context to the engine 233 * constructor. 234 */ 235 236/* `sni' may be NULL if engine is not HTTP mode and client TLS transport 237 * parameters did not include the SNI. 238 */ 239typedef struct ssl_ctx_st * (*lsquic_lookup_cert_f)( 240 void *lsquic_cert_lookup_ctx, const struct sockaddr *local, const char *sni); 241 242/** 243 * Minimum flow control window is set to 16 KB for both client and server. 244 * This means we can send up to this amount of data before handshake gets 245 * completed. 246 */ 247#define LSQUIC_MIN_FCW (16 * 1024) 248 249/* Each LSQUIC_DF_* value corresponds to es_* entry in 250 * lsquic_engine_settings below. 251 */ 252 253/** 254 * By default, deprecated and experimental versions are not included. 255 */ 256#define LSQUIC_DF_VERSIONS (LSQUIC_SUPPORTED_VERSIONS & \ 257 ~LSQUIC_DEPRECATED_VERSIONS & \ 258 ~LSQUIC_EXPERIMENTAL_VERSIONS) 259 260#define LSQUIC_DF_CFCW_SERVER (3 * 1024 * 1024 / 2) 261#define LSQUIC_DF_CFCW_CLIENT (15 * 1024 * 1024) 262#define LSQUIC_DF_SFCW_SERVER (1 * 1024 * 1024) 263#define LSQUIC_DF_SFCW_CLIENT (6 * 1024 * 1024) 264#define LSQUIC_DF_MAX_STREAMS_IN 100 265 266/* IQUIC uses different names for these: */ 267#define LSQUIC_DF_INIT_MAX_DATA_SERVER LSQUIC_DF_CFCW_SERVER 268#define LSQUIC_DF_INIT_MAX_DATA_CLIENT LSQUIC_DF_CFCW_CLIENT 269#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER LSQUIC_DF_SFCW_SERVER 270#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER 0 271#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT 0 272#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT LSQUIC_DF_SFCW_CLIENT 273#define LSQUIC_DF_INIT_MAX_STREAMS_BIDI LSQUIC_DF_MAX_STREAMS_IN 274#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT 100 275#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_SERVER 3 276/* XXX What's a good value here? */ 277#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT (32 * 1024) 278#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER (12 * 1024) 279 280/** 281 * Default idle connection time in seconds. 282 */ 283#define LSQUIC_DF_IDLE_TIMEOUT 30 284 285/** 286 * Default ping period in seconds. 287 */ 288#define LSQUIC_DF_PING_PERIOD 15 289 290/** 291 * Default handshake timeout in microseconds. 292 */ 293#define LSQUIC_DF_HANDSHAKE_TO (10 * 1000 * 1000) 294 295#define LSQUIC_DF_IDLE_CONN_TO (LSQUIC_DF_IDLE_TIMEOUT * 1000 * 1000) 296#define LSQUIC_DF_SILENT_CLOSE 1 297 298/** Default value of maximum header list size. If set to non-zero value, 299 * SETTINGS_MAX_HEADER_LIST_SIZE will be sent to peer after handshake is 300 * completed (assuming the peer supports this setting frame type). 301 */ 302#define LSQUIC_DF_MAX_HEADER_LIST_SIZE 0 303 304/** Default value of UAID (user-agent ID). */ 305#define LSQUIC_DF_UA "LSQUIC" 306 307#define LSQUIC_DF_STTL 86400 308#define LSQUIC_DF_MAX_INCHOATE (1 * 1000 * 1000) 309/** Do not use NSTP by default */ 310#define LSQUIC_DF_SUPPORT_NSTP 0 311/** TODO: IETF QUIC clients do not support push */ 312#define LSQUIC_DF_SUPPORT_PUSH 1 313#define LSQUIC_DF_SUPPORT_TCID0 1 314/** By default, LSQUIC ignores Public Reset packets. */ 315#define LSQUIC_DF_HONOR_PRST 0 316 317/** 318 * By default, LSQUIC will not send Public Reset packets in response to 319 * packets that specify unknown connections. 320 */ 321#define LSQUIC_DF_SEND_PRST 0 322 323/** By default, infinite loop checks are turned on */ 324#define LSQUIC_DF_PROGRESS_CHECK 1000 325 326/** By default, read/write events are dispatched in a loop */ 327#define LSQUIC_DF_RW_ONCE 0 328 329/** By default, the threshold is not enabled */ 330#define LSQUIC_DF_PROC_TIME_THRESH 0 331 332/** By default, packets are paced */ 333#define LSQUIC_DF_PACE_PACKETS 1 334 335/** Default clock granularity is 1000 microseconds */ 336#define LSQUIC_DF_CLOCK_GRANULARITY 1000 337 338/** The default value is 8 for simplicity */ 339#define LSQUIC_DF_SCID_LEN 8 340 341/** The default value is 60 CIDs per minute */ 342#define LSQUIC_DF_SCID_ISS_RATE 60 343 344#define LSQUIC_DF_QPACK_DEC_MAX_BLOCKED 100 345#define LSQUIC_DF_QPACK_DEC_MAX_SIZE 4096 346#define LSQUIC_DF_QPACK_ENC_MAX_BLOCKED 100 347#define LSQUIC_DF_QPACK_ENC_MAX_SIZE 4096 348 349/* By default, QPACK experiments are turned off */ 350#define LSQUIC_DF_QPACK_EXPERIMENT 0 351 352/** ECN is disabled by default */ 353#define LSQUIC_DF_ECN 0 354 355/** Allow migration by default */ 356#define LSQUIC_DF_ALLOW_MIGRATION 1 357 358/** Use QL loss bits by default */ 359#define LSQUIC_DF_QL_BITS 2 360 361/** Turn spin bit on by default */ 362#define LSQUIC_DF_SPIN 1 363 364/** Turn on delayed ACKs extension by default */ 365#define LSQUIC_DF_DELAYED_ACKS 1 366 367/** 368 * Defaults for the Packet Tolerance PID Controller (PTPC) used by the 369 * Delayed ACKs extension: 370 */ 371#define LSQUIC_DF_PTPC_PERIODICITY 3 372#define LSQUIC_DF_PTPC_MAX_PACKTOL 150 373#define LSQUIC_DF_PTPC_DYN_TARGET 1 374#define LSQUIC_DF_PTPC_TARGET 1.0 375#define LSQUIC_DF_PTPC_PROP_GAIN 0.8 376#define LSQUIC_DF_PTPC_INT_GAIN 0.35 377#define LSQUIC_DF_PTPC_ERR_THRESH 0.05 378#define LSQUIC_DF_PTPC_ERR_DIVISOR 0.05 379 380/** Turn on timestamp extension by default */ 381#define LSQUIC_DF_TIMESTAMPS 1 382 383/* Use Adaptive CC by default */ 384#define LSQUIC_DF_CC_ALGO 3 385 386/* Default value of the CC RTT threshold is 1.5 ms */ 387#define LSQUIC_DF_CC_RTT_THRESH 1500 388 389/** Turn off datagram extension by default */ 390#define LSQUIC_DF_DATAGRAMS 0 391 392/** Assume optimistic NAT by default. */ 393#define LSQUIC_DF_OPTIMISTIC_NAT 1 394 395/** Turn on Extensible HTTP Priorities by default. */ 396#define LSQUIC_DF_EXT_HTTP_PRIO 1 397 398/** By default, incoming packet size is not limited. */ 399#define LSQUIC_DF_MAX_UDP_PAYLOAD_SIZE_RX 0 400 401/** 402 * By default, greasing the QUIC bit is enabled (if peer sent 403 * the "grease_quic_bit" transport parameter). 404 */ 405#define LSQUIC_DF_GREASE_QUIC_BIT 1 406 407/** By default, DPLPMTUD is enabled */ 408#define LSQUIC_DF_DPLPMTUD 1 409 410/** By default, this value is left up to the engine. */ 411#define LSQUIC_DF_BASE_PLPMTU 0 412 413/** By default, this value is left up to the engine. */ 414#define LSQUIC_DF_MAX_PLPMTU 0 415 416/** By default, drop no-progress connections after 60 seconds on the server */ 417#define LSQUIC_DF_NOPROGRESS_TIMEOUT_SERVER 60 418 419/** By default, do not use no-progress timeout on the client */ 420#define LSQUIC_DF_NOPROGRESS_TIMEOUT_CLIENT 0 421 422/** By default, we use the minimum timer of 1000 milliseconds */ 423#define LSQUIC_DF_MTU_PROBE_TIMER 1000 424 425/** By default, calling on_close() is not delayed */ 426#define LSQUIC_DF_DELAY_ONCLOSE 0 427 428struct lsquic_engine_settings { 429 /** 430 * This is a bit mask wherein each bit corresponds to a value in 431 * enum lsquic_version. Client starts negotiating with the highest 432 * version and goes down. Server supports either of the versions 433 * specified here. 434 * 435 * This setting applies to both Google and IETF QUIC. 436 * 437 * @see lsquic_version 438 */ 439 unsigned es_versions; 440 441 /** 442 * Initial default CFCW. 443 * 444 * In server mode, per-connection values may be set lower than 445 * this if resources are scarce. 446 * 447 * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW. 448 * 449 * @see es_max_cfcw 450 */ 451 unsigned es_cfcw; 452 453 /** 454 * Initial default SFCW. 455 * 456 * In server mode, per-connection values may be set lower than 457 * this if resources are scarce. 458 * 459 * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW. 460 * 461 * @see es_max_sfcw 462 */ 463 unsigned es_sfcw; 464 465 /** 466 * This value is used to specify maximum allowed value CFCW is allowed 467 * to reach due to window auto-tuning. By default, this value is zero, 468 * which means that CFCW is not allowed to increase from its initial 469 * value. 470 * 471 * This setting is applicable to both gQUIC and IETF QUIC. 472 * 473 * @see es_cfcw, @see es_init_max_data. 474 */ 475 unsigned es_max_cfcw; 476 477 /** 478 * This value is used to specify the maximum value stream flow control 479 * window is allowed to reach due to auto-tuning. By default, this 480 * value is zero, meaning that auto-tuning is turned off. 481 * 482 * This setting is applicable to both gQUIC and IETF QUIC. 483 * 484 * @see es_sfcw, @see es_init_max_stream_data_bidi_remote, 485 * @see es_init_max_stream_data_bidi_local. 486 */ 487 unsigned es_max_sfcw; 488 489 /** MIDS */ 490 unsigned es_max_streams_in; 491 492 /** 493 * Handshake timeout in microseconds. 494 * 495 * For client, this can be set to an arbitrary value (zero turns the 496 * timeout off). 497 * 498 * For server, this value is limited to about 16 seconds. Do not set 499 * it to zero. 500 */ 501 unsigned long es_handshake_to; 502 503 /** ICSL in microseconds; GQUIC only */ 504 unsigned long es_idle_conn_to; 505 506 /** 507 * When true, CONNECTION_CLOSE is not sent when connection times out. 508 * The server will also not send a reply to client's CONNECTION_CLOSE. 509 * 510 * Corresponds to SCLS (silent close) gQUIC option. 511 */ 512 int es_silent_close; 513 514 /** 515 * This corresponds to SETTINGS_MAX_HEADER_LIST_SIZE 516 * (RFC 7540, Section 6.5.2). 0 means no limit. Defaults 517 * to @ref LSQUIC_DF_MAX_HEADER_LIST_SIZE. 518 */ 519 unsigned es_max_header_list_size; 520 521 /** UAID -- User-Agent ID. Defaults to @ref LSQUIC_DF_UA. */ 522 const char *es_ua; 523 524 /** 525 * More parameters for server 526 */ 527 uint64_t es_sttl; /* SCFG TTL in seconds */ 528 529 uint32_t es_pdmd; /* One fixed value X509 */ 530 uint32_t es_aead; /* One fixed value AESG */ 531 uint32_t es_kexs; /* One fixed value C255 */ 532 533 /* Maximum number of incoming connections in inchoate state. This is 534 * only applicable in server mode. 535 */ 536 unsigned es_max_inchoate; 537 538 /** 539 * Setting this value to 0 means that 540 * 541 * For client: 542 * a) we send a SETTINGS frame to indicate that we do not support server 543 * push; and 544 * b) All incoming pushed streams get reset immediately. 545 * (For maximum effect, set es_max_streams_in to 0.) 546 * 547 * For server: 548 * lsquic_conn_push_stream() will return -1. 549 */ 550 int es_support_push; 551 552 /** 553 * If set to true value, the server will not include connection ID in 554 * outgoing packets if client's CHLO specifies TCID=0. 555 * 556 * For client, this means including TCID=0 into CHLO message. Note that 557 * in this case, the engine tracks connections by the 558 * (source-addr, dest-addr) tuple, thereby making it necessary to create 559 * a socket for each connection. 560 * 561 * This option has no effect in Q046 and Q050, as the server never includes 562 * CIDs in the short packets. 563 * 564 * This setting is applicable to gQUIC only. 565 * 566 * The default is @ref LSQUIC_DF_SUPPORT_TCID0. 567 */ 568 int es_support_tcid0; 569 570 /** 571 * Q037 and higher support "No STOP_WAITING frame" mode. When set, the 572 * client will send NSTP option in its Client Hello message and will not 573 * sent STOP_WAITING frames, while ignoring incoming STOP_WAITING frames, 574 * if any. Note that if the version negotiation happens to downgrade the 575 * client below Q037, this mode will *not* be used. 576 * 577 * This option does not affect the server, as it must support NSTP mode 578 * if it was specified by the client. 579 * 580 * This setting is applicable to gQUIC only. 581 */ 582 int es_support_nstp; 583 584 /** 585 * If set to true value, the library will drop connections when it 586 * receives corresponding Public Reset packet. The default is to 587 * ignore these packets. 588 * 589 * The default is @ref LSQUIC_DF_HONOR_PRST. 590 */ 591 int es_honor_prst; 592 593 /** 594 * If set to true value, the library will send Public Reset packets 595 * in response to incoming packets with unknown Connection IDs. 596 * The default is @ref LSQUIC_DF_SEND_PRST. 597 */ 598 int es_send_prst; 599 600 /** 601 * A non-zero value enables internal checks that identify suspected 602 * infinite loops in user @ref on_read and @ref on_write callbacks 603 * and break them. An infinite loop may occur if user code keeps 604 * on performing the same operation without checking status, e.g. 605 * reading from a closed stream etc. 606 * 607 * The value of this parameter is as follows: should a callback return 608 * this number of times in a row without making progress (that is, 609 * reading, writing, or changing stream state), loop break will occur. 610 * 611 * The defaut value is @ref LSQUIC_DF_PROGRESS_CHECK. 612 */ 613 unsigned es_progress_check; 614 615 /** 616 * A non-zero value make stream dispatch its read-write events once 617 * per call. 618 * 619 * When zero, read and write events are dispatched until the stream 620 * is no longer readable or writeable, respectively, or until the 621 * user signals unwillingness to read or write using 622 * @ref lsquic_stream_wantread() or @ref lsquic_stream_wantwrite() 623 * or shuts down the stream. 624 * 625 * This also applies to the on_dg_write() callback. 626 * 627 * The default value is @ref LSQUIC_DF_RW_ONCE. 628 */ 629 int es_rw_once; 630 631 /** 632 * If set, this value specifies the number of microseconds that 633 * @ref lsquic_engine_process_conns() and 634 * @ref lsquic_engine_send_unsent_packets() are allowed to spend 635 * before returning. 636 * 637 * This is not an exact science and the connections must make 638 * progress, so the deadline is checked after all connections get 639 * a chance to tick (in the case of @ref lsquic_engine_process_conns()) 640 * and at least one batch of packets is sent out. 641 * 642 * When processing function runs out of its time slice, immediate 643 * calls to @ref lsquic_engine_has_unsent_packets() return false. 644 * 645 * The default value is @ref LSQUIC_DF_PROC_TIME_THRESH. 646 */ 647 unsigned es_proc_time_thresh; 648 649 /** 650 * If set to true, packet pacing is implemented per connection. 651 * 652 * The default value is @ref LSQUIC_DF_PACE_PACKETS. 653 */ 654 int es_pace_packets; 655 656 /** 657 * Clock granularity information is used by the pacer. The value 658 * is in microseconds; default is @ref LSQUIC_DF_CLOCK_GRANULARITY. 659 */ 660 unsigned es_clock_granularity; 661 662 /** 663 * Congestion control algorithm to use. 664 * 665 * 0: Use default (@ref LSQUIC_DF_CC_ALGO) 666 * 1: Cubic 667 * 2: BBRv1 668 * 3: Adaptive (Cubic or BBRv1) 669 */ 670 unsigned es_cc_algo; 671 672 /** 673 * Congestion controller RTT threshold in microseconds. 674 * 675 * Adaptive congestion control uses BBRv1 until RTT is determined. At 676 * that point a permanent choice of congestion controller is made. If 677 * RTT is smaller than or equal to es_cc_rtt_thresh, congestion 678 * controller is switched to Cubic; otherwise, BBRv1 is picked. 679 * 680 * The default value is @ref LSQUIC_DF_CC_RTT_THRESH. 681 */ 682 unsigned es_cc_rtt_thresh; 683 684 /** 685 * No progress timeout. 686 * 687 * If connection does not make progress for this number of seconds, the 688 * connection is dropped. Here, progress is defined as user streams 689 * being written to or read from. 690 * 691 * If this value is zero, this timeout is disabled. 692 * 693 * Default value is @ref LSQUIC_DF_NOPROGRESS_TIMEOUT_SERVER in server 694 * mode and @ref LSQUIC_DF_NOPROGRESS_TIMEOUT_CLIENT in client mode. 695 */ 696 unsigned es_noprogress_timeout; 697 698 /* The following settings are specific to IETF QUIC. */ 699 /* vvvvvvvvvvv */ 700 701 /** 702 * Initial max data. 703 * 704 * This is a transport parameter. 705 * 706 * Depending on the engine mode, the default value is either 707 * @ref LSQUIC_DF_INIT_MAX_DATA_CLIENT or 708 * @ref LSQUIC_DF_INIT_MAX_DATA_SERVER. 709 */ 710 unsigned es_init_max_data; 711 712 /** 713 * Initial maximum amount of stream data allowed to be sent on streams 714 * created by remote end (peer). 715 * 716 * This is a transport parameter. 717 * 718 * Depending on the engine mode, the default value is either 719 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT or 720 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER. 721 */ 722 unsigned es_init_max_stream_data_bidi_remote; 723 724 /** 725 * Initial maximum amount of stream data allowed to be sent on streams 726 * created by remote end (peer). 727 * 728 * This is a transport parameter. 729 * 730 * Depending on the engine mode, the default value is either 731 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT or 732 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER. 733 */ 734 unsigned es_init_max_stream_data_bidi_local; 735 736 /** 737 * Initial max stream data for unidirectional streams initiated 738 * by remote endpoint. 739 * 740 * This is a transport parameter. 741 * 742 * Depending on the engine mode, the default value is either 743 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT or 744 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER. 745 */ 746 unsigned es_init_max_stream_data_uni; 747 748 /** 749 * Maximum initial number of bidirectional stream. 750 * 751 * This is a transport parameter. 752 * 753 * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_BIDI. 754 */ 755 unsigned es_init_max_streams_bidi; 756 757 /** 758 * Maximum initial number of unidirectional stream. 759 * 760 * This is a transport parameter. 761 * 762 * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT or 763 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER. 764 */ 765 unsigned es_init_max_streams_uni; 766 767 /** 768 * Idle connection timeout. 769 * 770 * This is a transport parameter. 771 * 772 * (Note: es_idle_conn_to is not reused because it is in microseconds, 773 * which, I now realize, was not a good choice. Since it will be 774 * obsoleted some time after the switchover to IETF QUIC, we do not 775 * have to keep on using strange units.) 776 * 777 * Default value is @ref LSQUIC_DF_IDLE_TIMEOUT. 778 * 779 * Maximum value is 600 seconds. 780 */ 781 unsigned es_idle_timeout; 782 783 /** 784 * Ping period. If set to non-zero value, the connection will generate and 785 * send PING frames in the absence of other activity. 786 * 787 * By default, the server does not send PINGs and the period is set to zero. 788 * The client's defaut value is @ref LSQUIC_DF_PING_PERIOD. 789 */ 790 unsigned es_ping_period; 791 792 /** 793 * Source Connection ID length. Only applicable to the IETF QUIC 794 * versions. Valid values are 0 through 20, inclusive. 795 * 796 * Default value is @ref LSQUIC_DF_SCID_LEN. 797 */ 798 unsigned es_scid_len; 799 800 /** 801 * Source Connection ID issuance rate. Only applicable to the IETF QUIC 802 * versions. This field is measured in CIDs per minute. Using value 0 803 * indicates that there is no rate limit for CID issuance. 804 * 805 * Default value is @ref LSQUIC_DF_SCID_ISS_RATE. 806 */ 807 unsigned es_scid_iss_rate; 808 809 /** 810 * Maximum size of the QPACK dynamic table that the QPACK decoder will 811 * use. 812 * 813 * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_SIZE. 814 */ 815 unsigned es_qpack_dec_max_size; 816 817 /** 818 * Maximum number of blocked streams that the QPACK decoder is willing 819 * to tolerate. 820 * 821 * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_BLOCKED. 822 */ 823 unsigned es_qpack_dec_max_blocked; 824 825 /** 826 * Maximum size of the dynamic table that the encoder is willing to use. 827 * The actual size of the dynamic table will not exceed the minimum of 828 * this value and the value advertized by peer. 829 * 830 * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_SIZE. 831 */ 832 unsigned es_qpack_enc_max_size; 833 834 /** 835 * Maximum number of blocked streams that the QPACK encoder is willing 836 * to risk. The actual number of blocked streams will not exceed the 837 * minimum of this value and the value advertized by peer. 838 * 839 * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_BLOCKED. 840 */ 841 unsigned es_qpack_enc_max_blocked; 842 843 /** 844 * Enable ECN support. 845 * 846 * The default is @ref LSQUIC_DF_ECN 847 */ 848 int es_ecn; 849 850 /** 851 * Allow peer to migrate connection. 852 * 853 * The default is @ref LSQUIC_DF_ALLOW_MIGRATION 854 */ 855 int es_allow_migration; 856 857 /** 858 * Use QL loss bits. Allowed values are: 859 * 0: Do not use loss bits 860 * 1: Allow loss bits 861 * 2: Allow and send loss bits 862 * 863 * Default value is @ref LSQUIC_DF_QL_BITS 864 */ 865 int es_ql_bits; 866 867 /** 868 * Enable spin bit. Allowed values are 0 and 1. 869 * 870 * Default value is @ref LSQUIC_DF_SPIN 871 */ 872 int es_spin; 873 874 /** 875 * Enable delayed ACKs extension. Allowed values are 0 and 1. 876 * 877 * Default value is @ref LSQUIC_DF_DELAYED_ACKS 878 */ 879 int es_delayed_acks; 880 881 /** 882 * Enable timestamps extension. Allowed values are 0 and 1. 883 * 884 * Default value is @ref LSQUIC_DF_TIMESTAMPS 885 */ 886 int es_timestamps; 887 888 /** 889 * Maximum packet size we are willing to receive. This is sent to 890 * peer in transport parameters: the library does not enforce this 891 * limit for incoming packets. 892 * 893 * If set to zero, limit is not set. 894 * 895 * Default value is @ref LSQUIC_DF_MAX_UDP_PAYLOAD_SIZE_RX 896 */ 897 unsigned short es_max_udp_payload_size_rx; 898 899 /** 900 * Enable the "QUIC bit grease" extension. When set to a true value, 901 * lsquic will grease the QUIC bit on the outgoing QUIC packets if 902 * the peer sent the "grease_quic_bit" transport parameter. 903 * 904 * Default value is @ref LSQUIC_DF_GREASE_QUIC_BIT 905 */ 906 int es_grease_quic_bit; 907 908 /** 909 * If set to true value, enable DPLPMTUD -- Datagram Packetization 910 * Layer Path MTU Discovery. 911 * 912 * Default value is @ref LSQUIC_DF_DPLPMTUD 913 */ 914 int es_dplpmtud; 915 916 /** 917 * PLPMTU size expected to work for most paths. 918 * 919 * If set to zero, this value is calculated based on QUIC and IP versions. 920 * 921 * Default value is @ref LSQUIC_DF_BASE_PLPMTU. 922 */ 923 unsigned short es_base_plpmtu; 924 925 /** 926 * Largest PLPMTU size the engine will try. 927 * 928 * If set to zero, picking this value is left to the engine. 929 * 930 * Default value is @ref LSQUIC_DF_MAX_PLPMTU. 931 */ 932 unsigned short es_max_plpmtu; 933 934 /** 935 * This value specifies how long the DPLPMTUD probe timer is, in 936 * milliseconds. [draft-ietf-tsvwg-datagram-plpmtud-17] says: 937 * 938 " PROBE_TIMER: The PROBE_TIMER is configured to expire after a period 939 " longer than the maximum time to receive an acknowledgment to a 940 " probe packet. This value MUST NOT be smaller than 1 second, and 941 " SHOULD be larger than 15 seconds. Guidance on selection of the 942 " timer value are provided in section 3.1.1 of the UDP Usage 943 " Guidelines [RFC8085]. 944 * 945 * If set to zero, the default is used. 946 * 947 * Default value is @ref LSQUIC_DF_MTU_PROBE_TIMER. 948 */ 949 unsigned es_mtu_probe_timer; 950 951 /** 952 * Enable datagram extension. Allowed values are 0 and 1. 953 * 954 * Default value is @ref LSQUIC_DF_DATAGRAMS 955 */ 956 int es_datagrams; 957 958 /** 959 * If set to true, changes in peer port are assumed to be due to a 960 * benign NAT rebinding and path characteristics -- MTU, RTT, and 961 * CC state -- are not reset. 962 * 963 * Default value is @ref LSQUIC_DF_OPTIMISTIC_NAT. 964 */ 965 int es_optimistic_nat; 966 967 /** 968 * If set to true, Extensible HTTP Priorities are enabled. This 969 * is HTTP/3-only setting. 970 * 971 * Default value is @ref LSQUIC_DF_EXT_HTTP_PRIO 972 */ 973 int es_ext_http_prio; 974 975 /** 976 * If set to 1, QPACK statistics are logged per connection. 977 * 978 * If set to 2, QPACK experiments are run. In this mode, encoder 979 * and decoder setting values are randomly selected (from the range 980 * [0, whatever is specified in es_qpack_(enc|dec)_*]) and these 981 * values along with compression ratio and user agent are logged at 982 * NOTICE level when connection is destroyed. The purpose of these 983 * experiments is to use compression performance statistics to figure 984 * out a good set of default values. 985 * 986 * Default value is @ref LSQUIC_DF_QPACK_EXPERIMENT. 987 */ 988 int es_qpack_experiment; 989 990 /** 991 * Settings for the Packet Tolerance PID Controller (PTPC) used for 992 * the Delayed ACKs logic. Periodicity is how often the number of 993 * incoming ACKs is sampled. Periodicity's units is the number of 994 * RTTs. Target is the average number of incoming ACKs per RTT we 995 * want to achieve. Error threshold defines the range of error values 996 * within which no action is taken. For example, error threshold of 997 * 0.03 means that adjustment actions will be taken only when the 998 * error is outside of the [-0.03, 0.03] range. Proportional and 999 * integral gains have their usual meanings described here: 1000 * https://en.wikipedia.org/wiki/PID_controller#Controller_theory 1001 * 1002 * The average is normalized as follows: 1003 * AvgNormalized = Avg * e / Target # Where 'e' is 2.71828... 1004 * 1005 * The error is then calculated as ln(AvgNormalized) - 1. This gives 1006 * us a logarithmic scale that is convenient to use for adjustment 1007 * calculations. The error divisor is used to calculate the packet 1008 * tolerance adjustment: 1009 * Adjustment = Error / ErrorDivisor 1010 * 1011 * WARNING. The library comes with sane defaults. Only fiddle with 1012 * these knobs if you know what you are doing. 1013 */ 1014 unsigned es_ptpc_periodicity; /* LSQUIC_DF_PTPC_PERIODICITY */ 1015 unsigned es_ptpc_max_packtol; /* LSQUIC_DF_PTPC_MAX_PACKTOL */ 1016 int es_ptpc_dyn_target; /* LSQUIC_DF_PTPC_DYN_TARGET */ 1017 float es_ptpc_target, /* LSQUIC_DF_PTPC_TARGET */ 1018 es_ptpc_prop_gain, /* LSQUIC_DF_PTPC_PROP_GAIN */ 1019 es_ptpc_int_gain, /* LSQUIC_DF_PTPC_INT_GAIN */ 1020 es_ptpc_err_thresh, /* LSQUIC_DF_PTPC_ERR_THRESH */ 1021 es_ptpc_err_divisor; /* LSQUIC_DF_PTPC_ERR_DIVISOR */ 1022 1023 /** 1024 * When set to true, the on_close() callback will be delayed until the 1025 * peer acknowledges all data sent on the stream. (Or until the connection 1026 * is destroyed in some manner -- either explicitly closed by the user or 1027 * as a result of an engine shutdown.) 1028 * 1029 * Default value is @ref LSQUIC_DF_DELAY_ONCLOSE 1030 */ 1031 int es_delay_onclose; 1032}; 1033 1034/* Initialize `settings' to default values */ 1035void 1036lsquic_engine_init_settings (struct lsquic_engine_settings *, 1037 unsigned lsquic_engine_flags); 1038 1039/** 1040 * Check settings for errors. 1041 * 1042 * @param settings Settings struct. 1043 * 1044 * @param flags Engine flags. 1045 * 1046 * @param err_buf Optional pointer to buffer into which error string 1047 * is written. 1048 1049 * @param err_buf_sz Size of err_buf. No more than this number of bytes 1050 * will be written to err_buf, including the NUL byte. 1051 * 1052 * @retval 0 Settings have no errors. 1053 * @retval -1 There are errors in settings. 1054 */ 1055int 1056lsquic_engine_check_settings (const struct lsquic_engine_settings *settings, 1057 unsigned lsquic_engine_flags, 1058 char *err_buf, size_t err_buf_sz); 1059 1060struct lsquic_out_spec 1061{ 1062 struct iovec *iov; 1063 size_t iovlen; 1064 const struct sockaddr *local_sa; 1065 const struct sockaddr *dest_sa; 1066 void *peer_ctx; 1067 lsquic_conn_ctx_t *conn_ctx; /* will be NULL when sending out the first batch of handshake packets */ 1068 int ecn; /* Valid values are 0 - 3. See RFC 3168 */ 1069}; 1070 1071/** 1072 * Returns number of packets successfully sent out or -1 on error. -1 should 1073 * only be returned if no packets were sent out. If -1 is returned or if the 1074 * return value is smaller than `n_packets_out', this indicates that sending 1075 * of packets is not possible. 1076 * 1077 * If not all packets could be sent out, errno is examined. If it is not 1078 * EAGAIN or EWOULDBLOCK, the connection whose packet cause the error is 1079 * closed forthwith. 1080 * 1081 * No packets will be attempted to be sent out until 1082 * @ref lsquic_engine_send_unsent_packets() is called. 1083 */ 1084typedef int (*lsquic_packets_out_f)( 1085 void *packets_out_ctx, 1086 const struct lsquic_out_spec *out_spec, 1087 unsigned n_packets_out 1088); 1089 1090/** 1091 * The shared hash interface is used to share data between multiple LSQUIC 1092 * instances. 1093 */ 1094struct lsquic_shared_hash_if 1095{ 1096 /** 1097 * If you want your item to never expire, set `expiry' to zero. 1098 * Returns 0 on success, -1 on failure. 1099 * 1100 * If inserted successfully, `free()' will be called on `data' and 'key' 1101 * pointer when the element is deleted, whether due to expiration 1102 * or explicit deletion. 1103 */ 1104 int (*shi_insert)(void *shi_ctx, void *key, unsigned key_sz, 1105 void *data, unsigned data_sz, time_t expiry); 1106 /** 1107 * Returns 0 on success, -1 on failure. 1108 */ 1109 int (*shi_delete)(void *shi_ctx, const void *key, unsigned key_sz); 1110 1111 /** 1112 * `data' is pointed to the result and `data_sz' is set to the 1113 * object size. The implementation may choose to copy the object 1114 * into buffer pointed to by `data', so you should have it ready. 1115 * 1116 * @retval 1 found. 1117 * @retval 0 not found. 1118 * @retval -1 error (perhaps not enough room in `data' if copy was 1119 * attempted). 1120 */ 1121 int (*shi_lookup)(void *shi_ctx, const void *key, unsigned key_sz, 1122 void **data, unsigned *data_sz); 1123}; 1124 1125/** 1126 * The packet out memory interface is used by LSQUIC to get buffers to 1127 * which outgoing packets will be written before they are passed to 1128 * ea_packets_out callback. 1129 * 1130 * If not specified, malloc() and free() are used. 1131 */ 1132struct lsquic_packout_mem_if 1133{ 1134 /** 1135 * Allocate buffer for sending. 1136 */ 1137 void * (*pmi_allocate) (void *pmi_ctx, void *peer_ctx, lsquic_conn_ctx_t *, unsigned short sz, 1138 char is_ipv6); 1139 /** 1140 * This function is used to release the allocated buffer after it is 1141 * sent via @ref ea_packets_out. 1142 */ 1143 void (*pmi_release) (void *pmi_ctx, void *peer_ctx, void *buf, 1144 char is_ipv6); 1145 /** 1146 * If allocated buffer is not going to be sent, return it to the caller 1147 * using this function. 1148 */ 1149 void (*pmi_return) (void *pmi_ctx, void *peer_ctx, void *buf, 1150 char is_ipv6); 1151}; 1152 1153typedef void (*lsquic_cids_update_f)(void *ctx, void **peer_ctx, 1154 const lsquic_cid_t *cids, unsigned n_cids); 1155 1156struct stack_st_X509; 1157 1158enum lsquic_hsi_flag { 1159 /** 1160 * Turn HTTP/1.x mode on or off. In this mode, decoded name and value 1161 * pair are separated by ": " and "\r\n" is appended to the end of the 1162 * string. By default, this mode is off. 1163 */ 1164 LSQUIC_HSI_HTTP1X = 1 << 1, 1165 /** Include name hash into lsxpack_header */ 1166 LSQUIC_HSI_HASH_NAME = 1 << 2, 1167 /** Include nameval hash into lsxpack_header */ 1168 LSQUIC_HSI_HASH_NAMEVAL = 1 << 3, 1169}; 1170 1171struct lsquic_hset_if 1172{ 1173 /** 1174 * Create a new header set. This object is (and must be) fetched from a 1175 * stream by calling @ref lsquic_stream_get_hset() before the stream can 1176 * be read. 1177 * 1178 * `stream' may be set to NULL in server mode. 1179 */ 1180 void * (*hsi_create_header_set)(void *hsi_ctx, lsquic_stream_t *stream, 1181 int is_push_promise); 1182 /** 1183 * Return a header set prepared for decoding. If `hdr' is NULL, this 1184 * means return a new structure with at least `space' bytes available 1185 * in the decoder buffer. On success, a newly prepared header is 1186 * returned. 1187 * 1188 * If `hdr' is not NULL, it means there was not enough decoder buffer 1189 * and it must be increased to at least `space' bytes. `buf', `val_len', 1190 * and `name_offset' member of the `hdr' structure may change. On 1191 * success, the return value is the same as `hdr'. 1192 * 1193 * If NULL is returned, the space cannot be allocated. 1194 */ 1195 struct lsxpack_header * 1196 (*hsi_prepare_decode)(void *hdr_set, 1197 struct lsxpack_header *hdr, 1198 size_t space); 1199 /** 1200 * Process new header. Return 0 on success, a positive value if a header 1201 * error occured, or a negative value on any other error. 1202 * 1203 * A positive return value will result in cancellation of associated 1204 * stream. 1205 * 1206 * A negative return value will result in connection being aborted. 1207 * 1208 * `hdr_set' is the header set object returned by 1209 * @ref hsi_create_header_set(). 1210 * 1211 * `hdr' is the header returned by @ref `hsi_prepare_decode'. 1212 * 1213 * If `hdr' is NULL, this means that no more header are going to be 1214 * added to the set. 1215 */ 1216 int (*hsi_process_header)(void *hdr_set, struct lsxpack_header *hdr); 1217 /** 1218 * Discard header set. This is called for unclaimed header sets and 1219 * header sets that had an error. 1220 */ 1221 void (*hsi_discard_header_set)(void *hdr_set); 1222 /** 1223 * These flags specify properties of decoded headers passed to 1224 * hsi_process_header(). This is only applicable to QPACK headers; 1225 * HPACK library header properties are based on compilation, not 1226 * run-time, options. 1227 */ 1228 enum lsquic_hsi_flag hsi_flags; 1229}; 1230 1231/** 1232 * SSL keylog interface. 1233 */ 1234struct lsquic_keylog_if 1235{ 1236 /** Return keylog handle or NULL if no key logging is desired */ 1237 void * (*kli_open) (void *keylog_ctx, lsquic_conn_t *); 1238 1239 /** 1240 * Log line. The first argument is the pointer returned by 1241 * @ref kli_open. 1242 */ 1243 void (*kli_log_line) (void *handle, const char *line); 1244 1245 /** 1246 * Close handle. 1247 */ 1248 void (*kli_close) (void *handle); 1249}; 1250 1251/** 1252 * This struct contains a list of all callbacks that are used by the engine 1253 * to communicate with the user code. Most of these are optional, while 1254 * the following are mandatory: 1255 * 1256 * @ref ea_stream_if The stream interface. 1257 * @ref ea_packets_out Function to send packets. 1258 * @ref ea_lookup_cert Function to look up certificates by SNI (used 1259 * in server mode). 1260 * 1261 * A pointer to this structure is passed to engine constructor 1262 * @ref lsquic_engine_new(). 1263 */ 1264struct lsquic_engine_api 1265{ 1266 const struct lsquic_engine_settings *ea_settings; /* Optional */ 1267 /** Stream interface is required to manage connections and streams. */ 1268 const struct lsquic_stream_if *ea_stream_if; 1269 void *ea_stream_if_ctx; 1270 /** Function to send packets out is required. */ 1271 lsquic_packets_out_f ea_packets_out; 1272 void *ea_packets_out_ctx; 1273 /** Function to look up certificates by SNI is used in server mode. */ 1274 lsquic_lookup_cert_f ea_lookup_cert; 1275 void *ea_cert_lu_ctx; 1276 /** Mandatory callback for server, optional for client. */ 1277 struct ssl_ctx_st * (*ea_get_ssl_ctx)(void *peer_ctx, 1278 const struct sockaddr *local); 1279 /** 1280 * Shared hash interface is optional. If set to zero, performance of 1281 * multiple LSQUIC instances will be degraded. 1282 */ 1283 const struct lsquic_shared_hash_if *ea_shi; 1284 void *ea_shi_ctx; 1285 /** 1286 * Memory interface is optional. 1287 */ 1288 const struct lsquic_packout_mem_if *ea_pmi; 1289 void *ea_pmi_ctx; 1290 /** 1291 * Optional interface to report new and old source connection IDs. 1292 */ 1293 lsquic_cids_update_f ea_new_scids; 1294 lsquic_cids_update_f ea_live_scids; 1295 lsquic_cids_update_f ea_old_scids; 1296 void *ea_cids_update_ctx; 1297 /** 1298 * Function to verify server certificate. The chain contains at least 1299 * one element. The first element in the chain is the server 1300 * certificate. The chain belongs to the library. If you want to 1301 * retain it, call sk_X509_up_ref(). 1302 * 1303 * 0 is returned on success, -1 on error. 1304 * 1305 * If the function pointer is not set, no verification is performed 1306 * (the connection is allowed to proceed). 1307 */ 1308 int (*ea_verify_cert)(void *verify_ctx, 1309 struct stack_st_X509 *chain); 1310 void *ea_verify_ctx; 1311 1312 /** 1313 * Optional header set interface. If not specified, the incoming headers 1314 * are converted to HTTP/1.x format and are read from stream and have to 1315 * be parsed again. 1316 */ 1317 const struct lsquic_hset_if *ea_hsi_if; 1318 void *ea_hsi_ctx; 1319#if LSQUIC_CONN_STATS 1320 /** 1321 * If set, engine will print cumulative connection statistics to this 1322 * file just before it is destroyed. 1323 */ 1324 void /* FILE, really */ *ea_stats_fh; 1325#endif 1326 1327 /** 1328 * Optional SSL key logging interface. 1329 */ 1330 const struct lsquic_keylog_if *ea_keylog_if; 1331 void *ea_keylog_ctx; 1332 1333 /** 1334 * The optional ALPN string is used by the client if @ref LSENG_HTTP 1335 * is not set. 1336 */ 1337 const char *ea_alpn; 1338 1339 /** 1340 * Optional interface to control the creation of connection IDs 1341 */ 1342 void (*ea_generate_scid)(lsquic_conn_t *, 1343 lsquic_cid_t *, unsigned); 1344}; 1345 1346/** 1347 * Create new engine. 1348 * 1349 * @param lsquic_engine_flags A bitmask of @ref LSENG_SERVER and 1350 * @ref LSENG_HTTP 1351 * 1352 * @param api Required parameter that specifies 1353 * various callbacks. 1354 * 1355 * The engine can be instantiated either in server mode (when LSENG_SERVER 1356 * is set) or client mode. If you need both server and client in your 1357 * program, create two engines (or as many as you'd like). 1358 */ 1359lsquic_engine_t * 1360lsquic_engine_new (unsigned lsquic_engine_flags, 1361 const struct lsquic_engine_api *api); 1362 1363/** 1364 * Create a client connection to peer identified by `peer_ctx'. 1365 * 1366 * To let the engine specify QUIC version, use N_LSQVER. If session resumption 1367 * information is supplied, version is picked from there instead. 1368 * 1369 * If `base_plpmtu' is set to zero, it is selected based on the 1370 * engine settings, QUIC version, and IP version. 1371 */ 1372lsquic_conn_t * 1373lsquic_engine_connect (lsquic_engine_t *, enum lsquic_version, 1374 const struct sockaddr *local_sa, 1375 const struct sockaddr *peer_sa, 1376 void *peer_ctx, lsquic_conn_ctx_t *conn_ctx, 1377 const char *hostname, unsigned short base_plpmtu, 1378 const unsigned char *sess_resume, size_t sess_resume_len, 1379 /** Resumption token: optional */ 1380 const unsigned char *token, size_t token_sz); 1381 1382/** 1383 * Pass incoming packet to the QUIC engine. This function can be called 1384 * more than once in a row. After you add one or more packets, call 1385 * lsquic_engine_process_conns() to schedule output, if any. 1386 * 1387 * @retval 0 Packet was processed by a real connection. 1388 * 1389 * @retval 1 Packet was handled successfully, but not by a connection. 1390 * This may happen with version negotiation and public reset 1391 * packets as well as some packets that may be ignored. 1392 * 1393 * @retval -1 An error occurred. Possible reasons are failure to allocate 1394 * memory and invalid @param sa_local in client mode. 1395 */ 1396int 1397lsquic_engine_packet_in (lsquic_engine_t *, 1398 const unsigned char *packet_in_data, size_t packet_in_size, 1399 const struct sockaddr *sa_local, const struct sockaddr *sa_peer, 1400 void *peer_ctx, int ecn); 1401 1402/** 1403 * Process tickable connections. This function must be called often enough so 1404 * that packets and connections do not expire. 1405 */ 1406void 1407lsquic_engine_process_conns (lsquic_engine_t *engine); 1408 1409/** 1410 * Returns true if engine has some unsent packets. This happens if 1411 * @ref ea_packets_out() could not send everything out or if processing 1412 * deadline was exceeded (see @ref es_proc_time_thresh). 1413 */ 1414int 1415lsquic_engine_has_unsent_packets (lsquic_engine_t *engine); 1416 1417/** 1418 * Send out as many unsent packets as possibe: until we are out of unsent 1419 * packets or until @ref ea_packets_out() fails. 1420 * 1421 * If @ref ea_packets_out() does fail cannot send all packets, this 1422 * function must be called to signify that sending of packets is possible 1423 * again. 1424 */ 1425void 1426lsquic_engine_send_unsent_packets (lsquic_engine_t *engine); 1427 1428/** 1429 * Destroy engine and all connections and streams in it and free all 1430 * memory associated with this engine. 1431 */ 1432void 1433lsquic_engine_destroy (lsquic_engine_t *); 1434 1435/** Return max allowed outbound streams less current outbound streams. */ 1436unsigned 1437lsquic_conn_n_avail_streams (const lsquic_conn_t *); 1438 1439/** 1440 * Create a new request stream. This causes @ref on_new_stream() callback 1441 * to be called. If creating more requests is not permitted at the moment 1442 * (due to number of concurrent streams limit), stream creation is registered 1443 * as "pending" and the stream is created later when number of streams dips 1444 * under the limit again. Any number of pending streams can be created. 1445 * Use @ref lsquic_conn_n_pending_streams() and 1446 * @ref lsquic_conn_cancel_pending_streams() to manage pending streams. 1447 * 1448 * If connection is going away, @ref on_new_stream() is called with the 1449 * stream parameter set to NULL. 1450 */ 1451void 1452lsquic_conn_make_stream (lsquic_conn_t *); 1453 1454/** Return number of delayed streams currently pending */ 1455unsigned 1456lsquic_conn_n_pending_streams (const lsquic_conn_t *); 1457 1458/** Cancel `n' pending streams. Returns new number of pending streams. */ 1459unsigned 1460lsquic_conn_cancel_pending_streams (lsquic_conn_t *, unsigned n); 1461 1462/** 1463 * Mark connection as going away: send GOAWAY frame and do not accept 1464 * any more incoming streams, nor generate streams of our own. 1465 * 1466 * Only applicable to HTTP/3 and GQUIC connections. Otherwise a no-op. 1467 */ 1468void 1469lsquic_conn_going_away (lsquic_conn_t *); 1470 1471/** 1472 * This forces connection close. on_conn_closed and on_close callbacks 1473 * will be called. 1474 */ 1475void 1476lsquic_conn_close (lsquic_conn_t *); 1477 1478/** 1479 * Set whether you want to read from stream. If @param is_want is true, 1480 * @ref on_read() will be called when there is readable data in the 1481 * stream. If @param is false, @ref on_read() will not be called. 1482 * 1483 * Returns previous value of this flag. 1484 */ 1485int 1486lsquic_stream_wantread (lsquic_stream_t *s, int is_want); 1487 1488/** 1489 * Read up to @param len bytes from stream into @param buf. Returns number 1490 * of bytes read or -1 on error, in which case errno is set. Possible 1491 * errno values: 1492 * 1493 * EBADF The stream is closed. 1494 * ECONNRESET The stream has been reset. 1495 * EWOULDBLOCK There is no data to be read. 1496 * 1497 * Return value of zero indicates EOF. 1498 */ 1499ssize_t 1500lsquic_stream_read (lsquic_stream_t *s, void *buf, size_t len); 1501 1502/** 1503 * Similar to @ref lsquic_stream_read(), but reads data into @param vec. 1504 */ 1505ssize_t 1506lsquic_stream_readv (lsquic_stream_t *s, const struct iovec *vec, int iovcnt); 1507 1508/** 1509 * This function allows user-supplied callback to read the stream contents. 1510 * It is meant to be used for zero-copy stream processing. 1511 * 1512 * Return value and errors are same as in @ref lsquic_stream_read(). 1513 */ 1514ssize_t 1515lsquic_stream_readf (lsquic_stream_t *s, 1516 /** 1517 * The callback takes four parameters: 1518 * - Pointer to user-supplied context; 1519 * - Pointer to the data; 1520 * - Data size (can be zero); and 1521 * - Indicator whether the FIN follows the data. 1522 * 1523 * The callback returns number of bytes processed. If this number is zero 1524 * or is smaller than `len', reading from stream stops. 1525 */ 1526 size_t (*readf)(void *ctx, const unsigned char *buf, size_t len, int fin), 1527 void *ctx); 1528 1529/** 1530 * Set whether you want to write to stream. If @param is_want is true, 1531 * @ref on_write() will be called when it is possible to write data to 1532 * the stream. If @param is false, @ref on_write() will not be called. 1533 * 1534 * Returns previous value of this flag. 1535 */ 1536int 1537lsquic_stream_wantwrite (lsquic_stream_t *s, int is_want); 1538 1539/** 1540 * Write `len' bytes to the stream. Returns number of bytes written, which 1541 * may be smaller that `len'. 1542 * 1543 * A negative return value indicates a serious error (the library is likely 1544 * to have aborted the connection because of it). 1545 */ 1546ssize_t 1547lsquic_stream_write (lsquic_stream_t *s, const void *buf, size_t len); 1548 1549/** 1550 * Like @ref lsquic_stream_write(), but read data from @param vec. 1551 */ 1552ssize_t 1553lsquic_stream_writev (lsquic_stream_t *s, const struct iovec *vec, int count); 1554 1555/** 1556 * Write to streams using a single call to a preadv-like function. 1557 */ 1558ssize_t 1559lsquic_stream_pwritev (lsquic_stream_t *s, 1560 ssize_t (*preadv)(void *user_data, const struct iovec *iov, int iovcnt), 1561 void *user_data, size_t n_to_write); 1562 1563/** 1564 * Used as argument to @ref lsquic_stream_writef() 1565 */ 1566struct lsquic_reader 1567{ 1568 /** 1569 * Not a ssize_t because the read function is not supposed to return 1570 * an error. If an error occurs in the read function (for example, when 1571 * reading from a file fails), it is supposed to deal with the error 1572 * itself. 1573 */ 1574 size_t (*lsqr_read) (void *lsqr_ctx, void *buf, size_t count); 1575 /** 1576 * Return number of bytes remaining in the reader. 1577 */ 1578 size_t (*lsqr_size) (void *lsqr_ctx); 1579 void *lsqr_ctx; 1580}; 1581 1582/** 1583 * Write to stream using @ref lsquic_reader. This is the most generic of 1584 * the write functions -- @ref lsquic_stream_write() and 1585 * @ref lsquic_stream_writev() utilize the same mechanism. 1586 * 1587 * @retval Number of bytes written or -1 on error. 1588 */ 1589ssize_t 1590lsquic_stream_writef (lsquic_stream_t *, struct lsquic_reader *); 1591 1592/** 1593 * Flush any buffered data. This triggers packetizing even a single byte 1594 * into a separate frame. Flushing a closed stream is an error. 1595 * 1596 * @retval 0 Success 1597 * @retval -1 Failure 1598 */ 1599int 1600lsquic_stream_flush (lsquic_stream_t *s); 1601 1602/** 1603 * @typedef lsquic_http_headers_t 1604 * @brief HTTP header list structure. Contains a list of HTTP headers in key/value pairs. 1605 * used in API functions to pass headers. 1606 */ 1607struct lsquic_http_headers 1608{ 1609 int count; 1610 struct lsxpack_header *headers; 1611}; 1612 1613/** 1614 * Send headers in @param headers. This function must be called before 1615 * writing to the stream. The value of @param eos is ignored in IETF QUIC. 1616 */ 1617int 1618lsquic_stream_send_headers (lsquic_stream_t *s, 1619 const lsquic_http_headers_t *headers, int eos); 1620 1621/** 1622 * Get header set associated with the stream. The header set is created by 1623 * @ref hsi_create_header_set() callback. After this call, the ownership of 1624 * the header set is transferred to the caller. 1625 * 1626 * This call must precede calls to @ref lsquic_stream_read() and 1627 * @ref lsquic_stream_readv(). 1628 * 1629 * If the optional header set interface (@ref ea_hsi_if) is not specified, 1630 * this function returns NULL. 1631 */ 1632void * 1633lsquic_stream_get_hset (lsquic_stream_t *); 1634 1635/** 1636 * A server may push a stream. This call creates a new stream in reference 1637 * to stream `s'. It will behave as if the client made a request: it will 1638 * trigger on_new_stream() event and it can be used as a regular client- 1639 * initiated stream. 1640 * 1641 * `hdr_set' must be set. It is passed as-is to @lsquic_stream_get_hset. 1642 * 1643 * @retval 0 Stream pushed successfully. 1644 * @retval 1 Stream push failed because it is disabled or because we hit 1645 * stream limit or connection is going away. 1646 * @retval -1 Stream push failed because of an internal error. 1647 */ 1648int 1649lsquic_conn_push_stream (lsquic_conn_t *c, void *hdr_set, lsquic_stream_t *s, 1650 const lsquic_http_headers_t *headers); 1651 1652/** 1653 * Only makes sense in server mode: the client cannot push a stream and this 1654 * function always returns false in client mode. 1655 */ 1656int 1657lsquic_conn_is_push_enabled (lsquic_conn_t *); 1658 1659/** Possible values for how are 0, 1, and 2. See shutdown(2). */ 1660int lsquic_stream_shutdown(lsquic_stream_t *s, int how); 1661 1662int lsquic_stream_close(lsquic_stream_t *s); 1663 1664/** 1665 * Return true if peer has not ACKed all data written to the stream. This 1666 * includes both packetized and buffered data. 1667 */ 1668int 1669lsquic_stream_has_unacked_data (lsquic_stream_t *s); 1670 1671/** 1672 * Get certificate chain returned by the server. This can be used for 1673 * server certificate verification. 1674 * 1675 * The caller releases the stack using sk_X509_free(). 1676 */ 1677struct stack_st_X509 * 1678lsquic_conn_get_server_cert_chain (lsquic_conn_t *); 1679 1680/** Returns ID of the stream */ 1681lsquic_stream_id_t 1682lsquic_stream_id (const lsquic_stream_t *s); 1683 1684/** 1685 * Returns stream ctx associated with the stream. (The context is what 1686 * is returned by @ref on_new_stream callback). 1687 */ 1688lsquic_stream_ctx_t * 1689lsquic_stream_get_ctx (const lsquic_stream_t *s); 1690 1691/** Returns true if this is a pushed stream */ 1692int 1693lsquic_stream_is_pushed (const lsquic_stream_t *s); 1694 1695/** 1696 * Returns true if this stream was rejected, false otherwise. Use this as 1697 * an aid to distinguish between errors. 1698 */ 1699int 1700lsquic_stream_is_rejected (const lsquic_stream_t *s); 1701 1702/** 1703 * Refuse pushed stream. Call it from @ref on_new_stream. 1704 * 1705 * No need to call lsquic_stream_close() after this. on_close will be called. 1706 * 1707 * @see lsquic_stream_is_pushed 1708 */ 1709int 1710lsquic_stream_refuse_push (lsquic_stream_t *s); 1711 1712/** 1713 * Get information associated with pushed stream: 1714 * 1715 * @param ref_stream_id Stream ID in response to which push promise was 1716 * sent. 1717 * @param hdr_set Header set. This object was passed to or generated 1718 * by @ref lsquic_conn_push_stream(). 1719 * 1720 * @retval 0 Success. 1721 * @retval -1 This is not a pushed stream. 1722 */ 1723int 1724lsquic_stream_push_info (const lsquic_stream_t *, 1725 lsquic_stream_id_t *ref_stream_id, void **hdr_set); 1726 1727/** Return current priority of the stream */ 1728unsigned lsquic_stream_priority (const lsquic_stream_t *s); 1729 1730/** 1731 * Set stream priority. Valid priority values are 1 through 256, inclusive. 1732 * Lower value means higher priority. 1733 * 1734 * @retval 0 Success. 1735 * @retval -1 Priority value is invalid. 1736 */ 1737int lsquic_stream_set_priority (lsquic_stream_t *s, unsigned priority); 1738 1739/* 1740 * Definitions for Extensible HTTP Priorities: 1741 * https://tools.ietf.org/html/draft-ietf-httpbis-priority-01 1742 */ 1743/* This is maximum *value* -- but it's the lowest *priority* */ 1744#define LSQUIC_MAX_HTTP_URGENCY 7 1745#define LSQUIC_DEF_HTTP_URGENCY 3 1746#define LSQUIC_DEF_HTTP_INCREMENTAL 0 1747 1748struct lsquic_ext_http_prio 1749{ 1750 unsigned char urgency; 1751 signed char incremental; 1752}; 1753 1754/** 1755 * Get Extensible HTTP Priorities associated with the stream. 1756 * 1757 * Returns zero on success of a negative value on failure. A failure occurs 1758 * if this is not an HTTP/3 stream or if Extensible HTTP Priorities haven't 1759 * been enabled. See @ref es_ext_http_prio. 1760 */ 1761int 1762lsquic_stream_get_http_prio (lsquic_stream_t *, struct lsquic_ext_http_prio *); 1763 1764/** 1765 * Set Extensible HTTP Priorities of the stream. 1766 * 1767 * Returns zero on success of a negative value on failure. A failure occurs 1768 * if some internal error occured or if this is not an HTTP/3 stream or if 1769 * Extensible HTTP Priorities haven't been enabled. See @ref es_ext_http_prio. 1770 */ 1771int 1772lsquic_stream_set_http_prio (lsquic_stream_t *, 1773 const struct lsquic_ext_http_prio *); 1774 1775/** 1776 * Get a pointer to the connection object. Use it with lsquic_conn_* 1777 * functions. 1778 */ 1779lsquic_conn_t * lsquic_stream_conn(const lsquic_stream_t *s); 1780 1781/** Get connection ID */ 1782const lsquic_cid_t * 1783lsquic_conn_id (const lsquic_conn_t *c); 1784 1785/** Get pointer to the engine */ 1786lsquic_engine_t * 1787lsquic_conn_get_engine (lsquic_conn_t *c); 1788 1789int 1790lsquic_conn_get_sockaddr(lsquic_conn_t *c, 1791 const struct sockaddr **local, const struct sockaddr **peer); 1792 1793/* Returns previous value */ 1794int 1795lsquic_conn_want_datagram_write (lsquic_conn_t *, int is_want); 1796 1797/* Get minimum datagram size. By default, this value is zero. */ 1798size_t 1799lsquic_conn_get_min_datagram_size (lsquic_conn_t *); 1800 1801/* Set minimum datagram size. This is the minumum value of the buffer passed 1802 * to the on_dg_write() callback. 1803 */ 1804int 1805lsquic_conn_set_min_datagram_size (lsquic_conn_t *, size_t sz); 1806 1807struct lsquic_logger_if { 1808 int (*log_buf)(void *logger_ctx, const char *buf, size_t len); 1809}; 1810 1811/** 1812 * Enumerate timestamp styles supported by LSQUIC logger mechanism. 1813 */ 1814enum lsquic_logger_timestamp_style { 1815 /** 1816 * No timestamp is generated. 1817 */ 1818 LLTS_NONE, 1819 1820 /** 1821 * The timestamp consists of 24 hours, minutes, seconds, and 1822 * milliseconds. Example: 13:43:46.671 1823 */ 1824 LLTS_HHMMSSMS, 1825 1826 /** 1827 * Like above, plus date, e.g: 2017-03-21 13:43:46.671 1828 */ 1829 LLTS_YYYYMMDD_HHMMSSMS, 1830 1831 /** 1832 * This is Chrome-like timestamp used by proto-quic. The timestamp 1833 * includes month, date, hours, minutes, seconds, and microseconds. 1834 * 1835 * Example: 1223/104613.946956 (instead of 12/23 10:46:13.946956). 1836 * 1837 * This is to facilitate reading two logs side-by-side. 1838 */ 1839 LLTS_CHROMELIKE, 1840 1841 /** 1842 * The timestamp consists of 24 hours, minutes, seconds, and 1843 * microseconds. Example: 13:43:46.671123 1844 */ 1845 LLTS_HHMMSSUS, 1846 1847 /** 1848 * Date and time using microsecond resolution, 1849 * e.g: 2017-03-21 13:43:46.671123 1850 */ 1851 LLTS_YYYYMMDD_HHMMSSUS, 1852 1853 N_LLTS 1854}; 1855 1856/** 1857 * Call this if you want to do something with LSQUIC log messages, as they 1858 * are thrown out by default. 1859 */ 1860void lsquic_logger_init(const struct lsquic_logger_if *, void *logger_ctx, 1861 enum lsquic_logger_timestamp_style); 1862 1863/** 1864 * Set log level for all LSQUIC modules. Acceptable values are debug, info, 1865 * notice, warning, error, alert, emerg, crit (case-insensitive). 1866 * 1867 * @retval 0 Success. 1868 * @retval -1 Failure: log_level is not valid. 1869 */ 1870int 1871lsquic_set_log_level (const char *log_level); 1872 1873/** 1874 * E.g. "event=debug" 1875 */ 1876int 1877lsquic_logger_lopt (const char *optarg); 1878 1879/** 1880 * Return the list of QUIC versions (as bitmask) this engine instance 1881 * supports. 1882 */ 1883unsigned lsquic_engine_quic_versions (const lsquic_engine_t *); 1884 1885/** 1886 * This is one of the flags that can be passed to @ref lsquic_global_init. 1887 * Use it to initialize LSQUIC for use in client mode. 1888 */ 1889#define LSQUIC_GLOBAL_CLIENT (1 << 0) 1890 1891/** 1892 * This is one of the flags that can be passed to @ref lsquic_global_init. 1893 * Use it to initialize LSQUIC for use in server mode. 1894 */ 1895#define LSQUIC_GLOBAL_SERVER (1 << 1) 1896 1897/** 1898 * Initialize LSQUIC. This must be called before any other LSQUIC function 1899 * is called. Returns 0 on success and -1 on failure. 1900 * 1901 * @param flags This a bitmask of @ref LSQUIC_GLOBAL_CLIENT and 1902 * @ref LSQUIC_GLOBAL_SERVER. At least one of these 1903 * flags should be specified. 1904 * 1905 * @retval 0 Success. 1906 * @retval -1 Initialization failed. 1907 * 1908 * @see LSQUIC_GLOBAL_CLIENT 1909 * @see LSQUIC_GLOBAL_SERVER 1910 */ 1911int 1912lsquic_global_init (int flags); 1913 1914/** 1915 * Clean up global state created by @ref lsquic_global_init. Should be 1916 * called after all LSQUIC engine instances are gone. 1917 */ 1918void 1919lsquic_global_cleanup (void); 1920 1921/** 1922 * Get QUIC version used by the connection. 1923 * 1924 * @see lsquic_version 1925 */ 1926enum lsquic_version 1927lsquic_conn_quic_version (const lsquic_conn_t *c); 1928 1929/* Return keysize or -1 on error */ 1930int 1931lsquic_conn_crypto_keysize (const lsquic_conn_t *c); 1932 1933/* Return algorithm keysize or -1 on error */ 1934int 1935lsquic_conn_crypto_alg_keysize (const lsquic_conn_t *c); 1936 1937enum lsquic_crypto_ver 1938{ 1939 LSQ_CRY_QUIC, 1940 LSQ_CRY_TLSv13, 1941}; 1942 1943enum lsquic_crypto_ver 1944lsquic_conn_crypto_ver (const lsquic_conn_t *c); 1945 1946/* Return cipher or NULL on error */ 1947const char * 1948lsquic_conn_crypto_cipher (const lsquic_conn_t *c); 1949 1950/** Translate string QUIC version to LSQUIC QUIC version representation */ 1951enum lsquic_version 1952lsquic_str2ver (const char *str, size_t len); 1953 1954/** Translate ALPN (e.g. "h3", "h3-23", "h3-Q046") to LSQUIC enum */ 1955enum lsquic_version 1956lsquic_alpn2ver (const char *alpn, size_t len); 1957 1958/** 1959 * This function closes all mini connections and marks all full connections 1960 * as going away. In server mode, this also causes the engine to stop 1961 * creating new connections. 1962 */ 1963void 1964lsquic_engine_cooldown (lsquic_engine_t *); 1965 1966/** 1967 * Get user-supplied context associated with the connection. 1968 */ 1969lsquic_conn_ctx_t * 1970lsquic_conn_get_ctx (const lsquic_conn_t *); 1971 1972/** 1973 * Set user-supplied context associated with the connection. 1974 */ 1975void 1976lsquic_conn_set_ctx (lsquic_conn_t *, lsquic_conn_ctx_t *); 1977 1978/** 1979 * Get peer context associated with the connection. 1980 */ 1981void * 1982lsquic_conn_get_peer_ctx (lsquic_conn_t *, const struct sockaddr *local_sa); 1983 1984/** 1985 * Abort connection. 1986 */ 1987void 1988lsquic_conn_abort (lsquic_conn_t *); 1989 1990/** 1991 * Helper function: convert list of versions as specified in the argument 1992 * bitmask to string that can be included as argument to "v=" part of the 1993 * Alt-Svc header. 1994 * 1995 * For example (1<<LSQVER_037)|(1<<LSQVER_038) => "37,38" 1996 * 1997 * This is only applicable to Google QUIC versions. 1998 */ 1999const char * 2000lsquic_get_alt_svc_versions (unsigned versions); 2001 2002/** 2003 * Return a NULL-terminated list of HTTP/3 ALPNs, e.g "h3-17", "h3-18", "h3". 2004 */ 2005const char *const * 2006lsquic_get_h3_alpns (unsigned versions); 2007 2008/** 2009 * Returns true if provided buffer could be a valid handshake-stage packet, 2010 * false otherwise. Do not call this function if a connection has already 2011 * been established: it will return incorrect result. 2012 */ 2013int 2014lsquic_is_valid_hs_packet (lsquic_engine_t *, const unsigned char *, size_t); 2015 2016/** 2017 * Parse cid from packet stored in `buf' and store it to `cid'. Returns 0 2018 * on success and -1 on failure. 2019 */ 2020int 2021lsquic_cid_from_packet (const unsigned char *, size_t bufsz, lsquic_cid_t *cid); 2022 2023/** 2024 * Returns true if there are connections to be processed, false otherwise. 2025 * If true, `diff' is set to the difference between the earliest advisory 2026 * tick time and now. If the former is in the past, the value of `diff' 2027 * is negative. 2028 */ 2029int 2030lsquic_engine_earliest_adv_tick (lsquic_engine_t *engine, int *diff); 2031 2032/** 2033 * Return number of connections whose advisory tick time is before current 2034 * time plus `from_now' microseconds from now. `from_now' can be negative. 2035 */ 2036unsigned 2037lsquic_engine_count_attq (lsquic_engine_t *engine, int from_now); 2038 2039enum LSQUIC_CONN_STATUS 2040{ 2041 LSCONN_ST_HSK_IN_PROGRESS, 2042 LSCONN_ST_CONNECTED, 2043 LSCONN_ST_HSK_FAILURE, 2044 LSCONN_ST_GOING_AWAY, 2045 LSCONN_ST_TIMED_OUT, 2046 /* If es_honor_prst is not set, the connection will never get public 2047 * reset packets and this flag will not be set. 2048 */ 2049 LSCONN_ST_RESET, 2050 LSCONN_ST_USER_ABORTED, 2051 LSCONN_ST_ERROR, 2052 LSCONN_ST_CLOSED, 2053 LSCONN_ST_PEER_GOING_AWAY, 2054}; 2055 2056enum LSQUIC_CONN_STATUS 2057lsquic_conn_status (lsquic_conn_t *, char *errbuf, size_t bufsz); 2058 2059extern const char *const 2060lsquic_ver2str[N_LSQVER]; 2061 2062#ifdef __cplusplus 2063} 2064#endif 2065 2066#endif //__LSQUIC_H__ 2067 2068