Skip to content

Commit 08cb3ad

Browse files
kayx23pottekkatshreemaan-abhishek
authored
docs: add http3 docs (#11302)
Co-authored-by: Navendu Pottekkat <[email protected]> Co-authored-by: Abhishek Choudhary <[email protected]>
1 parent c2ba478 commit 08cb3ad

File tree

4 files changed

+380
-0
lines changed

4 files changed

+380
-0
lines changed

‎docs/en/latest/config.json

+4
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,10 @@
380380
{
381381
"type": "doc",
382382
"id": "ssl-protocol"
383+
},
384+
{
385+
"type": "doc",
386+
"id": "http3"
383387
}
384388
]
385389
},

‎docs/en/latest/http3.md

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: HTTP/3 Protocol
3+
---
4+
5+
<!--
6+
#
7+
# Licensed to the Apache Software Foundation (ASF) under one or more
8+
# contributor license agreements. See the NOTICE file distributed with
9+
# this work for additional information regarding copyright ownership.
10+
# The ASF licenses this file to You under the Apache License, Version 2.0
11+
# (the "License"); you may not use this file except in compliance with
12+
# the License. You may obtain a copy of the License at
13+
#
14+
# http://www.apache.org/licenses/LICENSE-2.0
15+
#
16+
# Unless required by applicable law or agreed to in writing, software
17+
# distributed under the License is distributed on an "AS IS" BASIS,
18+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
# See the License for the specific language governing permissions and
20+
# limitations under the License.
21+
#
22+
-->
23+
24+
[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) is the third major version of the Hypertext Transfer Protocol (HTTP). Unlike its predecessors which rely on TCP, HTTP/3 is based on [QUIC (Quick UDP Internet Connections) protocol](https://en.wikipedia.org/wiki/QUIC). It brings several benefits that collectively result in reduced latency and improved performance:
25+
26+
* enabling seamless transition between different network connections, such as switching from Wi-Fi to mobile data.
27+
* eliminating head-of-line blocking, so that a lost packet does not block all streams.
28+
* negotiating TLS versions at the same time as the TLS handshakes, allowing for faster connections.
29+
* providing encryption by default, ensuring that all data transmitted over an HTTP/3 connection is protected and confidential.
30+
* providing zero round-trip time (0-RTT) when communicating with servers that clients already established connections to.
31+
32+
APISIX currently supports HTTP/3 connections between downstream clients and APISIX. HTTP/3 connections with upstream services are not yet supported, and contributions are welcomed.
33+
34+
:::caution
35+
36+
This feature is currently experimental and not recommended for production use.
37+
38+
:::
39+
40+
This document will show you how to configure APISIX to enable HTTP/3 connections between client and APISIX and document a few known issues.
41+
42+
## Usage
43+
44+
### Enable HTTP/3 in APISIX
45+
46+
Enable HTTP/3 on port `9443` (or a different port) by adding the following configurations to APISIX's `config.yaml` configuration file:
47+
48+
```yaml title="config.yaml"
49+
apisix:
50+
ssl:
51+
listen:
52+
- port: 9443
53+
enable_http3: true
54+
ssl_protocols: TLSv1.3
55+
```
56+
57+
:::info
58+
59+
If you are deploying APISIX using Docker, make sure to allow UDP in the HTTP3 port, such as `-p 9443:9443/udp`.
60+
61+
:::
62+
63+
Then reload APISIX for configuration changes to take effect:
64+
65+
```shell
66+
apisix reload
67+
```
68+
69+
### Generate Certificates and Keys
70+
71+
HTTP/3 requires TLS. You can leverage the purchased certificates or self-generate them, whichever applicable.
72+
73+
To self-generate, first generate the certificate authority (CA) key and certificate:
74+
75+
```shell
76+
openssl genrsa -out ca.key 2048 && \
77+
openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \
78+
openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt
79+
```
80+
81+
Next, generate the key and certificate with a common name for APISIX, and sign with the CA certificate:
82+
83+
```shell
84+
openssl genrsa -out server.key 2048 && \
85+
openssl req -new -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \
86+
openssl x509 -req -days 36500 -sha256 -extensions v3_req \
87+
-CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \
88+
-in server.csr -out server.crt
89+
```
90+
91+
### Configure HTTPS
92+
93+
Optionally load the content stored in `server.crt` and `server.key` into shell variables:
94+
95+
```shell
96+
server_cert=$(cat server.crt)
97+
server_key=$(cat server.key)
98+
```
99+
100+
Create an SSL certificate object to save the server certificate and its key:
101+
102+
```shell
103+
curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT -d '
104+
{
105+
"id": "quickstart-tls-client-ssl",
106+
"sni": "test.com",
107+
"cert": "'"${server_cert}"'",
108+
"key": "'"${server_key}"'"
109+
}'
110+
```
111+
112+
### Create a Route
113+
114+
Create a sample route to `httpbin.org`:
115+
116+
```shell
117+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
118+
{
119+
"id":"httpbin-route",
120+
"uri":"/get",
121+
"upstream": {
122+
"type":"roundrobin",
123+
"nodes": {
124+
"httpbin.org:80": 1
125+
}
126+
}
127+
}'
128+
```
129+
130+
### Verify HTTP/3 Connections
131+
132+
Install [static-curl](https://github.com/stunnel/static-curl) or any other curl executable that has HTTP/3 support.
133+
134+
Send a request to the route:
135+
136+
```shell
137+
curl -kv --http3-only \
138+
-H "Host: test.com" \
139+
--resolve "test.com:9443:127.0.0.1" "https://test.com:9443/get"
140+
```
141+
142+
You should receive an `HTTP/3 200` response similar to the following:
143+
144+
```text
145+
* Added test.com:9443:127.0.0.1 to DNS cache
146+
* Hostname test.com was found in DNS cache
147+
* Trying 127.0.0.1:9443...
148+
* QUIC cipher selection: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
149+
* Skipped certificate verification
150+
* Connected to test.com (127.0.0.1) port 9443
151+
* using HTTP/3
152+
* [HTTP/3] [0] OPENED stream for https://test.com:9443/get
153+
* [HTTP/3] [0] [:method: GET]
154+
* [HTTP/3] [0] [:scheme: https]
155+
* [HTTP/3] [0] [:authority: test.com]
156+
* [HTTP/3] [0] [:path: /get]
157+
* [HTTP/3] [0] [user-agent: curl/8.7.1]
158+
* [HTTP/3] [0] [accept: */*]
159+
> GET /get HTTP/3
160+
> Host: test.com
161+
> User-Agent: curl/8.7.1
162+
> Accept: */*
163+
>
164+
* Request completely sent off
165+
< HTTP/3 200
166+
...
167+
{
168+
"args": {},
169+
"headers": {
170+
"Accept": "*/*",
171+
"Content-Length": "0",
172+
"Host": "test.com",
173+
"User-Agent": "curl/8.7.1",
174+
"X-Amzn-Trace-Id": "Root=1-6656013a-27da6b6a34d98e3e79baaf5b",
175+
"X-Forwarded-Host": "test.com"
176+
},
177+
"origin": "172.19.0.1, 123.40.79.456",
178+
"url": "http://test.com/get"
179+
}
180+
* Connection #0 to host test.com left intact
181+
```
182+
183+
## Known Issues
184+
185+
- For APISIX-3.9, test cases of Tongsuo will fail because the Tongsuo does not support QUIC TLS.
186+
- APISIX-3.9 is based on NGINX-1.25.3 with vulnerabilities in HTTP/3 (CVE-2024-24989, CVE-2024-24990).

‎docs/zh/latest/config.json

+4
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,10 @@
325325
{
326326
"type": "doc",
327327
"id": "ssl-protocol"
328+
},
329+
{
330+
"type": "doc",
331+
"id": "http3"
328332
}
329333
]
330334
},

