ngtcp2

"Call it TCP/2. One More Time."

ngtcp2 project is an effort to implement RFC9000 QUIC protocol.

Documentation

Online documentation is available.

Public test server

The following endpoints are available to try out ngtcp2implementation:

• https://nghttp2.org:4433

• https://nghttp2.org:4434 (requires address validation token)

• https://nghttp2.org (powered by nghttpx)

  This endpoints sends Alt-Svc header field to clients if it isaccessed via HTTP/1.1 or HTTP/2 to tell them that HTTP/3 isavailable at UDP 443.

Requirements

The libngtcp2 C library itself does not depend on any externallibraries. The example client, and server are written in C++17, andshould compile with the modern C++ compilers (e.g., clang >= 8.0, orgcc >= 8.0).

The following packages are required to configure the build system:

• pkg-config >= 0.20
• autoconf
• automake
• autotools-dev
• libtool

libngtcp2 uses cunit for its unit test frame work:

• cunit >= 2.1

To build sources under the examples directory, libev and nghttp3 arerequired:

• libev
• nghttp3 for HTTP/3

ngtcp2 crypto helper library, and client and server under examplesdirectory require at least one of the following TLS backends:

• OpenSSL with QUIC support
• GnuTLS >= 3.7.2
• BoringSSL (commit f6ef1c560ae5af51e2df5d8d2175bed207b28b8f)

Build from git

$ git clone --depth 1 -b OpenSSL_1_1_1l+quic https://github.com/quictls/openssl
$ cd openssl
$ # For Linux
$ ./config enable-tls1_3 --prefix=$PWD/build
$ make -j$(nproc)
$ make install_sw
$ cd ..
$ git clone https://github.com/ngtcp2/nghttp3
$ cd nghttp3
$ autoreconf -i
$ ./configure --prefix=$PWD/build --enable-lib-only
$ make -j$(nproc) check
$ make install
$ cd ..
$ git clone https://github.com/ngtcp2/ngtcp2
$ cd ngtcp2
$ autoreconf -i
$ # For Mac users who have installed libev with MacPorts, append
$ # ',-L/opt/local/lib' to LDFLAGS, and also pass
$ # CPPFLAGS="-I/opt/local/include" to ./configure.
$ # For OpenSSL v3.0.0, replace "openssl/build/lib" with
$ # "openssl/build/lib64".
$ ./configure PKG_CONFIG_PATH=$PWD/../openssl/build/lib/pkgconfig:$PWD/../nghttp3/build/lib/pkgconfig LDFLAGS="-Wl,-rpath,$PWD/../openssl/build/lib"
$ make -j$(nproc) check

Client/Server

After successful build, the client and server executable should befound under examples directory. They talk HTTP/3.

Client

$ examples/client [OPTIONS] <HOST> <PORT> [<URI>...]

The notable options are:

• -d, --data=<PATH>: Read data from <PATH> and send it to apeer.

Server

$ examples/server [OPTIONS] <ADDR> <PORT> <PRIVATE_KEY_FILE> <CERTIFICATE_FILE>

The notable options are:

• -V, --validate-addr: Enforce stateless address validation.

H09client/H09server

There are h09client and h09server which speak HTTP/0.9. They arewritten just for quic-interop-runner. They sharethe basic functionalities with HTTP/3 client and server but have lessfunctions (e.g., h09client does not have a capability to send requestbody, and h09server does not understand numeric request path, like/1000).

Resumption and 0-RTT

In order to resume a session, a session ticket, and a transportparameters must be fetched from server. First, run examples/clientwith --session-file, and --tp-file options which specify a path tosession ticket, and transport parameter files respectively to savethem locally.

Once these files are available, run examples/client with the samearguments again. You will see that session is resumed in your log ifresumption succeeds. Resuming session makes server's first Handshakepacket pretty small because it does not send its certificates.

To send 0-RTT data, after making sure that resumption works, use -doption to specify a file which contains data to send.

Token (Not something included in Retry packet)

QUIC server might send a token to client after connection has beenestablished. Client can send this token in subsequent connection tothe server. Server verifies the token and if it succeeds, the addressvalidation completes and lifts some restrictions on server which mightspeed up transfer. In order to save and/or load a token,use --token-file option of examples/client. The given file isoverwritten if it already exists when storing a token.

Crypto helper library

In order to make TLS stack integration less painful, we provide acrypto helper library which offers the basic crypto operations.

The header file exists under crypto/includes/ngtcp2 directory.

Each library file is built for a particular TLS backend. Theavailable crypto helper libraries are:

• libngtcp2_crypto_openssl: Use OpenSSL as TLS backend
• libngtcp2_crypto_gnutls: Use GnuTLS as TLS backend
• libngtcp2_crypto_boringssl: Use BoringSSL as TLS backend

Because BoringSSL is an unversioned product, we only tested itsparticular revision. See Requirements section above.

The examples directory contains client and server that are linked tothose crypto helper libraries and TLS backends. They are only builtif their corresponding crypto helper library is built:

• client: OpenSSL client
• server: OpenSSL server
• gtlsclient: GnuTLS client
• gtlsserver: GnuTLS server
• bsslclient: BoringSSL client
• bsslserver: BoringSSL server

QUIC protocol extensions

The library implements the following QUIC protocol extensions:

• An Unreliable Datagram Extension to QUIC
• Greasing the QUIC Bit

Configuring Wireshark for QUIC

Wireshark can be configured toanalyze QUIC traffic using the following steps:

1. Set SSLKEYLOGFILE environment variable:

   $ export SSLKEYLOGFILE=quic_keylog_file

2. Set the port that QUIC uses

   Go to Preferences->Protocols->QUIC and set the port the programlistens to. In the case of the example application this would bethe port specified on the command line.

3. Set Pre-Master-Secret logfile

   Go to Preferences->Protocols->TLS add set the Pre-Master-Secretlog file to the same value that was specified for SSLKEYLOGFILE.

4. Choose the correct network interface for capturing

   Make sure you choose the correct network interface forcapturing. For example, if using localhost choose the loopbacknetwork interface on macos.

5. Create a filter

   Create A filter for the udp.port and set the port to the port theapplication is listening to. For example:

   udp.port == 7777

License

The MIT License

Copyright (c) 2016 ngtcp2 contributors