CINXE.COM
HTTP/3 with curl
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>HTTP/3 with curl</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"> <link rel="stylesheet" type="text/css" href="/curl.css"> <link rel="shortcut icon" href="/favicon.ico"> <link rel="icon" href="/logo/curl-symbol.svg" type="image/svg+xml"> <link rel="alternate" type="application/rss+xml" title="cURL Releases" href="https://github.com/curl/curl/releases.atom"> </head> <body> <div class="main"> <div class="menu"> <a href="/docs/" class="menuitem" title="Documentation Overview">Docs Overview</a> <div class="dropdown"> <a class="dropbtn" href="/docs/projdocs.html">Project</a> <div class="dropdown-content"> <a href="/docs/bugbounty.html">Bug Bounty</a> <a href="/docs/bugs.html">Bug Report</a> <a href="/docs/code-of-conduct.html">Code of conduct</a> <a href="/docs/libs.html">Dependencies</a> <a href="/donation.html">Donate</a> <a href="/docs/faq.html">FAQ</a> <a href="/docs/features.html">Features</a> <a href="/docs/governance.html">Governance</a> <a href="/docs/history.html">History</a> <a href="/docs/install.html">Install</a> <a href="/docs/knownbugs.html">Known Bugs</a> <a href="/logo/">Logo</a> <a href="/docs/todo.html">TODO</a> <a href="/about.html">website Info</a> </div> </div> <div class="dropdown"> <a class="dropbtn" href="/docs/protdocs.html">Protocols</a> <div class="dropdown-content"> <a href="/docs/caextract.html">CA Extract</a> <a href="/docs/http-cookies.html">HTTP cookies</a> <a href="/docs/http3.html">HTTP/3</a> <a href="/docs/mqtt.html">MQTT</a> <a href="/docs/sslcerts.html">SSL certs</a> <a href="/docs/ssl-compared.html">SSL libs compared</a> <a href="/docs/url-syntax.html">URL syntax</a> <a href="/docs/websocket.html">WebSocket</a> </div> </div> <div class="dropdown"> <a class="dropbtn" href="/docs/reldocs.html">Releases</a> <div class="dropdown-content"> <a href="/ch/">Changelog</a> <a href="/docs/security.html">curl CVEs</a> <a href="/docs/releases.html">Release Table</a> <a href="/docs/versions.html">Version Numbering</a> <a href="/docs/vulnerabilities.html">Vulnerabilities</a> </div> </div> <div class="dropdown"> <a class="dropbtn" href="/docs/tooldocs.html">Tool</a> <div class="dropdown-content"> <a href="/docs/comparison-table.html">Comparison Table</a> <a href="/docs/manpage.html">curl man page</a> <a href="/docs/httpscripting.html">HTTP Scripting</a> <a href="/docs/mk-ca-bundle.html">mk-ca-bundle</a> <a href="/docs/tutorial.html">Tutorial</a> <a href="optionswhen.html">When options were added</a> </div> </div> <div class="dropdown"> <a class="dropbtn" href="/docs/whodocs.html">Who and Why</a> <div class="dropdown-content"> <a href="/docs/companies.html">Companies</a> <a href="/docs/copyright.html">Copyright</a> <a href="/sponsors.html">Sponsors</a> <a href="/docs/thanks.html">Thanks</a> <a href="/docs/thename.html">The name</a> </div> </div> </div> <div class="contents"> <div class="where"><a href="/">curl</a> / <a href="/docs/">Docs</a> / <a href="/docs/protdocs.html">Protocols</a> / <b>HTTP/3 with curl</b></div> <!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. SPDX-License-Identifier: curl --> <h1 id="http3-and-quic">HTTP3 (and QUIC)</h1> <h2 id="resources">Resources</h2> <p><a href="https://http3-explained.haxx.se/en/">HTTP/3 Explained</a> - the online free book describing the protocols involved.</p> <p><a href="https://quicwg.org/">quicwg.org</a> - home of the official protocol drafts</p> <h2 id="quic-libraries">QUIC libraries</h2> <p>QUIC libraries we are using:</p> <p><a href="https://github.com/ngtcp2/ngtcp2">ngtcp2</a></p> <p><a href="https://github.com/cloudflare/quiche">quiche</a> - <strong>EXPERIMENTAL</strong></p> <p><a href="https://github.com/openssl/openssl">OpenSSL 3.2+ QUIC</a> - <strong>EXPERIMENTAL</strong></p> <p><a href="https://github.com/nibanks/msh3">msh3</a> (with <a href="https://github.com/microsoft/msquic">msquic</a>) - <strong>EXPERIMENTAL</strong></p> <h2 id="experimental">Experimental</h2> <p>HTTP/3 support in curl is considered <strong>EXPERIMENTAL</strong> until further notice when built to use <em>quiche</em> or <em>msh3</em>. Only the <em>ngtcp2</em> backend is not experimental.</p> <p>Further development and tweaking of the HTTP/3 support in curl happens in the master branch using pull-requests, just like ordinary changes.</p> <p>To fix before we remove the experimental label:</p> <ul> <li>the used QUIC library needs to consider itself non-beta</li> <li>it is fine to "leave" individual backends as experimental if necessary</li> </ul> <h1 id="ngtcp2-version">ngtcp2 version</h1> <p>Building curl with ngtcp2 involves 3 components: <code>ngtcp2</code> itself, <code>nghttp3</code> and a QUIC supporting TLS library. The supported TLS libraries are covered below.</p> <ul> <li><code>ngtcp2</code>: v1.2.0</li> <li><code>nghttp3</code>: v1.1.0</li> </ul> <h2 id="build-with-quictls">Build with quictls</h2> <p>OpenSSL does not offer the required APIs for building a QUIC client. You need to use a TLS library that has such APIs and that works with <em>ngtcp2</em>.</p> <p>Build quictls:</p> <pre><code> % git clone --depth 1 -b openssl-3.1.4+quic https://github.com/quictls/openssl % cd openssl % ./config enable-tls1_3 --prefix=<somewhere1> % make % make install</code></pre> <p>Build nghttp3:</p> <pre><code> % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 % git submodule update --init % autoreconf -fi % ./configure --prefix=<somewhere2> --enable-lib-only % make % make install</code></pre> <p>Build ngtcp2:</p> <pre><code> % cd .. % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=<somewhere1>/lib/pkgconfig:<somewhere2>/lib/pkgconfig LDFLAGS="-Wl,-rpath,<somewhere1>/lib" --prefix=<somewhere3> --enable-lib-only % make % make install</code></pre> <p>Build curl:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % LDFLAGS="-Wl,-rpath,<somewhere1>/lib" ./configure --with-openssl=<somewhere1> --with-nghttp3=<somewhere2> --with-ngtcp2=<somewhere3> % make % make install</code></pre> <p>For OpenSSL 3.0.0 or later builds on Linux for x86_64 architecture, substitute all occurrences of "/lib" with "/lib64"</p> <h2 id="build-with-gnutls">Build with GnuTLS</h2> <p>Build GnuTLS:</p> <pre><code> % git clone --depth 1 https://gitlab.com/gnutls/gnutls.git % cd gnutls % ./bootstrap % ./configure --prefix=<somewhere1> % make % make install</code></pre> <p>Build nghttp3:</p> <pre><code> % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 % git submodule update --init % autoreconf -fi % ./configure --prefix=<somewhere2> --enable-lib-only % make % make install</code></pre> <p>Build ngtcp2:</p> <pre><code> % cd .. % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=<somewhere1>/lib/pkgconfig:<somewhere2>/lib/pkgconfig LDFLAGS="-Wl,-rpath,<somewhere1>/lib" --prefix=<somewhere3> --enable-lib-only --with-gnutls % make % make install</code></pre> <p>Build curl:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % ./configure --with-gnutls=<somewhere1> --with-nghttp3=<somewhere2> --with-ngtcp2=<somewhere3> % make % make install</code></pre> <h2 id="build-with-wolfssl">Build with wolfSSL</h2> <p>Build wolfSSL:</p> <pre><code> % git clone https://github.com/wolfSSL/wolfssl.git % cd wolfssl % autoreconf -fi % ./configure --prefix=<somewhere1> --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains % make % make install</code></pre> <p>Build nghttp3:</p> <pre><code> % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 % git submodule update --init % autoreconf -fi % ./configure --prefix=<somewhere2> --enable-lib-only % make % make install</code></pre> <p>Build ngtcp2:</p> <pre><code> % cd .. % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=<somewhere1>/lib/pkgconfig:<somewhere2>/lib/pkgconfig LDFLAGS="-Wl,-rpath,<somewhere1>/lib" --prefix=<somewhere3> --enable-lib-only --with-wolfssl % make % make install</code></pre> <p>Build curl:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % ./configure --with-wolfssl=<somewhere1> --with-nghttp3=<somewhere2> --with-ngtcp2=<somewhere3> % make % make install</code></pre> <h1 id="quiche-version">quiche version</h1> <p>quiche support is <strong>EXPERIMENTAL</strong></p> <p>Since the quiche build manages its dependencies, curl can be built against the latest version. You are <em>probably</em> able to build against their main branch, but in case of problems, we recommend their latest release tag.</p> <h2 id="build">Build</h2> <p>Build quiche and BoringSSL:</p> <pre><code> % git clone --recursive -b 0.22.0 https://github.com/cloudflare/quiche % cd quiche % cargo build --package quiche --release --features ffi,pkg-config-meta,qlog % ln -s libquiche.so target/release/libquiche.so.0 % mkdir quiche/deps/boringssl/src/lib % ln -vnf $(find target/release -name libcrypto.a -o -name libssl.a) quiche/deps/boringssl/src/lib/</code></pre> <p>Build curl:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % ./configure LDFLAGS="-Wl,-rpath,$PWD/../quiche/target/release" --with-openssl=$PWD/../quiche/quiche/deps/boringssl/src --with-quiche=$PWD/../quiche/target/release % make % make install</code></pre> <p>If <code>make install</code> results in <code>Permission denied</code> error, you need to prepend it with <code>sudo</code>.</p> <h1 id="openssl-version">OpenSSL version</h1> <p>QUIC support is <strong>EXPERIMENTAL</strong></p> <p>Build OpenSSL 3.3.1:</p> <pre><code> % cd .. % git clone -b openssl-3.3.1 https://github.com/openssl/openssl % cd openssl % ./config enable-tls1_3 --prefix=<somewhere> --libdir=lib % make % make install</code></pre> <p>Build nghttp3:</p> <pre><code> % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 % git submodule update --init % autoreconf -fi % ./configure --prefix=<somewhere2> --enable-lib-only % make % make install</code></pre> <p>Build curl:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % LDFLAGS="-Wl,-rpath,<somewhere>/lib" ./configure --with-openssl=<somewhere> --with-openssl-quic --with-nghttp3=<somewhere2> % make % make install</code></pre> <p>You can build curl with cmake:</p> <pre><code> % cd .. % git clone https://github.com/curl/curl % cd curl % cmake . -B bld -DCURL_USE_OPENSSL=ON -DUSE_OPENSSL_QUIC=ON % cmake --build bld % cmake --install bld</code></pre> <p>If <code>make install</code> results in <code>Permission denied</code> error, you need to prepend it with <code>sudo</code>.</p> <h1 id="msh3-msquic-version">msh3 (msquic) version</h1> <p><strong>Note</strong>: The msquic HTTP/3 backend is immature and is not properly functional one as of September 2023. Feel free to help us test it and improve it, but there is no point in filing bugs about it just yet.</p> <p>msh3 support is <strong>EXPERIMENTAL</strong></p> <h2 id="build-linux-with-quictls-fork-of-openssl">Build Linux (with quictls fork of OpenSSL)</h2> <p>Build msh3:</p> <pre><code> % git clone -b v0.6.0 --depth 1 --recursive https://github.com/nibanks/msh3 % cd msh3 && mkdir build && cd build % cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=RelWithDebInfo .. % cmake --build . % cmake --install .</code></pre> <p>Build curl:</p> <pre><code> % git clone https://github.com/curl/curl % cd curl % autoreconf -fi % ./configure LDFLAGS="-Wl,-rpath,/usr/local/lib" --with-msh3=/usr/local --with-openssl % make % make install</code></pre> <p>Run from <code>/usr/local/bin/curl</code>.</p> <h2 id="build-windows">Build Windows</h2> <p>Build msh3:</p> <pre><code> % git clone -b v0.6.0 --depth 1 --recursive https://github.com/nibanks/msh3 % cd msh3 && mkdir build && cd build % cmake -G 'Visual Studio 17 2022' -DCMAKE_BUILD_TYPE=RelWithDebInfo .. % cmake --build . --config Release % cmake --install . --config Release</code></pre> <p><strong>Note</strong> - On Windows, Schannel is used for TLS support by default. If you with to use (the quictls fork of) OpenSSL, specify the <code>-DQUIC_TLS=openssl</code> option to the generate command above. Also note that OpenSSL brings with it an additional set of build dependencies not specified here.</p> <p>Build curl (in <a href="../winbuild/README.md#open-a-command-prompt">Visual Studio Command prompt</a>):</p> <pre><code> % git clone https://github.com/curl/curl % cd curl/winbuild % nmake /f Makefile.vc mode=dll WITH_MSH3=dll MSH3_PATH="C:/Program Files/msh3" MACHINE=x64</code></pre> <p><strong>Note</strong> - If you encounter a build error with <code>tool_hugehelp.c</code> being missing, rename <code>tool_hugehelp.c.cvs</code> in the same directory to <code>tool_hugehelp.c</code> and then run <code>nmake</code> again.</p> <p>Run in the <code>C:/Program Files/msh3/lib</code> directory, copy <code>curl.exe</code> to that directory, or copy <code>msquic.dll</code> and <code>msh3.dll</code> from that directory to the <code>curl.exe</code> directory. For example:</p> <pre><code> % C:\Program Files\msh3\lib> F:\curl\builds\libcurl-vc-x64-release-dll-ipv6-sspi-schannel-msh3\bin\curl.exe --http3 https://curl.se/</code></pre> <h1 id="--http3"><code>--http3</code></h1> <p>Use only HTTP/3:</p> <pre><code> % curl --http3-only https://example.org:4433/</code></pre> <p>Use HTTP/3 with fallback to HTTP/2 or HTTP/1.1 (see "HTTPS eyeballing" below):</p> <pre><code> % curl --http3 https://example.org:4433/</code></pre> <p>Upgrade via Alt-Svc:</p> <pre><code> % curl --alt-svc altsvc.cache https://curl.se/</code></pre> <p>See this <a href="https://bagder.github.io/HTTP3-test/">list of public HTTP/3 servers</a></p> <h3 id="https-eyeballing">HTTPS eyeballing</h3> <p>With option <code>--http3</code> curl attempts earlier HTTP versions as well should the connect attempt via HTTP/3 not succeed "fast enough". This strategy is similar to IPv4/6 happy eyeballing where the alternate address family is used in parallel after a short delay.</p> <p>The IPv4/6 eyeballing has a default of 200ms and you may override that via <code>--happy-eyeballs-timeout-ms value</code>. Since HTTP/3 is still relatively new, we decided to use this timeout also for the HTTP eyeballing - with a slight twist.</p> <p>The <code>happy-eyeballs-timeout-ms</code> value is the <strong>hard</strong> timeout, meaning after that time expired, a TLS connection is opened in addition to negotiate HTTP/2 or HTTP/1.1. At half of that value - currently - is the <strong>soft</strong> timeout. The soft timeout fires, when there has been <strong>no data at all</strong> seen from the server on the HTTP/3 connection.</p> <p>So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms:</p> <ul> <li>Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection in less than 100ms.</li> <li>When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.</li> <li>In the worst case, UDP replies start before 100ms, but drag on. This starts the TLS+TCP connection after 200ms.</li> <li>When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.</li> </ul> <p>The whole transfer only fails, when <strong>both</strong> QUIC and TLS+TCP fail to handshake or time out.</p> <p>Note that all this happens in addition to IP version happy eyeballing. If the name resolution for the server gives more than one IP address, curl tries all those until one succeeds - just as with all other protocols. If those IP addresses contain both IPv6 and IPv4, those attempts happen, delayed, in parallel (the actual eyeballing).</p> <h2 id="known-bugs">Known Bugs</h2> <p>Check out the <a href="https://curl.se/docs/knownbugs.html#HTTP3">list of known HTTP3 bugs</a>.</p> <h1 id="http3-test-server">HTTP/3 Test server</h1> <p>This is not advice on how to run anything in production. This is for development and experimenting.</p> <h2 id="prerequisites">Prerequisite(s)</h2> <p>An existing local HTTP/1.1 server that hosts files. Preferably also a few huge ones. You can easily create huge local files like <code>truncate -s=8G 8GB</code> - they are huge but do not occupy that much space on disk since they are just big holes.</p> <p>In a Debian setup you can install apache2. It runs on port 80 and has a document root in <code>/var/www/html</code>. Download the 8GB file from apache with <code>curl localhost/8GB -o dev/null</code></p> <p>In this description we setup and run an HTTP/3 reverse-proxy in front of the HTTP/1 server.</p> <h2 id="setup">Setup</h2> <p>You can select either or both of these server solutions.</p> <h3 id="nghttpx">nghttpx</h3> <p>Get, build and install quictls, nghttp3 and ngtcp2 as described above.</p> <p>Get, build and install nghttp2:</p> <pre><code> % git clone https://github.com/nghttp2/nghttp2.git % cd nghttp2 % autoreconf -fi % PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/home/daniel/build-quictls/lib/pkgconfig:/home/daniel/build-nghttp3/lib/pkgconfig:/home/daniel/build-ngtcp2/lib/pkgconfig LDFLAGS=-L/home/daniel/build-quictls/lib CFLAGS=-I/home/daniel/build-quictls/include ./configure --enable-maintainer-mode --prefix=/home/daniel/build-nghttp2 --disable-shared --enable-app --enable-http3 --without-jemalloc --without-libxml2 --without-systemd % make && make install</code></pre> <p>Run the local h3 server on port 9443, make it proxy all traffic through to HTTP/1 on localhost port 80. For local toying, we can just use the test cert that exists in curl's test dir.</p> <pre><code> % CERT=$CURLSRC/tests/stunnel.pem % $HOME/bin/nghttpx $CERT $CERT --backend=localhost,80 --frontend="localhost,9443;quic"</code></pre> <h3 id="caddy">Caddy</h3> <p><a href="https://caddyserver.com/docs/install">Install Caddy</a>. For easiest use, the binary should be either in your PATH or your current directory.</p> <p>Create a <code>Caddyfile</code> with the following content:</p> <pre><code>localhost:7443 { respond "Hello, world! you are using {http.request.proto}" }</code></pre> <p>Then run Caddy:</p> <pre><code> % ./caddy start</code></pre> <p>Making requests to <code>https://localhost:7443</code> should tell you which protocol is being used.</p> <p>You can change the hard-coded response to something more useful by replacing <code>respond</code> with <code>reverse_proxy</code> or <code>file_server</code>, for example: <code>reverse_proxy localhost:80</code></p> </div> </div> </body> </html>