‎docs/zh/latest/http3.md

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: HTTP3 协议
3+
---
4+
5+
<!--
6+
#
7+
# Licensed to the Apache Software Foundation (ASF) under one or more
8+
# contributor license agreements. See the NOTICE file distributed with
9+
# this work for additional information regarding copyright ownership.
10+
# The ASF licenses this file to You under the Apache License, Version 2.0
11+
# (the "License"); you may not use this file except in compliance with
12+
# the License. You may obtain a copy of the License at
13+
#
14+
# http://www.apache.org/licenses/LICENSE-2.0
15+
#
16+
# Unless required by applicable law or agreed to in writing, software
17+
# distributed under the License is distributed on an "AS IS" BASIS,
18+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
# See the License for the specific language governing permissions and
20+
# limitations under the License.
21+
#
22+
-->
23+
24+
[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) 是 Hypertext Transfer Protocol(HTTP) 的第三个主要版本。与依赖 TCP 的前辈不同，HTTP/3 基于 [QUIC (Quick UDP Internet Connections) protocol](https://en.wikipedia.org/wiki/QUIC)。它带来了多项好处，减少了延迟并提高了性能：
25+
26+
* 实现不同网络连接之间的无缝过渡，例如从 Wi-Fi 切换到移动数据。
27+
* 消除队头阻塞，以便丢失的数据包不会阻塞所有流。
28+
* 在 TLS 握手的同时协商 TLS 版本，从而实现更快的连接。
29+
* 默认提供加密，确保通过 HTTP/3 连接传输的所有数据都受到保护和保密。
30+
* 在与客户端已建立连接的服务器通信时提供零往返时间 (0-RTT)。
31+
32+
APISIX 目前支持下游客户端和 APISIX 之间的 HTTP/3 连接。尚不支持与上游服务的 HTTP/3 连接。欢迎社区贡献。
33+
34+
:::caution
35+
36+
此功能尚未经过大规模测试，因此不建议用于生产使用。
37+
38+
:::
39+
40+
本文档将向您展示如何配置 APISIX 以在客户端和 APISIX 之间启用 HTTP/3 连接，并记录一些已知问题。
41+
42+
## 使用示例
43+
44+
### 启用 HTTP/3
45+
46+
将以下配置添加到 APISIX 的配置文件。该配置将在端口 `9443`（或其他端口）上启用 HTTP/3：
47+
48+
```yaml title="config.yaml"
49+
apisix:
50+
ssl:
51+
listen:
52+
- port: 9443
53+
enable_http3: true
54+
ssl_protocols: TLSv1.3
55+
```
56+
57+
:::info
58+
59+
如果您使用 Docker 部署 APISIX，请确保在 HTTP3 端口中允许 UDP，例如 `-p 9443:9443/udp`。
60+
61+
:::
62+
63+
然后重新加载 APISIX 以使配置更改生效：
64+
65+
```shell
66+
apisix reload
67+
```
68+
69+
### 生成证书和密钥
70+
71+
HTTP/3 需要 TLS。您可以利用购买的证书或自行生成证书。
72+
73+
如自行生成，首先生成证书颁发机构 (CA) 密钥和证书：
74+
75+
```shell
76+
openssl genrsa -out ca.key 2048 && \
77+
openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \
78+
openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt
79+
```
80+
81+
接下来，生成具有 APISIX 通用名称的密钥和证书，并使用 CA 证书进行签名：
82+
83+
```shell
84+
openssl genrsa -out server.key 2048 && \
85+
openssl req -new -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \
86+
openssl x509 -req -days 36500 -sha256 -extensions v3_req \
87+
-CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \
88+
-in server.csr -out server.crt
89+
```
90+
91+
### 配置 HTTPS
92+
93+
可选择性地将存储在 `server.crt` 和 `server.key` 中的内容加载到环境变量中：
94+
95+
```shell
96+
server_cert=$(cat server.crt)
97+
server_key=$(cat server.key)
98+
```
99+
100+
创建一个保存服务器证书及其密钥的 SSL 对象：
101+
102+
```shell
103+
curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT -d '
104+
{
105+
"id": "quickstart-tls-client-ssl",
106+
"sni": "test.com",
107+
"cert": "'"${server_cert}"'",
108+
"key": "'"${server_key}"'"
109+
}'
110+
```
111+
112+
### 创建路由
113+
114+
创建一个路由至 `httpbin.org`:
115+
116+
```shell
117+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
118+
{
119+
"id":"httpbin-route",
120+
"uri":"/get",
121+
"upstream": {
122+
"type":"roundrobin",
123+
"nodes": {
124+
"httpbin.org:80": 1
125+
}
126+
}
127+
}'
128+
```
129+
130+
### 验证 HTTP/3 连接
131+
132+
验证前需要安装支持 HTTP/3 的 curl，如 [static-curl](https://github.com/stunnel/static-curl) 或其他支持 HTTP/3 的 curl。
133+
134+
发送一个请求到路由：
135+
136+
```shell
137+
curl -kv --http3-only \
138+
-H "Host: test.com" \
139+
--resolve "test.com:9443:127.0.0.1" "https://test.com:9443/get"
140+
```
141+
142+
应收到 `HTTP/3 200` 相应如下：
143+
144+
```text
145+
* Added test.com:9443:127.0.0.1 to DNS cache
146+
* Hostname test.com was found in DNS cache
147+
* Trying 127.0.0.1:9443...
148+
* QUIC cipher selection: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
149+
* Skipped certificate verification
150+
* Connected to test.com (127.0.0.1) port 9443
151+
* using HTTP/3
152+
* [HTTP/3] [0] OPENED stream for https://test.com:9443/get
153+
* [HTTP/3] [0] [:method: GET]
154+
* [HTTP/3] [0] [:scheme: https]
155+
* [HTTP/3] [0] [:authority: test.com]
156+
* [HTTP/3] [0] [:path: /get]
157+
* [HTTP/3] [0] [user-agent: curl/8.7.1]
158+
* [HTTP/3] [0] [accept: */*]
159+
> GET /get HTTP/3
160+
> Host: test.com
161+
> User-Agent: curl/8.7.1
162+
> Accept: */*
163+
>
164+
* Request completely sent off
165+
< HTTP/3 200
166+
...
167+
{
168+
"args": {},
169+
"headers": {
170+
"Accept": "*/*",
171+
"Content-Length": "0",
172+
"Host": "test.com",
173+
"User-Agent": "curl/8.7.1",
174+
"X-Amzn-Trace-Id": "Root=1-6656013a-27da6b6a34d98e3e79baaf5b",
175+
"X-Forwarded-Host": "test.com"
176+
},
177+
"origin": "172.19.0.1, 123.40.79.456",
178+
"url": "http://test.com/get"
179+
}
180+
* Connection #0 to host test.com left intact
181+
```
182+
183+
## 已知问题
184+
185+
- 对于 APISIX-3.9, Tongsuo 相关测试用例会失败，因为 Tongsuo 不支持 QUIC TLS。
186+
- APISIX-3.9 基于 NGINX-1.25.3，存在 HTTP/3 漏洞（CVE-2024-24989、CVE-2024-24990）。

0 commit comments

Comments
 (0)