mirror of
https://github.com/curl/curl.git
synced 2026-06-02 14:44:15 +03:00
e78b1b3ecc
This patch adds two major proxy capabilities to curl (ngtcp2 QUIC):
- HTTP/3 Proxy CONNECT: Tunnel HTTP/1.1 or HTTP/2 traffic through an
HTTPS proxy that speaks HTTP/3 (QUIC) using the standard CONNECT
method over an HTTP/3 connection.
- MASQUE CONNECT-UDP: Tunnel HTTP/3 (QUIC) traffic through an HTTP
proxy (speaking HTTP/1.1, HTTP/2, or HTTP/3) using the extended
CONNECT method with the CONNECT-UDP protocol (RFC9297 & RFC9298).
Public API additions:
- `CURLPROXY_HTTPS3`: new proxy type constant for HTTP/3 proxy
- `--proxy-http3`: new CLI flag to negotiate HTTP/3 with HTTPS proxy
The implementation adds two new filters:
- `H3-PROXY` - enables negotiating HTTP/3 (QUIC) to the proxy and
running CONNECT/CONNECT-UDP through that proxy transport.
- `CAPSULE` - dedicated filter inserted between QUIC transport and
HTTP-PROXY to handle datagram capsule encapsulation/decapsulation.
Here is how the curl filter chaining looks in different scenarios:
- HTTP/3 Proxy CONNECT (tunneling TCP protocols over QUIC proxy):
conn -> HTTP/1.1 or HTTP/2 -> SSL -> HTTP-PROXY ->
H3-PROXY -> HAPPY-EYEBALLS -> UDP
- MASQUE CONNECT-UDP (tunneling QUIC over any proxy):
conn -> HTTP/3 -> CAPSULE -> HTTP-PROXY -> H3-PROXY ->
HAPPY-EYEBALLS -> UDP
conn -> HTTP/3 -> CAPSULE -> HTTP-PROXY -> H1-PROXY or H2-PROXY ->
SSL -> HAPPY-EYEBALLS -> TCP
- Both features currently require the ngtcp2 QUIC backend.
- Both features are experimental (disabled by default). Enable with
`--enable-proxy-http3`(autotools) or `-DUSE_PROXY_HTTP3=ON`(CMake).
Tests:
- tests/unit/unit3400.c: Unit tests for capsule protocol encode/decode
- tests/http/test_60_h3_proxy.py: Comprehensive pytest integration suite
- tests/http/testenv/h2o.py: Managing h2o instances with HTTP/1.1, HTTP/2,
and HTTP/3 (QUIC) listeners, proxy.connect and proxy.connect-udp enabled.
References:
RFC 9297 - HTTP Datagrams and the Capsule Protocol
RFC 9298 - Proxying UDP in HTTP
RFC 9000 §16 — Variable-Length Integer Encoding
Signed-off-by: Aritra Basu <aritrbas+gh@cisco.com>
Closes #21153
100 lines
3 KiB
Markdown
100 lines
3 KiB
Markdown
<!--
|
|
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
|
|
SPDX-License-Identifier: curl
|
|
-->
|
|
|
|
# Experimental
|
|
|
|
Some features and functionality in curl and libcurl are considered
|
|
**EXPERIMENTAL**.
|
|
|
|
Experimental support in curl means:
|
|
|
|
1. Experimental features are provided to allow users to try them out and
|
|
provide feedback on functionality and API etc before they ship and get
|
|
"carved in stone".
|
|
2. You must enable the feature when invoking configure as otherwise curl is
|
|
not built with the feature present.
|
|
3. We strongly advise against using this feature in production.
|
|
4. **We reserve the right to change behavior** of the feature without sticking
|
|
to our API/ABI rules as we do for regular features, as long as it is marked
|
|
experimental.
|
|
5. Experimental features are clearly marked so in documentation. Beware.
|
|
|
|
## Graduation
|
|
|
|
1. Each experimental feature should have a set of documented requirements of
|
|
what is needed for that feature to graduate. Graduation means being removed
|
|
from the list of experiments.
|
|
2. An experiment should NOT graduate if it needs test cases to be disabled,
|
|
unless they are for minor features that are clearly documented as not
|
|
provided by the experiment and then the disabling should be managed inside
|
|
each affected test case.
|
|
|
|
## Experimental features right now
|
|
|
|
### HTTP/3 support (non-ngtcp2 backends)
|
|
|
|
Graduation requirements:
|
|
|
|
- The used libraries should be considered out-of-beta with a reasonable
|
|
expectation of a stable API going forward.
|
|
|
|
- Using HTTP/3 with the given build should perform without risking busy-loops
|
|
|
|
### HTTP/3 proxy and CONNECT-UDP support
|
|
|
|
Support for HTTP/3 proxy and CONNECT-UDP tunneling is experimental and
|
|
requires an explicit build-time opt-in (`--enable-proxy-http3` for
|
|
autotools, `-DUSE_PROXY_HTTP3=ON` for CMake).
|
|
|
|
Graduation requirements:
|
|
|
|
- implementation stability over time with no known severe regressions
|
|
|
|
### The Rustls backend
|
|
|
|
Graduation requirements:
|
|
|
|
- a reasonable expectation of a stable API going forward.
|
|
|
|
## ECH
|
|
|
|
Use of the HTTPS resource record and Encrypted Client Hello (ECH) when using
|
|
DoH
|
|
|
|
Graduation requirements:
|
|
|
|
- ECH support exists in at least one widely used TLS library apart from
|
|
BoringSSL and wolfSSL.
|
|
|
|
- feedback from users saying that ECH works for their use cases
|
|
|
|
- it has been given time to mature, so no earlier than April 2025 (twelve
|
|
months after being added here)
|
|
|
|
## SSL session import/export
|
|
|
|
Import/Export of SSL sessions tickets in libcurl and curl command line
|
|
option '--ssl-session <filename>' for faster TLS handshakes and use
|
|
of TLSv1.3/QUIC Early Data (0-RTT).
|
|
|
|
Graduation requirements:
|
|
|
|
- the implementation is considered safe
|
|
|
|
- feedback from users saying that session export works for their use cases
|
|
|
|
## HTTPS RR
|
|
|
|
HTTPS records support is a requirement for ECH but is provided as a
|
|
stand-alone feature that is itself considered EXPERIMENTAL.
|
|
|
|
Graduation requirements:
|
|
|
|
- HTTPS records work for DoH, c-ares and the threaded resolver
|
|
|
|
- HTTPS records can control ALPN and port number, at least
|
|
|
|
- There are options to control HTTPS use
|