The ngtcp2 programmers’ guide for early adopters
This document is written for early adopters of ngtcp2 library. It describes a brief introduction of programming ngtcp2.
QUIC requires the special interface from TLS stack, which is probably not available from most of the existing TLS stacks. As far as I know, the TLS stacks maintained by the active participants of QUIC working group only get this interface at the time of this writing. In order to build QUIC application you have to choose one of them. Here is the list of TLS stacks which are supposed to provide such interface and for which we provide crypto helper libraries:
Creating ngtcp2_conn object
ngtcp2_callbacks contains the callback functions which
ngtcp2_conn calls when a specific event happens, say,
receiving stream data or stream is closed, etc. Some of the callback
functions are optional. For client application, the following
callback functions must be set:
For server application, the following callback functions must be set:
ngtcp2_crypto_* functions are a part of ngtcp2 crypto API which provides easy integration with the supported
TLS backend. It vastly simplifies TLS integration and is strongly
ngtcp2_settings contains the settings for QUIC connection.
All fields must be set. Application should call
ngtcp2_settings_default() to set the default values. It would be
very useful to enable debug logging by setting logging function to
ngtcp2_settings.log_printf field. ngtcp2 library relies on
the timestamp fed from application. The initial timestamp must be
ngtcp2_settings.initial_ts field in nanosecond
resolution. ngtcp2 cares about the difference from that initial
value. It could be any timestamp which increases monotonically, and
actual value does not matter.
ngtcp2_transport_params contains QUIC transport parameters
which is sent to a remote endpoint during handshake. Application
ngtcp2_transport_params_default() to set the default
values. Server must set
ngtcp2_transport_params.original_dcid and set
ngtcp2_transport_params.original_dcid_present to nonzero.
Client application has to supply Connection IDs to
ngtcp2_conn_client_new(). The dcid parameter is the destination
connection ID (DCID), and which should be random byte string and at
least 8 bytes long. The scid is the source connection ID (SCID)
which identifies the client itself. The client_chosen_version
parameter is the QUIC version to use. It should be
Similarly, server application has to supply these parameters to
ngtcp2_conn_server_new(). But the dcid must be the same value
which is received from client (which is client SCID). The scid is
chosen by server. Don’t use DCID in client packet as server SCID.
The client_chosen_version parameter is the QUIC version that client
A path is very important to QUIC connection. It is the pair of
endpoints, local and remote. The path passed to
ngtcp2_conn_server_new() is a network
path that handshake is performed. The path must not change during
handshake. After handshake is confirmed, client can migrate to new
path. An application must provide actual path to the API function to
tell the library where a packet comes from. The “write” API function
takes path parameter and fills it to which the packet should be sent.
Use of ngtcp2 crypto API is strongly recommended because it vastly simplifies the TLS integration.
The most of the TLS work is done by the callback functions passed to
ngtcp2_callbacks object. There are some operations left to
application in order to make TLS integration work. We have a set of
helper functions to make it easier for applications to configure TLS
stack object to work with QUIC and ngtcp2. They are specific to each
supported TLS stack:
They make the minimal QUIC specific changes to TLS stack object. See
the ngtcp2 crypto API header files for each supported TLS stack. In
order to make these functions work, we require that a pointer to
ngtcp2_crypto_conn_ref must be set as a user data in TLS stack
object, and its
ngtcp2_crypto_conn_ref.get_conn must point
to a function which returns
ngtcp2_conn of the underlying QUIC
If you do not use the above helper functions, you need to generate and
install keys to
ngtcp2_conn, and pass handshake messages to
ngtcp2_conn as well. When TLS stack generates new secrets,
they have to be installed to
ngtcp2_conn by calling
ngtcp2_crypto_derive_and_install_tx_key(). When TLS stack generates
new crypto data to send, they must be passed to
When QUIC handshake is completed,
ngtcp2_callbacks.handshake_completed callback function is
called. The local and remote endpoint independently declare handshake
completion. The endpoint has to confirm that the other endpoint also
finished handshake. When the handshake is confirmed, client side
ngtcp2_conn will call
ngtcp2_callbacks.handshake_confirmed callback function.
Server confirms handshake when it declares handshake completion,
therefore, separate handshake confirmation callback is not called.
Read and write packets
ngtcp2_conn_read_pkt() processes the incoming QUIC packets. In
order to write QUIC packets, call
ngtcp2_conn_write_pkt(). The destlen parameter must be at least
the value returned from
In order to send stream data, the application has to first open a
stream. In earliest, clients can open streams after installing 1RTT
RX(decryption) key, which is notified by
ngtcp2_callbacks.recv_rx_key. Because the key is installed
just before handshake completion, handshake completion (see
ngtcp2_callbacks.handshake_completed) is also a good signal
to start opening streams. For convenience,
ngtcp2_callbacks.extend_max_local_streams_uni are called
ngtcp2_callbacks.handshake_completed callback if
there are streams IDs available.
For server, it can open streams after installing 1RTT TX(encryption)
key, which is notified by
Note that handshake is not authenticated until handshake completes.
Therefore, it is a good practice to send important data after
An application should pace sending packets.
ngtcp2_conn_get_send_quantum() returns the number of bytes that can
be sent without packet spacing. After one or more calls of
ngtcp2_conn_writev_stream() (it can be called multiple times to fill
the buffer sized up to
ngtcp2_conn_get_send_quantum() bytes), call
ngtcp2_conn_update_pkt_tx_time() to set the timer when the next
packet should be sent. The timer is integrated into
Packet handling on server side
Any incoming UDP datagram should be first processed by
ngtcp2_pkt_decode_version_cid(). It can handle Connection ID more
than 20 bytes which is the maximum length defined in QUIC v1. If the
should send Version Negotiation packet. Use
ngtcp2_pkt_write_version_negotiation() for this purpose. If
ngtcp2_pkt_decode_version_cid() succeeds, then check whether the UDP
datagram belongs to any existing connection by looking up connection
tables by Destination Connection ID (refer to the next section to know
how to associate Connection ID to a
ngtcp2_conn). If it
belongs to an existing connection, pass the UDP datagram to
ngtcp2_conn_read_pkt(). If it does not belong to any existing
connection, it should be passed to
ngtcp2_accept(). If it returns a
negative error code, just drop the packet to the floor and take no
action, or send Stateless Reset packet (use
ngtcp2_pkt_write_stateless_reset() to create Stateless Reset
packet). Otherwise, the UDP datagram is acceptable as a new
ngtcp2_conn object and pass the UDP
Associating Connection ID to ngtcp2_conn
Server needs to route an incoming UDP datagram to the correct
ngtcp2_conn by its Destination Connection ID. When a UDP
datagram is received, and it does not belong to any existing
connections, and it is successfully processed by
ngtcp2_conn_read_pkt(), associate the Destination Connection ID in
the QUIC packet and
ngtcp2_conn object. The server must
associate the Connection IDs returned by
ngtcp2_conn object as well. When new Connection ID is
asked by the library,
is called. Inside the callback, associate the newly generated
Connection ID to the
When Connection ID is no longer used, its association should be
removed. When Connection ID is retired,
ngtcp2_callbacks.remove_connection_id is called. Inside the
callback, remove the association for the Connection ID.
When a QUIC connection is closed, all associations for the connection
should be removed. Remove all associations for Connection ID returned
ngtcp2_conn_get_scid(). Association for the initial Connection
ID which can be obtained by calling
ngtcp2_conn_get_client_initial_dcid() should also be removed.
Dealing with 0-RTT (early) data
Client application has to remember the subset of the QUIC transport
parameters received from a server in the previous connection.
ngtcp2_conn_encode_0rtt_transport_params() returns the encoded QUIC
transport parameters that include these values. When sending 0-RTT
data, the remembered transport parameters should be set via
ngtcp2_conn_decode_and_set_0rtt_transport_params(). Then client can
open streams with
ngtcp2_conn_open_uni_stream(). Note that
ngtcp2_conn_decode_and_set_0rtt_transport_params() does not invoke
Other than that, there is no difference between 0-RTT and 1-RTT data in terms of API usage.
If early data is rejected by a server during TLS handshake, client
ngtcp2_conn_tls_early_data_rejected(). All connection
states altered during 0-RTT transmission are undone. The library does
not retransmit 0-RTT data to server as 1-RTT data. If an application
wishes to resend data, it has to reopen streams and writes data again.
The send-side stream is closed when you call
flag set, and all data are acknowledged. The receive-side stream is
closed when a local endpoint receives fin from a remote endpoint, and
all data are received. And then
ngtcp2_callbacks.stream_close is invoked.
Application can close stream abruptly by calling
ngtcp2_conn_shutdown_stream(). It has
ngtcp2_conn_shutdown_stream_read() variants that close the individual
side of a stream.
Stream data ownership
Stream data passed to
ngtcp2_conn must be held by application
ngtcp2_callbacks.acked_stream_data_offset callbacks is
invoked, telling that the those data are acknowledged by the remote
endpoint and no longer used by the library.
The library does not ask an operating system for any timestamp.
Instead, an application has to supply timestamp to the library. The
type of timestamp in ngtcp2 library is
ngtcp2_tstamp which is
nanosecond resolution. The library only cares the difference of
timestamp, so it does not have to be a system clock. A monotonic
clock should work better. It should be same clock passed to
ngtcp2_settings.initial_ts. The duration in ngtcp2 library
ngtcp2_duration which is also nanosecond resolution.
ngtcp2_conn_get_expiry() tells an application when timer fires.
When it fires, call
ngtcp2_conn_handle_expiry(). If it returns
NGTCP2_ERR_IDLE_CLOSE, it means that an idle timer has fired
for this particular connection. In this case, drop the connection
ngtcp2_conn_writev_stream(). After calling
expiry is set. The application should call
to get a new deadline.
In QUIC, client application can migrate to a new local address.
ngtcp2_conn_initiate_immediate_migration() migrates to a new local
address without checking reachability. On the other hand,
ngtcp2_conn_initiate_migration() migrates to a new local address
after a new path is validated (thus reachability is established).
Closing connection abruptly
In order to close QUIC connection abruptly, call
ngtcp2_conn_write_connection_close() and get a terminal packet.
After the call, the connection enters the closing state.
The closing and draining state
After the successful call of
the connection enters the closing state. When
connection has entered the draining state. In these states,
ngtcp2_conn_read_pkt() return an
NGTCP2_ERR_DRAINING depending on the state).
ngtcp2_conn_write_connection_close() returns 0 in these states. If
an application needs to send a packet containing CONNECTION_CLOSE
frame in the closing state, resend the packet produced by the first
ngtcp2_conn_write_connection_close(). Therefore, after a
connection has entered one of these states, the application can
ngtcp2_conn object. The closing and draining state
should persist at least 3 times the current PTO.
Error handling in general
In general, when error is returned from the ngtcp2 library function,
ngtcp2_conn_write_connection_close() to get terminal packet.
If the successful call of the function creates non-empty packet, the
QUIC connection enters the closing state. Calling
ngtcp2_conn_writev_stream() after getting a
negative error code is undefined except for the errors that are
defined as transitional. See below and their documentation.
NGTCP2_ERR_DROP_CONN is returned from
ngtcp2_conn_read_pkt(), a connection should be dropped without calling
ngtcp2_conn_write_connection_close(). Similarly, if
NGTCP2_ERR_IDLE_CLOSE is returned from
ngtcp2_conn_handle_expiry(), a connection should be dropped without
NGTCP2_ERR_DRAINING is returned from
a connection has entered the draining state, and no further packet
transmission is allowed.
The following error codes must be considered as transitional, and application should keep connection alive:
Version negotiation is configured with the following
client_chosen_version passed to
influence the version negotiation process.
By default, client sends client_chosen_version passed to
ngtcp2_conn_client_new() in available_versions field of
version_information QUIC transport parameter. That means there is no
chance for server to select the other compatible version. Meanwhile,
ngtcp2 supports QUIC v2 version (
ngtcp2_settings.available_versions field allows server to
NGTCP2_PROTO_VER_V2 which is compatible to
By default, server sends
available_versions field of version_information QUIC transport
parameter. Because there is no particular preferred versions
specified, server will accept any supported version. In order to set
the version preference, specify
ngtcp2_settings.preferred_versions field. If it is
specified, server sends them in available_versions field of
version_information QUIC transport parameter unless
ngtcp2_settings.available_versionslen is not zero.
ngtcp2_settings.available_versions overrides the
above mentioned default behavior. Even if there is no overlap between
ngtcp2_settings.preferred_versions and available_versions
field plus client_chosen_version from client, as long as
client_chosen_version is supported by server, server accepts
If client receives Version Negotiation packet from server,
ngtcp2_callbacks.recv_version_negotiation is also invoked if
set. It will provide the versions contained in the packet. Client
then either gives up the connection attempt, or selects the version
from Version Negotiation packet, and starts new connection attempt
with that version. In the latter case, the initial version that used
in the first connection attempt must be set to
ngtcp2_settings.original_version. The client version
preference that is used when selecting a version from Version
Negotiation packet must be set to
ngtcp2_settings.available_versions must include the selected
version. The selected version becomes client_chosen_version in the
second connection attempt, and must be passed to
Server never know whether client reacted upon Version Negotiation packet or not, and there is no particular setup for server to make this incompatible version negotiation work.
ngtcp2 library is thread-safe as long as a single
object is accessed by a single thread at a time. For multi-threaded
applications, it is recommended to create
per thread to avoid locks.