lsquic.h revision 1bdb91d1
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 10 28#define LSQUIC_PATCH_VERSION 5 29 30/** 31 * Engine flags: 32 */ 33 34/** Server mode */ 35#define LSENG_SERVER (1 << 0) 36 37/** Treat stream 3 as headers stream and, in general, behave like the 38 * regular QUIC. 39 */ 40#define LSENG_HTTP (1 << 1) 41 42#define LSENG_HTTP_SERVER (LSENG_SERVER|LSENG_HTTP) 43 44/** 45 * This is a list of QUIC versions that we know of. List of supported 46 * versions is in LSQUIC_SUPPORTED_VERSIONS. 47 */ 48enum lsquic_version 49{ 50 51 /** Q035. This is the first version to be supported by LSQUIC. */ 52 /* Support for this version has been removed. The comment remains to 53 * document the changes. 54 */ 55 56 /* 57 * Q037. This version is like Q035, except the way packet hashes are 58 * generated is different for clients and servers. In addition, new 59 * option NSTP (no STOP_WAITING frames) is rumored to be supported at 60 * some point in the future. 61 */ 62 /* Support for this version has been removed. The comment remains to 63 * document the changes. 64 */ 65 66 /* 67 * Q038. Based on Q037, supports PADDING frames in the middle of packet 68 * and NSTP (no STOP_WAITING frames) option. 69 */ 70 /* Support for this version has been removed. The comment remains to 71 * document the changes. 72 */ 73 74 /** 75 * Q039. Switch to big endian. Do not ack acks. Send connection level 76 * WINDOW_UPDATE frame every 20 sent packets which do not contain 77 * retransmittable frames. 78 */ 79 /* Support for this version has been removed. The comment remains to 80 * document the changes. 81 */ 82 83 /* 84 * Q041. RST_STREAM, ACK and STREAM frames match IETF format. 85 */ 86 /* Support for this version has been removed. The comment remains to 87 * document the changes. 88 */ 89 90 /* 91 * Q042. Receiving overlapping stream data is allowed. 92 */ 93 /* Support for this version has been removed. The comment remains to 94 * document the changes. 95 */ 96 97 /** 98 * Q043. Support for processing PRIORITY frames. Since this library 99 * has supported PRIORITY frames from the beginning, this version is 100 * exactly the same as LSQVER_042. 101 */ 102 LSQVER_043, 103 104 /** 105 * Q044. IETF-like packet headers are used. Frames are the same as 106 * in Q043. Server never includes CIDs in short packets. 107 */ 108 /* Support for this version has been removed. The comment remains to 109 * document the changes. 110 */ 111 112 /** 113 * Q046. Use IETF Draft-17 compatible packet headers. 114 */ 115 LSQVER_046, 116 117 /** 118 * Q050. Variable-length QUIC server connection IDs. Use CRYPTO frames 119 * for handshake. IETF header format matching invariants-06. Packet 120 * number encryption. Initial packets are obfuscated. 121 */ 122 LSQVER_050, 123 124#if LSQUIC_USE_Q098 125 /** 126 * Q098. This is a made-up, experimental version used to test version 127 * negotiation. The choice of 98 is similar to Google's choice of 99 128 * as the "IETF" version. 129 */ 130 LSQVER_098, 131#define LSQUIC_EXPERIMENTAL_Q098 (1 << LSQVER_098) 132#else 133#define LSQUIC_EXPERIMENTAL_Q098 0 134#endif 135 136 /** 137 * IETF QUIC Draft-24 138 */ 139 LSQVER_ID24, 140 141 /** 142 * IETF QUIC Draft-25 143 */ 144 LSQVER_ID25, 145 146 /** 147 * Special version to trigger version negotiation. 148 * [draft-ietf-quic-transport-11], Section 3. 149 */ 150 LSQVER_VERNEG, 151 152 N_LSQVER 153}; 154 155/** 156 * We currently support versions 43, 46, 50, and Draft-24 157 * @see lsquic_version 158 */ 159#define LSQUIC_SUPPORTED_VERSIONS ((1 << N_LSQVER) - 1) 160 161/** 162 * List of versions in which the server never includes CID in short packets. 163 */ 164#define LSQUIC_FORCED_TCID0_VERSIONS ((1 << LSQVER_046)|(1 << LSQVER_050)) 165 166#define LSQUIC_EXPERIMENTAL_VERSIONS ( \ 167 (1 << LSQVER_VERNEG) | LSQUIC_EXPERIMENTAL_Q098) 168 169#define LSQUIC_DEPRECATED_VERSIONS 0 170 171#define LSQUIC_GQUIC_HEADER_VERSIONS (1 << LSQVER_043) 172 173#define LSQUIC_IETF_VERSIONS ((1 << LSQVER_ID24) | (1 << LSQVER_ID25) \ 174 | (1 << LSQVER_VERNEG)) 175 176#define LSQUIC_IETF_DRAFT_VERSIONS ((1 << LSQVER_ID24) | (1 << LSQVER_ID25) \ 177 | (1 << LSQVER_VERNEG)) 178 179enum lsquic_hsk_status 180{ 181 /** 182 * The handshake failed. 183 */ 184 LSQ_HSK_FAIL, 185 /** 186 * The handshake succeeded without 0-RTT. 187 */ 188 LSQ_HSK_OK, 189 /** 190 * The handshake succeeded with 0-RTT. 191 */ 192 LSQ_HSK_0RTT_OK, 193 /** 194 * The handshake failed because of 0-RTT (early data rejected). Retry 195 * the connection without 0-RTT. 196 */ 197 LSQ_HSK_0RTT_FAIL, 198}; 199 200/** 201 * @struct lsquic_stream_if 202 * @brief The definition of callback functions call by lsquic_stream to 203 * process events. 204 * 205 */ 206struct lsquic_stream_if { 207 208 /** 209 * Use @ref lsquic_conn_get_ctx to get back the context. It is 210 * OK for this function to return NULL. 211 */ 212 lsquic_conn_ctx_t *(*on_new_conn)(void *stream_if_ctx, 213 lsquic_conn_t *c); 214 215 /** This is called when our side received GOAWAY frame. After this, 216 * new streams should not be created. The callback is optional. 217 */ 218 void (*on_goaway_received)(lsquic_conn_t *c); 219 void (*on_conn_closed)(lsquic_conn_t *c); 220 221 /** If you need to initiate a connection, call lsquic_conn_make_stream(). 222 * This will cause `on_new_stream' callback to be called when appropriate 223 * (this operation is delayed when maximum number of outgoing streams is 224 * reached). 225 * 226 * After `on_close' is called, the stream is no longer accessible. 227 */ 228 lsquic_stream_ctx_t * 229 (*on_new_stream)(void *stream_if_ctx, lsquic_stream_t *s); 230 231 void (*on_read) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 232 void (*on_write) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 233 void (*on_close) (lsquic_stream_t *s, lsquic_stream_ctx_t *h); 234 /* This callback in only called in client mode */ 235 /** 236 * When handshake is completed, this callback is called. `ok' is set 237 * to true if handshake was successful; otherwise, `ok' is set to 238 * false. 239 * 240 * This callback is optional. 241 */ 242 void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s); 243 /** 244 * When server sends a token in NEW_TOKEN frame, this callback is called. 245 * The callback is optional. 246 */ 247 void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token, 248 size_t token_size); 249 /** 250 * This optional callback lets client record information needed to 251 * perform a zero-RTT handshake next time around. 252 */ 253 void (*on_zero_rtt_info)(lsquic_conn_t *c, const unsigned char *, size_t); 254}; 255 256struct ssl_ctx_st; 257struct ssl_st; 258 259/** 260 * QUIC engine in server role needs access to certificates. This is 261 * accomplished by providing a callback and a context to the engine 262 * constructor. 263 */ 264 265typedef struct ssl_ctx_st * (*lsquic_lookup_cert_f)( 266 void *lsquic_cert_lookup_ctx, const struct sockaddr *local, const char *sni); 267 268/** 269 * Minimum flow control window is set to 16 KB for both client and server. 270 * This means we can send up to this amount of data before handshake gets 271 * completed. 272 */ 273#define LSQUIC_MIN_FCW (16 * 1024) 274 275/* Each LSQUIC_DF_* value corresponds to es_* entry in 276 * lsquic_engine_settings below. 277 */ 278 279/** 280 * By default, deprecated and experimental versions are not included. 281 */ 282#define LSQUIC_DF_VERSIONS (LSQUIC_SUPPORTED_VERSIONS & \ 283 ~LSQUIC_DEPRECATED_VERSIONS & \ 284 ~LSQUIC_EXPERIMENTAL_VERSIONS) 285 286#define LSQUIC_DF_CFCW_SERVER (3 * 1024 * 1024 / 2) 287#define LSQUIC_DF_CFCW_CLIENT (15 * 1024 * 1024) 288#define LSQUIC_DF_SFCW_SERVER (1 * 1024 * 1024) 289#define LSQUIC_DF_SFCW_CLIENT (6 * 1024 * 1024) 290#define LSQUIC_DF_MAX_STREAMS_IN 100 291 292/* IQUIC uses different names for these: */ 293#define LSQUIC_DF_INIT_MAX_DATA_SERVER LSQUIC_DF_CFCW_SERVER 294#define LSQUIC_DF_INIT_MAX_DATA_CLIENT LSQUIC_DF_CFCW_CLIENT 295#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER LSQUIC_DF_SFCW_SERVER 296#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER 0 297#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT 0 298#define LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT LSQUIC_DF_SFCW_CLIENT 299#define LSQUIC_DF_INIT_MAX_STREAMS_BIDI LSQUIC_DF_MAX_STREAMS_IN 300#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT 100 301#define LSQUIC_DF_INIT_MAX_STREAMS_UNI_SERVER 3 302/* XXX What's a good value here? */ 303#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT (32 * 1024) 304#define LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER (12 * 1024) 305 306/** 307 * Default idle connection time in seconds. 308 */ 309#define LSQUIC_DF_IDLE_TIMEOUT 30 310 311/** 312 * Default ping period in seconds. 313 */ 314#define LSQUIC_DF_PING_PERIOD 15 315 316/** 317 * Default handshake timeout in microseconds. 318 */ 319#define LSQUIC_DF_HANDSHAKE_TO (10 * 1000 * 1000) 320 321#define LSQUIC_DF_IDLE_CONN_TO (LSQUIC_DF_IDLE_TIMEOUT * 1000 * 1000) 322#define LSQUIC_DF_SILENT_CLOSE 1 323 324/** Default value of maximum header list size. If set to non-zero value, 325 * SETTINGS_MAX_HEADER_LIST_SIZE will be sent to peer after handshake is 326 * completed (assuming the peer supports this setting frame type). 327 */ 328#define LSQUIC_DF_MAX_HEADER_LIST_SIZE 0 329 330/** Default value of UAID (user-agent ID). */ 331#define LSQUIC_DF_UA "LSQUIC" 332 333#define LSQUIC_DF_STTL 86400 334#define LSQUIC_DF_MAX_INCHOATE (1 * 1000 * 1000) 335/** Do not use NSTP by default */ 336#define LSQUIC_DF_SUPPORT_NSTP 0 337/** TODO: IETF QUIC clients do not support push */ 338#define LSQUIC_DF_SUPPORT_PUSH 1 339#define LSQUIC_DF_SUPPORT_TCID0 1 340/** By default, LSQUIC ignores Public Reset packets. */ 341#define LSQUIC_DF_HONOR_PRST 0 342 343/** 344 * By default, LSQUIC will not send Public Reset packets in response to 345 * packets that specify unknown connections. 346 */ 347#define LSQUIC_DF_SEND_PRST 0 348 349/** By default, infinite loop checks are turned on */ 350#define LSQUIC_DF_PROGRESS_CHECK 1000 351 352/** By default, read/write events are dispatched in a loop */ 353#define LSQUIC_DF_RW_ONCE 0 354 355/** By default, the threshold is not enabled */ 356#define LSQUIC_DF_PROC_TIME_THRESH 0 357 358/** By default, packets are paced */ 359#define LSQUIC_DF_PACE_PACKETS 1 360 361/** Default clock granularity is 1000 microseconds */ 362#define LSQUIC_DF_CLOCK_GRANULARITY 1000 363 364/** The default value is 8 for simplicity */ 365#define LSQUIC_DF_SCID_LEN 8 366 367/** The default value is 60 CIDs per minute */ 368#define LSQUIC_DF_SCID_ISS_RATE 60 369 370#define LSQUIC_DF_QPACK_DEC_MAX_BLOCKED 100 371#define LSQUIC_DF_QPACK_DEC_MAX_SIZE 4096 372#define LSQUIC_DF_QPACK_ENC_MAX_BLOCKED 100 373#define LSQUIC_DF_QPACK_ENC_MAX_SIZE 4096 374 375/** ECN is disabled by default */ 376#define LSQUIC_DF_ECN 0 377 378/** Allow migration by default */ 379#define LSQUIC_DF_ALLOW_MIGRATION 1 380 381/** Use QL loss bits by default */ 382#define LSQUIC_DF_QL_BITS 2 383 384/** Turn spin bit on by default */ 385#define LSQUIC_DF_SPIN 1 386 387/* 1: Cubic; 2: BBR */ 388#define LSQUIC_DF_CC_ALGO 1 389 390struct lsquic_engine_settings { 391 /** 392 * This is a bit mask wherein each bit corresponds to a value in 393 * enum lsquic_version. Client starts negotiating with the highest 394 * version and goes down. Server supports either of the versions 395 * specified here. 396 * 397 * This setting applies to both Google and IETF QUIC. 398 * 399 * @see lsquic_version 400 */ 401 unsigned es_versions; 402 403 /** 404 * Initial default CFCW. 405 * 406 * In server mode, per-connection values may be set lower than 407 * this if resources are scarce. 408 * 409 * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW. 410 * 411 * @see es_max_cfcw 412 */ 413 unsigned es_cfcw; 414 415 /** 416 * Initial default SFCW. 417 * 418 * In server mode, per-connection values may be set lower than 419 * this if resources are scarce. 420 * 421 * Do not set es_cfcw and es_sfcw lower than @ref LSQUIC_MIN_FCW. 422 * 423 * @see es_max_sfcw 424 */ 425 unsigned es_sfcw; 426 427 /** 428 * This value is used to specify maximum allowed value CFCW is allowed 429 * to reach due to window auto-tuning. By default, this value is zero, 430 * which means that CFCW is not allowed to increase from its initial 431 * value. 432 * 433 * @see es_cfcw 434 */ 435 unsigned es_max_cfcw; 436 437 unsigned es_max_sfcw; 438 439 /** MIDS */ 440 unsigned es_max_streams_in; 441 442 /** 443 * Handshake timeout in microseconds. 444 * 445 * For client, this can be set to an arbitrary value (zero turns the 446 * timeout off). 447 * 448 * For server, this value is limited to about 16 seconds. Do not set 449 * it to zero. 450 */ 451 unsigned long es_handshake_to; 452 453 /** ICSL in microseconds; GQUIC only */ 454 unsigned long es_idle_conn_to; 455 456 /** SCLS (silent close) */ 457 int es_silent_close; 458 459 /** 460 * This corresponds to SETTINGS_MAX_HEADER_LIST_SIZE 461 * (RFC 7540, Section 6.5.2). 0 means no limit. Defaults 462 * to @ref LSQUIC_DF_MAX_HEADER_LIST_SIZE. 463 */ 464 unsigned es_max_header_list_size; 465 466 /** UAID -- User-Agent ID. Defaults to @ref LSQUIC_DF_UA. */ 467 const char *es_ua; 468 469 /** 470 * More parameters for server 471 */ 472 uint64_t es_sttl; /* SCFG TTL in seconds */ 473 474 uint32_t es_pdmd; /* One fixed value X509 */ 475 uint32_t es_aead; /* One fixed value AESG */ 476 uint32_t es_kexs; /* One fixed value C255 */ 477 478 /* Maximum number of incoming connections in inchoate state. This is 479 * only applicable in server mode. 480 */ 481 unsigned es_max_inchoate; 482 483 /** 484 * Setting this value to 0 means that 485 * 486 * For client: 487 * a) we send a SETTINGS frame to indicate that we do not support server 488 * push; and 489 * b) All incoming pushed streams get reset immediately. 490 * (For maximum effect, set es_max_streams_in to 0.) 491 * 492 * For server: 493 * lsquic_conn_push_stream() will return -1. 494 */ 495 int es_support_push; 496 497 /** 498 * If set to true value, the server will not include connection ID in 499 * outgoing packets if client's CHLO specifies TCID=0. 500 * 501 * For client, this means including TCID=0 into CHLO message. Note that 502 * in this case, the engine tracks connections by the 503 * (source-addr, dest-addr) tuple, thereby making it necessary to create 504 * a socket for each connection. 505 * 506 * This option has no effect in Q046, as the server never includes 507 * CIDs in the short packets. 508 * 509 * The default is @ref LSQUIC_DF_SUPPORT_TCID0. 510 */ 511 int es_support_tcid0; 512 513 /** 514 * Q037 and higher support "No STOP_WAITING frame" mode. When set, the 515 * client will send NSTP option in its Client Hello message and will not 516 * sent STOP_WAITING frames, while ignoring incoming STOP_WAITING frames, 517 * if any. Note that if the version negotiation happens to downgrade the 518 * client below Q037, this mode will *not* be used. 519 * 520 * This option does not affect the server, as it must support NSTP mode 521 * if it was specified by the client. 522 */ 523 int es_support_nstp; 524 525 /** 526 * If set to true value, the library will drop connections when it 527 * receives corresponding Public Reset packet. The default is to 528 * ignore these packets. 529 */ 530 int es_honor_prst; 531 532 /** 533 * If set to true value, the library will send Public Reset packets 534 * in response to incoming packets with unknown Connection IDs. 535 * The default is @ref LSQUIC_DF_SEND_PRST. 536 */ 537 int es_send_prst; 538 539 /** 540 * A non-zero value enables internal checks that identify suspected 541 * infinite loops in user @ref on_read and @ref on_write callbacks 542 * and break them. An infinite loop may occur if user code keeps 543 * on performing the same operation without checking status, e.g. 544 * reading from a closed stream etc. 545 * 546 * The value of this parameter is as follows: should a callback return 547 * this number of times in a row without making progress (that is, 548 * reading, writing, or changing stream state), loop break will occur. 549 * 550 * The defaut value is @ref LSQUIC_DF_PROGRESS_CHECK. 551 */ 552 unsigned es_progress_check; 553 554 /** 555 * A non-zero value make stream dispatch its read-write events once 556 * per call. 557 * 558 * When zero, read and write events are dispatched until the stream 559 * is no longer readable or writeable, respectively, or until the 560 * user signals unwillingness to read or write using 561 * @ref lsquic_stream_wantread() or @ref lsquic_stream_wantwrite() 562 * or shuts down the stream. 563 * 564 * The default value is @ref LSQUIC_DF_RW_ONCE. 565 */ 566 int es_rw_once; 567 568 /** 569 * If set, this value specifies that number of microseconds that 570 * @ref lsquic_engine_process_conns() and 571 * @ref lsquic_engine_send_unsent_packets() are allowed to spend 572 * before returning. 573 * 574 * This is not an exact science and the connections must make 575 * progress, so the deadline is checked after all connections get 576 * a chance to tick (in the case of @ref lsquic_engine_process_conns()) 577 * and at least one batch of packets is sent out. 578 * 579 * When processing function runs out of its time slice, immediate 580 * calls to @ref lsquic_engine_has_unsent_packets() return false. 581 * 582 * The default value is @ref LSQUIC_DF_PROC_TIME_THRESH. 583 */ 584 unsigned es_proc_time_thresh; 585 586 /** 587 * If set to true, packet pacing is implemented per connection. 588 * 589 * The default value is @ref LSQUIC_DF_PACE_PACKETS. 590 */ 591 int es_pace_packets; 592 593 /** 594 * Clock granularity information is used by the pacer. The value 595 * is in microseconds; default is @ref LSQUIC_DF_CLOCK_GRANULARITY. 596 */ 597 unsigned es_clock_granularity; 598 599 /* The following settings are specific to IETF QUIC. */ 600 /* vvvvvvvvvvv */ 601 602 /** 603 * Initial max data. 604 * 605 * This is a transport parameter. 606 * 607 * Depending on the engine mode, the default value is either 608 * @ref LSQUIC_DF_INIT_MAX_DATA_CLIENT or 609 * @ref LSQUIC_DF_INIT_MAX_DATA_SERVER. 610 */ 611 unsigned es_init_max_data; 612 613 /** 614 * Initial max stream data. 615 * 616 * This is a transport parameter. 617 * 618 * Depending on the engine mode, the default value is either 619 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_CLIENT or 620 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER. 621 */ 622 unsigned es_init_max_stream_data_bidi_remote; 623 unsigned es_init_max_stream_data_bidi_local; 624 625 /** 626 * Initial max stream data for unidirectional streams initiated 627 * by remote endpoint. 628 * 629 * This is a transport parameter. 630 * 631 * Depending on the engine mode, the default value is either 632 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT or 633 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER. 634 */ 635 unsigned es_init_max_stream_data_uni; 636 637 /** 638 * Maximum initial number of bidirectional stream. 639 * 640 * This is a transport parameter. 641 * 642 * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_BIDI. 643 */ 644 unsigned es_init_max_streams_bidi; 645 646 /** 647 * Maximum initial number of unidirectional stream. 648 * 649 * This is a transport parameter. 650 * 651 * Default value is @ref LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT or 652 * @ref LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER. 653 */ 654 unsigned es_init_max_streams_uni; 655 656 /** 657 * Idle connection timeout. 658 * 659 * This is a transport parameter. 660 * 661 * (Note: es_idle_conn_to is not reused because it is in microseconds, 662 * which, I now realize, was not a good choice. Since it will be 663 * obsoleted some time after the switchover to IETF QUIC, we do not 664 * have to keep on using strange units.) 665 * 666 * Default value is @ref LSQUIC_DF_IDLE_TIMEOUT. 667 * 668 * Maximum value is 600 seconds. 669 */ 670 unsigned es_idle_timeout; 671 672 /** 673 * Ping period. If set to non-zero value, the connection will generate and 674 * send PING frames in the absence of other activity. 675 * 676 * By default, the server does not send PINGs and the period is set to zero. 677 * The client's defaut value is @ref LSQUIC_DF_PING_PERIOD. 678 */ 679 unsigned es_ping_period; 680 681 /** 682 * Source Connection ID length. Only applicable to the IETF QUIC 683 * versions. Valid values are 0 through 20, inclusive. 684 * 685 * Default value is @ref LSQUIC_DF_SCID_LEN. 686 */ 687 unsigned es_scid_len; 688 689 /** 690 * Source Connection ID issuance rate. Only applicable to the IETF QUIC 691 * versions. This field is measured in CIDs per minute. Using value 0 692 * indicates that there is no rate limit for CID issuance. 693 * 694 * Default value is @ref LSQUIC_DF_SCID_ISS_RATE. 695 */ 696 unsigned es_scid_iss_rate; 697 698 /** 699 * Maximum size of the QPACK dynamic table that the QPACK decoder will 700 * use. 701 * 702 * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_SIZE. 703 */ 704 unsigned es_qpack_dec_max_size; 705 706 /** 707 * Maximum number of blocked streams that the QPACK decoder is willing 708 * to tolerate. 709 * 710 * The default is @ref LSQUIC_DF_QPACK_DEC_MAX_BLOCKED. 711 */ 712 unsigned es_qpack_dec_max_blocked; 713 714 /** 715 * Maximum size of the dynamic table that the encoder is willing to use. 716 * The actual size of the dynamic table will not exceed the minimum of 717 * this value and the value advertized by peer. 718 * 719 * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_SIZE. 720 */ 721 unsigned es_qpack_enc_max_size; 722 723 /** 724 * Maximum number of blocked streams that the QPACK encoder is willing 725 * to risk. The actual number of blocked streams will not exceed the 726 * minimum of this value and the value advertized by peer. 727 * 728 * The default is @ref LSQUIC_DF_QPACK_ENC_MAX_BLOCKED. 729 */ 730 unsigned es_qpack_enc_max_blocked; 731 732 /** 733 * Enable ECN support. 734 * 735 * The default is @ref LSQUIC_DF_ECN 736 */ 737 int es_ecn; 738 739 /** 740 * Allow peer to migrate connection. 741 * 742 * The default is @ref LSQUIC_DF_ALLOW_MIGRATION 743 */ 744 int es_allow_migration; 745 746 /** 747 * Congestion control algorithm to use. 748 * 749 * 0: Use default (@ref LSQUIC_DF_CC_ALGO) 750 * 1: Cubic 751 * 2: BBR 752 */ 753 unsigned es_cc_algo; 754 755 /** 756 * Use QL loss bits. Allowed values are: 757 * 0: Do not use loss bits 758 * 1: Allow loss bits 759 * 2: Allow and send loss bits 760 * 761 * Default value is @ref LSQUIC_DF_QL_BITS 762 */ 763 int es_ql_bits; 764 765 /** 766 * Enable spin bit. Allowed values are 0 and 1. 767 * 768 * Default value is @ref LSQUIC_DF_SPIN 769 */ 770 int es_spin; 771}; 772 773/* Initialize `settings' to default values */ 774void 775lsquic_engine_init_settings (struct lsquic_engine_settings *, 776 unsigned lsquic_engine_flags); 777 778/** 779 * Check settings for errors. 780 * 781 * @param settings Settings struct. 782 * 783 * @param flags Engine flags. 784 * 785 * @param err_buf Optional pointer to buffer into which error string 786 * is written. 787 788 * @param err_buf_sz Size of err_buf. No more than this number of bytes 789 * will be written to err_buf, including the NUL byte. 790 * 791 * @retval 0 Settings have no errors. 792 * @retval -1 There are errors in settings. 793 */ 794int 795lsquic_engine_check_settings (const struct lsquic_engine_settings *settings, 796 unsigned lsquic_engine_flags, 797 char *err_buf, size_t err_buf_sz); 798 799struct lsquic_out_spec 800{ 801 struct iovec *iov; 802 size_t iovlen; 803 const struct sockaddr *local_sa; 804 const struct sockaddr *dest_sa; 805 void *peer_ctx; 806 int ecn; /* Valid values are 0 - 3. See RFC 3168 */ 807}; 808 809/** 810 * Returns number of packets successfully sent out or -1 on error. -1 should 811 * only be returned if no packets were sent out. If -1 is returned or if the 812 * return value is smaller than `n_packets_out', this indicates that sending 813 * of packets is not possible. 814 * 815 * If not all packets could be sent out, errno is examined. If it is not 816 * EAGAIN or EWOULDBLOCK, the connection whose packet cause the error is 817 * closed forthwith. 818 * 819 * No packets will be attempted to be sent out until 820 * @ref lsquic_engine_send_unsent_packets() is called. 821 */ 822typedef int (*lsquic_packets_out_f)( 823 void *packets_out_ctx, 824 const struct lsquic_out_spec *out_spec, 825 unsigned n_packets_out 826); 827 828/** 829 * The shared hash interface is used to share data between multiple LSQUIC 830 * instances. 831 */ 832struct lsquic_shared_hash_if 833{ 834 /** 835 * If you want your item to never expire, set `expiry' to zero. 836 * Returns 0 on success, -1 on failure. 837 * 838 * If inserted successfully, `free()' will be called on `data' and 'key' 839 * pointer when the element is deleted, whether due to expiration 840 * or explicit deletion. 841 */ 842 int (*shi_insert)(void *shi_ctx, void *key, unsigned key_sz, 843 void *data, unsigned data_sz, time_t expiry); 844 /** 845 * Returns 0 on success, -1 on failure. 846 */ 847 int (*shi_delete)(void *shi_ctx, const void *key, unsigned key_sz); 848 849 /** 850 * `data' is pointed to the result and `data_sz' is set to the 851 * object size. The implementation may choose to copy the object 852 * into buffer pointed to by `data', so you should have it ready. 853 * 854 * @retval 1 found. 855 * @retval 0 not found. 856 * @retval -1 error (perhaps not enough room in `data' if copy was 857 * attempted). 858 */ 859 int (*shi_lookup)(void *shi_ctx, const void *key, unsigned key_sz, 860 void **data, unsigned *data_sz); 861}; 862 863/** 864 * The packet out memory interface is used by LSQUIC to get buffers to 865 * which outgoing packets will be written before they are passed to 866 * ea_packets_out callback. 867 * 868 * If not specified, malloc() and free() are used. 869 */ 870struct lsquic_packout_mem_if 871{ 872 /** 873 * Allocate buffer for sending. 874 */ 875 void * (*pmi_allocate) (void *pmi_ctx, void *conn_ctx, unsigned short sz, 876 char is_ipv6); 877 /** 878 * This function is used to release the allocated buffer after it is 879 * sent via @ref ea_packets_out. 880 */ 881 void (*pmi_release) (void *pmi_ctx, void *conn_ctx, void *buf, 882 char is_ipv6); 883 /** 884 * If allocated buffer is not going to be sent, return it to the caller 885 * using this function. 886 */ 887 void (*pmi_return) (void *pmi_ctx, void *conn_ctx, void *buf, 888 char is_ipv6); 889}; 890 891typedef void (*lsquic_cids_update_f)(void *ctx, void **peer_ctx, 892 const lsquic_cid_t *cids, unsigned n_cids); 893 894struct stack_st_X509; 895 896/** 897 * When headers are processed, various errors may occur. They are listed 898 * in this enum. 899 */ 900enum lsquic_header_status 901{ 902 LSQUIC_HDR_OK, 903 /** Duplicate pseudo-header */ 904 LSQUIC_HDR_ERR_DUPLICATE_PSDO_HDR, 905 /** Not all request pseudo-headers are present */ 906 LSQUIC_HDR_ERR_INCOMPL_REQ_PSDO_HDR, 907 /** Unnecessary request pseudo-header present in the response */ 908 LSQUIC_HDR_ERR_UNNEC_REQ_PSDO_HDR, 909 /** Prohibited header in request */ 910 LSQUIC_HDR_ERR_BAD_REQ_HEADER, 911 /** Not all response pseudo-headers are present */ 912 LSQUIC_HDR_ERR_INCOMPL_RESP_PSDO_HDR, 913 /** Unnecessary response pseudo-header present in the response. */ 914 LSQUIC_HDR_ERR_UNNEC_RESP_PSDO_HDR, 915 /** Unknown pseudo-header */ 916 LSQUIC_HDR_ERR_UNKNOWN_PSDO_HDR, 917 /** Uppercase letter in header */ 918 LSQUIC_HDR_ERR_UPPERCASE_HEADER, 919 /** Misplaced pseudo-header */ 920 LSQUIC_HDR_ERR_MISPLACED_PSDO_HDR, 921 /** Missing pseudo-header */ 922 LSQUIC_HDR_ERR_MISSING_PSDO_HDR, 923 /** Header or headers are too large */ 924 LSQUIC_HDR_ERR_HEADERS_TOO_LARGE, 925 /** Cannot allocate any more memory. */ 926 LSQUIC_HDR_ERR_NOMEM, 927}; 928 929struct lsquic_hset_if 930{ 931 /** 932 * Create a new header set. This object is (and must be) fetched from a 933 * stream by calling @ref lsquic_stream_get_hset() before the stream can 934 * be read. 935 */ 936 void * (*hsi_create_header_set)(void *hsi_ctx, 937 int is_push_promise); 938 /** 939 * Process new header. Return 0 on success, -1 if there is a problem with 940 * the header. -1 is treated as a stream error: the associated stream is 941 * reset. 942 * 943 * `hdr_set' is the header set object returned by 944 * @ref hsi_create_header_set(). 945 * 946 * `name_idx' is set to the index in either the HPACK or QPACK static table 947 * whose entry's name element matches `name'. The values are as follows: 948 * - if there is no such match, `name_idx' is set to zero; 949 * - if HPACK is used, the value is between 1 and 61; and 950 * - if QPACK is used, the value is 62+ (subtract 62 to get the QPACK 951 * static table index). 952 * 953 * If `name' is NULL, this means that no more header are going to be 954 * added to the set. 955 */ 956 enum lsquic_header_status (*hsi_process_header)(void *hdr_set, 957 unsigned name_idx, 958 const char *name, unsigned name_len, 959 const char *value, unsigned value_len); 960 /** 961 * Discard header set. This is called for unclaimed header sets and 962 * header sets that had an error. 963 */ 964 void (*hsi_discard_header_set)(void *hdr_set); 965}; 966 967/** 968 * SSL keylog interface. 969 */ 970struct lsquic_keylog_if 971{ 972 /** Return keylog handle or NULL if no key logging is desired */ 973 void * (*kli_open) (void *keylog_ctx, lsquic_conn_t *); 974 975 /** 976 * Log line. The first argument is the pointer returned by 977 * @ref kli_open. 978 */ 979 void (*kli_log_line) (void *handle, const char *line); 980 981 /** 982 * Close handle. 983 */ 984 void (*kli_close) (void *handle); 985}; 986 987/* TODO: describe this important data structure */ 988typedef struct lsquic_engine_api 989{ 990 const struct lsquic_engine_settings *ea_settings; /* Optional */ 991 const struct lsquic_stream_if *ea_stream_if; 992 void *ea_stream_if_ctx; 993 lsquic_packets_out_f ea_packets_out; 994 void *ea_packets_out_ctx; 995 lsquic_lookup_cert_f ea_lookup_cert; 996 void *ea_cert_lu_ctx; 997 struct ssl_ctx_st * (*ea_get_ssl_ctx)(void *peer_ctx); 998 /** 999 * Shared hash interface is optional. If set to zero, performance of 1000 * multiple LSQUIC instances will be degraded. 1001 */ 1002 const struct lsquic_shared_hash_if *ea_shi; 1003 void *ea_shi_ctx; 1004 /** 1005 * Memory interface is optional. 1006 */ 1007 const struct lsquic_packout_mem_if *ea_pmi; 1008 void *ea_pmi_ctx; 1009 /** 1010 * Optional interface to report new and old source connection IDs. 1011 */ 1012 lsquic_cids_update_f ea_new_scids; 1013 lsquic_cids_update_f ea_live_scids; 1014 lsquic_cids_update_f ea_old_scids; 1015 void *ea_cids_update_ctx; 1016 /** 1017 * Function to verify server certificate. The chain contains at least 1018 * one element. The first element in the chain is the server 1019 * certificate. The chain belongs to the library. If you want to 1020 * retain it, call sk_X509_up_ref(). 1021 * 1022 * 0 is returned on success, -1 on error. 1023 * 1024 * If the function pointer is not set, no verification is performed 1025 * (the connection is allowed to proceed). 1026 */ 1027 int (*ea_verify_cert)(void *verify_ctx, 1028 struct stack_st_X509 *chain); 1029 void *ea_verify_ctx; 1030 1031 /** 1032 * Optional header set interface. If not specified, the incoming headers 1033 * are converted to HTTP/1.x format and are read from stream and have to 1034 * be parsed again. 1035 */ 1036 const struct lsquic_hset_if *ea_hsi_if; 1037 void *ea_hsi_ctx; 1038#if LSQUIC_CONN_STATS 1039 /** 1040 * If set, engine will print cumulative connection statistics to this 1041 * file just before it is destroyed. 1042 */ 1043 void /* FILE, really */ *ea_stats_fh; 1044#endif 1045 1046 /** 1047 * Optional SSL key logging interface. 1048 */ 1049 const struct lsquic_keylog_if *ea_keylog_if; 1050 void *ea_keylog_ctx; 1051} lsquic_engine_api_t; 1052 1053/** 1054 * Create new engine. 1055 * 1056 * @param lsquic_engine_flags A bitmask of @ref LSENG_SERVER and 1057 * @ref LSENG_HTTP 1058 */ 1059lsquic_engine_t * 1060lsquic_engine_new (unsigned lsquic_engine_flags, 1061 const struct lsquic_engine_api *); 1062 1063/** 1064 * Create a client connection to peer identified by `peer_ctx'. 1065 * 1066 * To let the engine specify QUIC version, use N_LSQVER. If zero-rtt info 1067 * is supplied, version is picked from there instead. 1068 * 1069 * If `max_packet_size' is set to zero, it is inferred based on `peer_sa': 1070 * 1350 for IPv6 and 1370 for IPv4. 1071 */ 1072lsquic_conn_t * 1073lsquic_engine_connect (lsquic_engine_t *, enum lsquic_version, 1074 const struct sockaddr *local_sa, 1075 const struct sockaddr *peer_sa, 1076 void *peer_ctx, lsquic_conn_ctx_t *conn_ctx, 1077 const char *hostname, unsigned short max_packet_size, 1078 const unsigned char *zero_rtt, size_t zero_rtt_len, 1079 /** Resumption token: optional */ 1080 const unsigned char *token, size_t token_sz); 1081 1082/** 1083 * Pass incoming packet to the QUIC engine. This function can be called 1084 * more than once in a row. After you add one or more packets, call 1085 * lsquic_engine_process_conns() to schedule output, if any. 1086 * 1087 * @retval 0 Packet was processed by a real connection. 1088 * 1089 * @retval 1 Packet was handled successfully, but not by a connection. 1090 * This may happen with version negotiation and public reset 1091 * packets as well as some packets that may be ignored. 1092 * 1093 * @retval -1 Some error occurred. Possible reasons are invalid packet 1094 * size or failure to allocate memory. 1095 */ 1096int 1097lsquic_engine_packet_in (lsquic_engine_t *, 1098 const unsigned char *packet_in_data, size_t packet_in_size, 1099 const struct sockaddr *sa_local, const struct sockaddr *sa_peer, 1100 void *peer_ctx, int ecn); 1101 1102/** 1103 * Process tickable connections. This function must be called often enough so 1104 * that packets and connections do not expire. 1105 */ 1106void 1107lsquic_engine_process_conns (lsquic_engine_t *engine); 1108 1109/** 1110 * Returns true if engine has some unsent packets. This happens if 1111 * @ref ea_packets_out() could not send everything out. 1112 */ 1113int 1114lsquic_engine_has_unsent_packets (lsquic_engine_t *engine); 1115 1116/** 1117 * Send out as many unsent packets as possibe: until we are out of unsent 1118 * packets or until @ref ea_packets_out() fails. 1119 * 1120 * If @ref ea_packets_out() does fail (that is, it returns an error), this 1121 * function must be called to signify that sending of packets is possible 1122 * again. 1123 */ 1124void 1125lsquic_engine_send_unsent_packets (lsquic_engine_t *engine); 1126 1127void 1128lsquic_engine_destroy (lsquic_engine_t *); 1129 1130/** Return max allowed outbound streams less current outbound streams. */ 1131unsigned 1132lsquic_conn_n_avail_streams (const lsquic_conn_t *); 1133 1134void 1135lsquic_conn_make_stream (lsquic_conn_t *); 1136 1137/** Return number of delayed streams currently pending */ 1138unsigned 1139lsquic_conn_n_pending_streams (const lsquic_conn_t *); 1140 1141/** Cancel `n' pending streams. Returns new number of pending streams. */ 1142unsigned 1143lsquic_conn_cancel_pending_streams (lsquic_conn_t *, unsigned n); 1144 1145/** 1146 * Mark connection as going away: send GOAWAY frame and do not accept 1147 * any more incoming streams, nor generate streams of our own. 1148 * 1149 * In the server mode, of course, we can call this function just fine in both 1150 * Google and IETF QUIC. 1151 * 1152 * In client mode, calling this function in for an IETF QUIC connection does 1153 * not do anything, as the client MUST NOT send GOAWAY frames. 1154 * See [draft-ietf-quic-http-17] Section 4.2.7. 1155 */ 1156void 1157lsquic_conn_going_away (lsquic_conn_t *); 1158 1159/** 1160 * This forces connection close. on_conn_closed and on_close callbacks 1161 * will be called. 1162 */ 1163void 1164lsquic_conn_close (lsquic_conn_t *); 1165 1166int lsquic_stream_wantread(lsquic_stream_t *s, int is_want); 1167ssize_t lsquic_stream_read(lsquic_stream_t *s, void *buf, size_t len); 1168ssize_t lsquic_stream_readv(lsquic_stream_t *s, const struct iovec *, 1169 int iovcnt); 1170 1171/** 1172 * This function allows user-supplied callback to read the stream contents. 1173 * It is meant to be used for zero-copy stream processing. 1174 */ 1175ssize_t 1176lsquic_stream_readf (lsquic_stream_t *s, 1177 /** 1178 * The callback takes four parameters: 1179 * - Pointer to user-supplied context; 1180 * - Pointer to the data; 1181 * - Data size (can be zero); and 1182 * - Indicator whether the FIN follows the data. 1183 * 1184 * The callback returns number of bytes processed. If this number is zero 1185 * or is smaller than `len', reading from stream stops. 1186 */ 1187 size_t (*readf)(void *ctx, const unsigned char *buf, size_t len, int fin), 1188 void *ctx); 1189 1190int lsquic_stream_wantwrite(lsquic_stream_t *s, int is_want); 1191 1192/** 1193 * Write `len' bytes to the stream. Returns number of bytes written, which 1194 * may be smaller that `len'. 1195 */ 1196ssize_t lsquic_stream_write(lsquic_stream_t *s, const void *buf, size_t len); 1197 1198ssize_t lsquic_stream_writev(lsquic_stream_t *s, const struct iovec *vec, int count); 1199 1200/** 1201 * Used as argument to @ref lsquic_stream_writef() 1202 */ 1203struct lsquic_reader 1204{ 1205 /** 1206 * Not a ssize_t because the read function is not supposed to return 1207 * an error. If an error occurs in the read function (for example, when 1208 * reading from a file fails), it is supposed to deal with the error 1209 * itself. 1210 */ 1211 size_t (*lsqr_read) (void *lsqr_ctx, void *buf, size_t count); 1212 /** 1213 * Return number of bytes remaining in the reader. 1214 */ 1215 size_t (*lsqr_size) (void *lsqr_ctx); 1216 void *lsqr_ctx; 1217}; 1218 1219/** 1220 * Write to stream using @ref lsquic_reader. This is the most generic of 1221 * the write functions -- @ref lsquic_stream_write() and 1222 * @ref lsquic_stream_writev() utilize the same mechanism. 1223 * 1224 * @retval Number of bytes written or -1 on error. 1225 */ 1226ssize_t 1227lsquic_stream_writef (lsquic_stream_t *, struct lsquic_reader *); 1228 1229/** 1230 * Flush any buffered data. This triggers packetizing even a single byte 1231 * into a separate frame. Flushing a closed stream is an error. 1232 * 1233 * @retval 0 Success 1234 * @retval -1 Failure 1235 */ 1236int 1237lsquic_stream_flush (lsquic_stream_t *s); 1238 1239/** 1240 * @typedef lsquic_http_header_t 1241 * @brief HTTP header structure. Contains header name and value. 1242 * 1243 */ 1244typedef struct lsquic_http_header 1245{ 1246 struct iovec name; 1247 struct iovec value; 1248} lsquic_http_header_t; 1249 1250/** 1251 * @typedef lsquic_http_headers_t 1252 * @brief HTTP header list structure. Contains a list of HTTP headers in key/value pairs. 1253 * used in API functions to pass headers. 1254 */ 1255struct lsquic_http_headers 1256{ 1257 int count; 1258 lsquic_http_header_t *headers; 1259}; 1260 1261int lsquic_stream_send_headers(lsquic_stream_t *s, 1262 const lsquic_http_headers_t *h, int eos); 1263 1264/** 1265 * Get header set associated with the stream. The header set is created by 1266 * @ref hsi_create_header_set() callback. After this call, the ownership of 1267 * the header set is trasnferred to the caller. 1268 * 1269 * This call must precede calls to @ref lsquic_stream_read() and 1270 * @ref lsquic_stream_readv(). 1271 * 1272 * If the optional header set interface (@ref ea_hsi_if) is not specified, 1273 * this function returns NULL. 1274 */ 1275void * 1276lsquic_stream_get_hset (lsquic_stream_t *); 1277 1278/** 1279 * A server may push a stream. This call creates a new stream in reference 1280 * to stream `s'. It will behave as if the client made a request: it will 1281 * trigger on_new_stream() event and it can be used as a regular client- 1282 * initiated stream. 1283 * 1284 * If `hdr_set' is not set, it is generated by using `ea_hsi_if' callbacks. 1285 * In either case, the header set object belongs to the connection. The 1286 * user is not to free this object until (@ref hsi_discard_header_set) is 1287 * called. 1288 * 1289 * @retval 0 Stream pushed successfully. 1290 * @retval 1 Stream push failed because it is disabled or because we hit 1291 * stream limit or connection is going away. 1292 * @retval -1 Stream push failed because of an internal error. 1293 */ 1294int 1295lsquic_conn_push_stream (lsquic_conn_t *c, void *hdr_set, lsquic_stream_t *s, 1296 const struct iovec* url, const struct iovec* authority, 1297 const lsquic_http_headers_t *headers); 1298 1299/** 1300 * Only makes sense in server mode: the client cannot push a stream and this 1301 * function always returns false in client mode. 1302 */ 1303int 1304lsquic_conn_is_push_enabled (lsquic_conn_t *); 1305 1306/** Possible values for how are 0, 1, and 2. See shutdown(2). */ 1307int lsquic_stream_shutdown(lsquic_stream_t *s, int how); 1308 1309int lsquic_stream_close(lsquic_stream_t *s); 1310 1311/** 1312 * Get certificate chain returned by the server. This can be used for 1313 * server certificate verification. 1314 * 1315 * If server certificate cannot be verified, the connection can be closed 1316 * using lsquic_conn_cert_verification_failed(). 1317 * 1318 * The caller releases the stack using sk_X509_free(). 1319 */ 1320struct stack_st_X509 * 1321lsquic_conn_get_server_cert_chain (lsquic_conn_t *); 1322 1323/** Returns ID of the stream */ 1324lsquic_stream_id_t 1325lsquic_stream_id (const lsquic_stream_t *s); 1326 1327/** 1328 * Returns stream ctx associated with the stream. (The context is what 1329 * is returned by @ref on_new_stream callback). 1330 */ 1331lsquic_stream_ctx_t * 1332lsquic_stream_get_ctx (const lsquic_stream_t *s); 1333 1334/** Returns true if this is a pushed stream */ 1335int 1336lsquic_stream_is_pushed (const lsquic_stream_t *s); 1337 1338/** 1339 * Returns true if this stream was rejected, false otherwise. Use this as 1340 * an aid to distinguish between errors. 1341 */ 1342int 1343lsquic_stream_is_rejected (const lsquic_stream_t *s); 1344 1345/** 1346 * Refuse pushed stream. Call it from @ref on_new_stream. 1347 * 1348 * No need to call lsquic_stream_close() after this. on_close will be called. 1349 * 1350 * @see lsquic_stream_is_pushed 1351 */ 1352int 1353lsquic_stream_refuse_push (lsquic_stream_t *s); 1354 1355/** 1356 * Get information associated with pushed stream: 1357 * 1358 * @param ref_stream_id Stream ID in response to which push promise was 1359 * sent. 1360 * @param hdr_set Header set. This object was passed to or generated 1361 * by @ref lsquic_conn_push_stream(). 1362 * 1363 * @retval 0 Success. 1364 * @retval -1 This is not a pushed stream. 1365 */ 1366int 1367lsquic_stream_push_info (const lsquic_stream_t *, 1368 lsquic_stream_id_t *ref_stream_id, void **hdr_set); 1369 1370/** Return current priority of the stream */ 1371unsigned lsquic_stream_priority (const lsquic_stream_t *s); 1372 1373/** 1374 * Set stream priority. Valid priority values are 1 through 256, inclusive. 1375 * 1376 * @retval 0 Success. 1377 * @retval -1 Priority value is invalid. 1378 */ 1379int lsquic_stream_set_priority (lsquic_stream_t *s, unsigned priority); 1380 1381/** 1382 * Get a pointer to the connection object. Use it with lsquic_conn_* 1383 * functions. 1384 */ 1385lsquic_conn_t * lsquic_stream_conn(const lsquic_stream_t *s); 1386 1387lsquic_stream_t * 1388lsquic_conn_get_stream_by_id (lsquic_conn_t *c, lsquic_stream_id_t stream_id); 1389 1390/** Get connection ID */ 1391const lsquic_cid_t * 1392lsquic_conn_id (const lsquic_conn_t *c); 1393 1394/** Get pointer to the engine */ 1395lsquic_engine_t * 1396lsquic_conn_get_engine (lsquic_conn_t *c); 1397 1398int 1399lsquic_conn_get_sockaddr(lsquic_conn_t *c, 1400 const struct sockaddr **local, const struct sockaddr **peer); 1401 1402struct lsquic_logger_if { 1403 int (*log_buf)(void *logger_ctx, const char *buf, size_t len); 1404}; 1405 1406/** 1407 * Enumerate timestamp styles supported by LSQUIC logger mechanism. 1408 */ 1409enum lsquic_logger_timestamp_style { 1410 /** 1411 * No timestamp is generated. 1412 */ 1413 LLTS_NONE, 1414 1415 /** 1416 * The timestamp consists of 24 hours, minutes, seconds, and 1417 * milliseconds. Example: 13:43:46.671 1418 */ 1419 LLTS_HHMMSSMS, 1420 1421 /** 1422 * Like above, plus date, e.g: 2017-03-21 13:43:46.671 1423 */ 1424 LLTS_YYYYMMDD_HHMMSSMS, 1425 1426 /** 1427 * This is Chrome-like timestamp used by proto-quic. The timestamp 1428 * includes month, date, hours, minutes, seconds, and microseconds. 1429 * 1430 * Example: 1223/104613.946956 (instead of 12/23 10:46:13.946956). 1431 * 1432 * This is to facilitate reading two logs side-by-side. 1433 */ 1434 LLTS_CHROMELIKE, 1435 1436 /** 1437 * The timestamp consists of 24 hours, minutes, seconds, and 1438 * microseconds. Example: 13:43:46.671123 1439 */ 1440 LLTS_HHMMSSUS, 1441 1442 /** 1443 * Date and time using microsecond resolution, 1444 * e.g: 2017-03-21 13:43:46.671123 1445 */ 1446 LLTS_YYYYMMDD_HHMMSSUS, 1447 1448 N_LLTS 1449}; 1450 1451/** 1452 * Call this if you want to do something with LSQUIC log messages, as they 1453 * are thrown out by default. 1454 */ 1455void lsquic_logger_init(const struct lsquic_logger_if *, void *logger_ctx, 1456 enum lsquic_logger_timestamp_style); 1457 1458/** 1459 * Set log level for all LSQUIC modules. Acceptable values are debug, info, 1460 * notice, warning, error, alert, emerg, crit (case-insensitive). 1461 * 1462 * @retval 0 Success. 1463 * @retval -1 Failure: log_level is not valid. 1464 */ 1465int 1466lsquic_set_log_level (const char *log_level); 1467 1468/** 1469 * E.g. "event=debug" 1470 */ 1471int 1472lsquic_logger_lopt (const char *optarg); 1473 1474/** 1475 * Return the list of QUIC versions (as bitmask) this engine instance 1476 * supports. 1477 */ 1478unsigned lsquic_engine_quic_versions (const lsquic_engine_t *); 1479 1480/** 1481 * This is one of the flags that can be passed to @ref lsquic_global_init. 1482 * Use it to initialize LSQUIC for use in client mode. 1483 */ 1484#define LSQUIC_GLOBAL_CLIENT (1 << 0) 1485 1486/** 1487 * This is one of the flags that can be passed to @ref lsquic_global_init. 1488 * Use it to initialize LSQUIC for use in server mode. 1489 */ 1490#define LSQUIC_GLOBAL_SERVER (1 << 1) 1491 1492/** 1493 * Initialize LSQUIC. This must be called before any other LSQUIC function 1494 * is called. Returns 0 on success and -1 on failure. 1495 * 1496 * @param flags This a bitmask of @ref LSQUIC_GLOBAL_CLIENT and 1497 * @ref LSQUIC_GLOBAL_SERVER. At least one of these 1498 * flags should be specified. 1499 * 1500 * @retval 0 Success. 1501 * @retval -1 Initialization failed. 1502 * 1503 * @see LSQUIC_GLOBAL_CLIENT 1504 * @see LSQUIC_GLOBAL_SERVER 1505 */ 1506int 1507lsquic_global_init (int flags); 1508 1509/** 1510 * Clean up global state created by @ref lsquic_global_init. Should be 1511 * called after all LSQUIC engine instances are gone. 1512 */ 1513void 1514lsquic_global_cleanup (void); 1515 1516/** 1517 * Get QUIC version used by the connection. 1518 * 1519 * @see lsquic_version 1520 */ 1521enum lsquic_version 1522lsquic_conn_quic_version (const lsquic_conn_t *c); 1523 1524/* Return keysize or -1 on error */ 1525int 1526lsquic_conn_crypto_keysize (const lsquic_conn_t *c); 1527 1528/* Return algorithm keysize or -1 on error */ 1529int 1530lsquic_conn_crypto_alg_keysize (const lsquic_conn_t *c); 1531 1532enum lsquic_crypto_ver 1533{ 1534 LSQ_CRY_QUIC, 1535 LSQ_CRY_TLSv13, 1536}; 1537 1538enum lsquic_crypto_ver 1539lsquic_conn_crypto_ver (const lsquic_conn_t *c); 1540 1541/* Return cipher or NULL on error */ 1542const char * 1543lsquic_conn_crypto_cipher (const lsquic_conn_t *c); 1544 1545/** Translate string QUIC version to LSQUIC QUIC version representation */ 1546enum lsquic_version 1547lsquic_str2ver (const char *str, size_t len); 1548 1549/** Translate ALPN (e.g. "h3", "h3-23", "h3-Q046") to LSQUIC enum */ 1550enum lsquic_version 1551lsquic_alpn2ver (const char *alpn, size_t len); 1552 1553/** 1554 * This function closes all mini connections and marks all full connections 1555 * as going away. In server mode, this also causes the engine to stop 1556 * creating new connections. 1557 */ 1558void 1559lsquic_engine_cooldown (lsquic_engine_t *); 1560 1561struct ssl_st * 1562lsquic_hsk_getssl(lsquic_conn_t *conn); 1563 1564/** 1565 * Get user-supplied context associated with the connection. 1566 */ 1567lsquic_conn_ctx_t * 1568lsquic_conn_get_ctx (const lsquic_conn_t *); 1569 1570/** 1571 * Set user-supplied context associated with the connection. 1572 */ 1573void 1574lsquic_conn_set_ctx (lsquic_conn_t *, lsquic_conn_ctx_t *); 1575 1576/** 1577 * Get peer context associated with the connection. 1578 */ 1579void * 1580lsquic_conn_get_peer_ctx (lsquic_conn_t *, const struct sockaddr *local_sa); 1581 1582/** 1583 * Abort connection. 1584 */ 1585void 1586lsquic_conn_abort (lsquic_conn_t *); 1587 1588/** 1589 * Helper function: convert list of versions as specified in the argument 1590 * bitmask to string that can be included as argument to "v=" part of the 1591 * Alt-Svc header. 1592 * 1593 * For example (1<<LSQVER_037)|(1<<LSQVER_038) => "37,38" 1594 * 1595 * This is only applicable to Google QUIC versions. 1596 */ 1597const char * 1598lsquic_get_alt_svc_versions (unsigned versions); 1599 1600/** 1601 * Return a NULL-terminated list of HTTP/3 ALPNs, e.g "h3-17", "h3-18", "h3". 1602 */ 1603const char *const * 1604lsquic_get_h3_alpns (unsigned versions); 1605 1606/** 1607 * Returns true if provided buffer could be a valid handshake-stage packet, 1608 * false otherwise. Do not call this function if a connection has already 1609 * been established: it will return incorrect result. 1610 */ 1611int 1612lsquic_is_valid_hs_packet (lsquic_engine_t *, const unsigned char *, size_t); 1613 1614/** 1615 * Parse cid from packet stored in `buf' and store it to `cid'. Returns 0 1616 * on success and -1 on failure. 1617 */ 1618int 1619lsquic_cid_from_packet (const unsigned char *, size_t bufsz, lsquic_cid_t *cid); 1620 1621/** 1622 * Returns true if there are connections to be processed, false otherwise. 1623 * If true, `diff' is set to the difference between the earliest advisory 1624 * tick time and now. If the former is in the past, the value of `diff' 1625 * is negative. 1626 */ 1627int 1628lsquic_engine_earliest_adv_tick (lsquic_engine_t *engine, int *diff); 1629 1630/** 1631 * Return number of connections whose advisory tick time is before current 1632 * time plus `from_now' microseconds from now. `from_now' can be negative. 1633 */ 1634unsigned 1635lsquic_engine_count_attq (lsquic_engine_t *engine, int from_now); 1636 1637enum LSQUIC_CONN_STATUS 1638{ 1639 LSCONN_ST_HSK_IN_PROGRESS, 1640 LSCONN_ST_CONNECTED, 1641 LSCONN_ST_HSK_FAILURE, 1642 LSCONN_ST_GOING_AWAY, 1643 LSCONN_ST_TIMED_OUT, 1644 /* If es_honor_prst is not set, the connection will never get public 1645 * reset packets and this flag will not be set. 1646 */ 1647 LSCONN_ST_RESET, 1648 LSCONN_ST_USER_ABORTED, 1649 LSCONN_ST_ERROR, 1650 LSCONN_ST_CLOSED, 1651 LSCONN_ST_PEER_GOING_AWAY, 1652}; 1653 1654enum LSQUIC_CONN_STATUS 1655lsquic_conn_status (lsquic_conn_t *, char *errbuf, size_t bufsz); 1656 1657extern const char *const 1658lsquic_ver2str[N_LSQVER]; 1659 1660#ifdef __cplusplus 1661} 1662#endif 1663 1664#endif //__LSQUIC_H__ 1665 1666