1ngtcp2 2====== 3 4"Call it TCP/2. One More Time." 5 6ngtcp2 project is an effort to implement `RFC9000 7<https://datatracker.ietf.org/doc/html/rfc9000>`_ QUIC protocol. 8 9Documentation 10------------- 11 12`Online documentation <https://nghttp2.org/ngtcp2/>`_ is available. 13 14Public test server 15------------------ 16 17The following endpoints are available to try out ngtcp2 18implementation: 19 20- https://nghttp2.org:4433 21- https://nghttp2.org:4434 (requires address validation token) 22- https://nghttp2.org (powered by `nghttpx 23 <https://nghttp2.org/documentation/nghttpx.1.html>`_) 24 25 This endpoints sends Alt-Svc header field to clients if it is 26 accessed via HTTP/1.1 or HTTP/2 to tell them that HTTP/3 is 27 available at UDP 443. 28 29Requirements 30------------ 31 32The libngtcp2 C library itself does not depend on any external 33libraries. The example client, and server are written in C++17, and 34should compile with the modern C++ compilers (e.g., clang >= 8.0, or 35gcc >= 8.0). 36 37The following packages are required to configure the build system: 38 39- pkg-config >= 0.20 40- autoconf 41- automake 42- autotools-dev 43- libtool 44 45libngtcp2 uses cunit for its unit test frame work: 46 47- cunit >= 2.1 48 49To build sources under the examples directory, libev and nghttp3 are 50required: 51 52- libev 53- `nghttp3 <https://github.com/ngtcp2/nghttp3>`_ for HTTP/3 54 55ngtcp2 crypto helper library, and client and server under examples 56directory require at least one of the following TLS backends: 57 58- `OpenSSL with QUIC support 59 <https://github.com/quictls/openssl/tree/OpenSSL_1_1_1l+quic>`_ 60- GnuTLS >= 3.7.2 61- BoringSSL (commit f6ef1c560ae5af51e2df5d8d2175bed207b28b8f) 62 63Build from git 64-------------- 65 66.. code-block:: text 67 68 $ git clone --depth 1 -b OpenSSL_1_1_1l+quic https://github.com/quictls/openssl 69 $ cd openssl 70 $ # For Linux 71 $ ./config enable-tls1_3 --prefix=$PWD/build 72 $ make -j$(nproc) 73 $ make install_sw 74 $ cd .. 75 $ git clone https://github.com/ngtcp2/nghttp3 76 $ cd nghttp3 77 $ autoreconf -i 78 $ ./configure --prefix=$PWD/build --enable-lib-only 79 $ make -j$(nproc) check 80 $ make install 81 $ cd .. 82 $ git clone https://github.com/ngtcp2/ngtcp2 83 $ cd ngtcp2 84 $ autoreconf -i 85 $ # For Mac users who have installed libev with MacPorts, append 86 $ # ',-L/opt/local/lib' to LDFLAGS, and also pass 87 $ # CPPFLAGS="-I/opt/local/include" to ./configure. 88 $ # For OpenSSL v3.0.0, replace "openssl/build/lib" with 89 $ # "openssl/build/lib64". 90 $ ./configure PKG_CONFIG_PATH=$PWD/../openssl/build/lib/pkgconfig:$PWD/../nghttp3/build/lib/pkgconfig LDFLAGS="-Wl,-rpath,$PWD/../openssl/build/lib" 91 $ make -j$(nproc) check 92 93Client/Server 94------------- 95 96After successful build, the client and server executable should be 97found under examples directory. They talk HTTP/3. 98 99Client 100~~~~~~ 101 102.. code-block:: text 103 104 $ examples/client [OPTIONS] <HOST> <PORT> [<URI>...] 105 106The notable options are: 107 108- ``-d``, ``--data=<PATH>``: Read data from <PATH> and send it to a 109 peer. 110 111Server 112~~~~~~ 113 114.. code-block:: text 115 116 $ examples/server [OPTIONS] <ADDR> <PORT> <PRIVATE_KEY_FILE> <CERTIFICATE_FILE> 117 118The notable options are: 119 120- ``-V``, ``--validate-addr``: Enforce stateless address validation. 121 122H09client/H09server 123------------------- 124 125There are h09client and h09server which speak HTTP/0.9. They are 126written just for `quic-interop-runner 127<https://github.com/marten-seemann/quic-interop-runner>`_. They share 128the basic functionalities with HTTP/3 client and server but have less 129functions (e.g., h09client does not have a capability to send request 130body, and h09server does not understand numeric request path, like 131/1000). 132 133Resumption and 0-RTT 134-------------------- 135 136In order to resume a session, a session ticket, and a transport 137parameters must be fetched from server. First, run examples/client 138with --session-file, and --tp-file options which specify a path to 139session ticket, and transport parameter files respectively to save 140them locally. 141 142Once these files are available, run examples/client with the same 143arguments again. You will see that session is resumed in your log if 144resumption succeeds. Resuming session makes server's first Handshake 145packet pretty small because it does not send its certificates. 146 147To send 0-RTT data, after making sure that resumption works, use -d 148option to specify a file which contains data to send. 149 150Token (Not something included in Retry packet) 151---------------------------------------------- 152 153QUIC server might send a token to client after connection has been 154established. Client can send this token in subsequent connection to 155the server. Server verifies the token and if it succeeds, the address 156validation completes and lifts some restrictions on server which might 157speed up transfer. In order to save and/or load a token, 158use --token-file option of examples/client. The given file is 159overwritten if it already exists when storing a token. 160 161Crypto helper library 162--------------------- 163 164In order to make TLS stack integration less painful, we provide a 165crypto helper library which offers the basic crypto operations. 166 167The header file exists under crypto/includes/ngtcp2 directory. 168 169Each library file is built for a particular TLS backend. The 170available crypto helper libraries are: 171 172- libngtcp2_crypto_openssl: Use OpenSSL as TLS backend 173- libngtcp2_crypto_gnutls: Use GnuTLS as TLS backend 174- libngtcp2_crypto_boringssl: Use BoringSSL as TLS backend 175 176Because BoringSSL is an unversioned product, we only tested its 177particular revision. See Requirements section above. 178 179The examples directory contains client and server that are linked to 180those crypto helper libraries and TLS backends. They are only built 181if their corresponding crypto helper library is built: 182 183- client: OpenSSL client 184- server: OpenSSL server 185- gtlsclient: GnuTLS client 186- gtlsserver: GnuTLS server 187- bsslclient: BoringSSL client 188- bsslserver: BoringSSL server 189 190QUIC protocol extensions 191------------------------- 192 193The library implements the following QUIC protocol extensions: 194 195- `An Unreliable Datagram Extension to QUIC 196 <https://quicwg.org/datagram/draft-ietf-quic-datagram.html>`_ 197- `Greasing the QUIC Bit 198 <https://datatracker.ietf.org/doc/html/draft-ietf-quic-bit-grease>`_ 199 200Configuring Wireshark for QUIC 201------------------------------ 202 203`Wireshark <https://www.wireshark.org/download.html>`_ can be configured to 204analyze QUIC traffic using the following steps: 205 2061. Set *SSLKEYLOGFILE* environment variable: 207 208 .. code-block:: text 209 210 $ export SSLKEYLOGFILE=quic_keylog_file 211 2122. Set the port that QUIC uses 213 214 Go to *Preferences->Protocols->QUIC* and set the port the program 215 listens to. In the case of the example application this would be 216 the port specified on the command line. 217 2183. Set Pre-Master-Secret logfile 219 220 Go to *Preferences->Protocols->TLS* add set the *Pre-Master-Secret 221 log file* to the same value that was specified for *SSLKEYLOGFILE*. 222 2234. Choose the correct network interface for capturing 224 225 Make sure you choose the correct network interface for 226 capturing. For example, if using localhost choose the *loopback* 227 network interface on macos. 228 2295. Create a filter 230 231 Create A filter for the udp.port and set the port to the port the 232 application is listening to. For example: 233 234 .. code-block:: text 235 236 udp.port == 7777 237 238License 239------- 240 241The MIT License 242 243Copyright (c) 2016 ngtcp2 contributors 244