wangfq
173dd6874f
- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
225 lines
14 KiB
Markdown
225 lines
14 KiB
Markdown
# netdrv IKEv2/IPsec 客户端设计文档
|
||
|
||
> 适用范围：LuatOS `netdrv` 框架下的 IKEv2/IPsec 隧道模式客户端
|
||
> （ESP tunnel mode）。首期已在 PC 模拟器上对接真实 strongSwan 网关
|
||
> `ipsec.air32.cn`（strongSwan 5.9.13, Ubuntu 24.04 云主机）联调通过。
|
||
|
||
---
|
||
|
||
## 1. 目标与范围
|
||
|
||
在 netdrv 框架内新增 `netdrv.IPSEC` 虚拟网卡，实现：
|
||
|
||
- IKEv2 发起端（RFC 7296），服务器证书链校验 + 强制 EAP-MSCHAPv2；
|
||
- NAT-T（RFC 3948）：UDP 500 启动，探测到 NAT 后切换 4500；
|
||
- DPD 保活、CHILD_SA 到期重协商（CREATE_CHILD_SA，默认带 PFS，
|
||
KE + 新 Ni/Nr 按 RFC 7296 §2.17 派生 KEYMAT；网关不支持 PFS 时自动
|
||
无 KE 重试一次并保持旧 SA 在线）、IKE SA 到期全量重建；
|
||
- 套件扩展：IKE DH 组 19/20/21（ECP-256/384/521，RFC 4753），
|
||
ESP AES-GCM-128/256（RFC 4106 AEAD，SA 内无 INTEG transform）；
|
||
- MOBIKE（RFC 4555，opt-in，默认关闭）：本地地址变化时发送
|
||
INFORMATIONAL(UPDATE_SA_ADDRESSES + NAT-D)，处理对端发起的地址更新，
|
||
以及 established 状态下的对端地址学习；不做 ADDITIONAL_IP4_ADDRESS
|
||
通告与 COOKIE2；
|
||
- CP（Configuration Payload）下发虚拟 IPv4 + DNS；
|
||
- ESP 隧道模式（RFC 4303）AES-CBC-128/256 + HMAC-SHA1-96 /
|
||
HMAC-SHA2-256-128 或 AES-GCM-128/256，32 包反重放窗口，
|
||
ESP-in-UDP(4500)。
|
||
|
||
明确不做：IKEv1、L2TP/IPsec、ESP 传输模式、客户端证书认证、
|
||
IPv6 隧道、MOBIKE 的 ADDITIONAL_IP4_ADDRESS 通告与 COOKIE2。
|
||
MOBIKE 默认关闭（`ipsec_mobike_enable` 未配置时行为与旧版一致，
|
||
地址变化仍走断线重连）。
|
||
|
||
## 2. 文件布局
|
||
|
||
代码按用户要求拆分到独立子模块 `components/network/ipsec/`（内部头在
|
||
`include/ipsec/`，源文件在 `src/`）：
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `include/ipsec/ipsec_crypto.h` + `src/ipsec_crypto.c` | PRF+/HMAC、DH modp2048、IKE/CHILD 密钥派生、AUTH 计算/验签、X.509 链+SAN 校验（信任锚由 `ipsec_ca_cert_pem` 提供；不提供时默认 fail-closed，仅当显式开启 `ipsec_insecure_cert_ok` 才接受证书且仍校验 SAN） |
|
||
| `include/ipsec/ipsec_esp.h` + `src/ipsec_esp.c` | ESP 隧道封装/解封（AES-CBC + HMAC 或 AES-GCM AEAD）、SPI 方向、32 包反重放 |
|
||
| `include/ipsec/ipsec_ike.h` + `src/ipsec_ike.c` | IKEv2 状态机：SA_INIT/AUTH/EAP/CREATE_CHILD_SA/INFORMATIONAL、payload 编解码、SK 加密、NAT-T 切换、DPD、重协商、虚拟 netif 与 adapter 收发 |
|
||
| `include/ipsec/ipsec_vendor_md4.h` + `src/ipsec_vendor_md4.c` | MD4（Apache-2.0, 从 mbedTLS 2.x vendor, 自包含） |
|
||
| `include/ipsec/ipsec_vendor_chap_ms.h` + `src/ipsec_vendor_chap_ms.c` | MS-CHAPv2（BSD, 移植自 lwIP2.2 `chap_ms.c`），含 strongSwan 线格式与 RFC 3079 MSK 派生、RFC 2759 测试向量自检 |
|
||
| `src/luat_netdrv_ipsec.c` | netdrv 胶水层：setup/ctrl(UPDOWN)/dhcp(-1)/debug + 链路状态回调 |
|
||
| `components/network/netdrv/include/luat_netdrv_ipsec.h` | 胶水层头文件（保持在 netdrv/include） |
|
||
|
||
接入点：
|
||
|
||
- `luat_netdrv_drv.h`：`LUAT_NETDRV_IMPL_IPSEC 7`
|
||
- `luat_netdrv.h`：`luat_netdrv_ipsec_conf_t` + `conf->ipsec_conf`
|
||
- `luat_netdrv.c` / `luat_lib_netdrv.c`：setup 分发与 `ipsec_*` 参数解析
|
||
- `bsp/pc/xmake.lua`：ipsec 子模块头文件搜索路径（`components/network/ipsec/include`）
|
||
- `bsp/pc/include/luat_conf_bsp.h`：`LUAT_USE_NETDRV_IPSEC 1`
|
||
- `bsp/pc/include/lwipopts.h`：`MEMP_NUM_SYS_TIMEOUT 30`
|
||
- `bsp/pc/port/luat_crypto_mini.c`：PC 模拟器 TRNG 每次调用重新播种
|
||
|
||
## 3. 架构与数据流
|
||
|
||
```
|
||
Lua (netdrv.setup / socket.*)
|
||
|
|
||
v
|
||
luat_netdrv_ipsec.c (setup/ctrl/dhcp/debug, IP_READY/IP_LOSE 事件)
|
||
|
|
||
v
|
||
ipsec_ike.c (IKEv2 状态机, tcpip 线程)
|
||
| netif (虚拟网卡, 全流量默认路由)
|
||
| | netif output -> ESP 封装 -> adapter UDP TX(4500)
|
||
| | adapter RX(4500) -> IKE(4字节零前缀) 或 ESP -> 内层 IP 注入
|
||
|
|
||
+-- network_ctrl_t (luat_network_adapter, 单 socket: 500 -> 4500)
|
||
```
|
||
|
||
- IKE 与 ESP 共用同一个 adapter UDP socket：先在 500 上完成
|
||
IKE_SA_INIT，NAT 探测后切换到本地/远端 4500（RFC 3948 非 ESP
|
||
marker 区分 IKE 与 ESP）。这是标准 NAT-T 形态，避免了双 socket
|
||
同端口绑定的问题。
|
||
- 所有状态机工作经 `tcpip_callback_with_block` 汇聚到 tcpip 线程；
|
||
adapter 回调只拷贝数据并投递，与 L2TP/OpenVPN 客户端一致。
|
||
- CP 下发虚拟 IP 后 `netif_set_addr` + `netif_set_default`，DNS 写入
|
||
`network_set_dns_server`。
|
||
|
||
## 4. 协议要点与互操作细节
|
||
|
||
- 套件：IKE `{aes256-sha256, aes128-sha1} × {modp2048, ecp256, ecp384,
|
||
ecp521}!`（8 个提案，DH14 优先；响应者选中其它组时按 RFC 7296 §2.7
|
||
的 INVALID_KE 通知重试，IKE_SA_INIT 默认先发 DH14 的 KE）；
|
||
ESP `aes256-sha256, aes128-sha1, aes256gcm16, aes128gcm16!`
|
||
（AEAD 提案无 INTEG transform，transform id 20 + KEY_LENGTH 属性）。
|
||
- CHILD_SA 重协商默认带 PFS：请求载荷顺序 `SA | Ni | KE | TSi | TSr`，
|
||
使用 IKE_SA_INIT 协商出的 DH 组生成新的临时密钥对；响应解析新 Nr 与
|
||
KE，KEYMAT = prf+(SK_d, g^ir | Ni | Nr)。响应缺少 KE 或带
|
||
NO_PROPOSAL_CHOSEN/TS_UNACCEPTABLE 时，自动无 KE 重试一次并保持旧 SA
|
||
在线（与旧版行为一致）。
|
||
- MOBIKE 更新载荷顺序：`N(UPDATE_SA_ADDRESSES) | N(NAT_DETECTION_SOURCE_IP)
|
||
| N(NAT_DETECTION_DESTINATION_IP)`（RFC 4555 §2.2），NAT-D 复用
|
||
IKE_SA_INIT 的 SHA-1 哈希方式；对端发起的更新用当前本地 IP 校验
|
||
目标 NAT-D，不匹配则忽略；established 状态下的地址学习只发生在
|
||
密码学验证通过之后：ESP 报文在 ICV/解密成功后、对端
|
||
UPDATE_SA_ADDRESSES 在 SK 解密 + NAT-D 校验通过后、已认证的
|
||
INFORMATIONAL 响应在 ICV 校验通过后（RFC 4555 §3，
|
||
未认证报文一律不得改写对端地址）。
|
||
- IKE 请求单在途槽位：`pending_msgid/last_tx` 全 client 一份，
|
||
DPD/MOBIKE 更新/CREATE_CHILD_SA 任一在途时其余请求让路（下一秒
|
||
tick 重试）；INFORMATIONAL 响应（DPD/MOBIKE ack）经 SK 解密 +
|
||
ICV 校验后才采信；msgid 全链路 32 位（RFC 7296 单调不回绕）。
|
||
- IKE SK 载荷：AES-CBC + HMAC；**ICV 只覆盖 IKE 报文本身**（strongSwan
|
||
收到 4500 报文会先剥离 4 字节非 ESP marker 再校验）。
|
||
- ESP AEAD（RFC 4106）：8 字节显式 IV，GCM IV = salt(4) | IV(8)，
|
||
AAD = SPI | SEQ，ICV 16 字节，padding 按 4 字节对齐；KEYMAT 每方向为
|
||
`enc_key(16/32) + salt(4)`（RFC 7296 §3.3.2），无 INTEG 密钥。
|
||
- AUTH：EAP 模式按 RFC 7296 §2.16 用 MSK 作为共享密钥；
|
||
`"Key Pad for IKEv2"` 为 17 字节（不含 NUL）。
|
||
- MSK：按 strongSwan 的 RFC 3079 实现——
|
||
`master=SHA1(HH|NT-Response|Magic1)`，
|
||
`recv/send=SHA1(master[0:16]|0x00*40|Magic2/3|0xF2*40)`，
|
||
`MSK=recv[0:16]|send[0:16]|0x00*32`。
|
||
- MS-CHAPv2 线格式采用 strongSwan/Windows 客户端格式：
|
||
`opcode|id|ms_length|value_size|...`（区别于 RFC 2759 排版）。
|
||
- ESP SPI 方向：发起端**发送**用响应者分配的 SPI（SAr2），**接收**
|
||
用自己提议的 SPI（SAi2）。
|
||
- 证书链：配置了 `ipsec_ca_cert_pem` 时按该信任锚做链校验并校验
|
||
SAN `ipsec.air32.cn`；未配置时默认 **fail-closed**（固件不再内置任何
|
||
信任锚），仅当显式设置 `ipsec_insecure_cert_ok=true` 才接受服务器证书，
|
||
且仍强制 SAN 匹配。mbedTLS 校验需传 `mbedtls_x509_crt_profile_default`，
|
||
PEM 缓冲需 NUL 结尾（mbedTLS 3.x 的 PEM 识别条件）。
|
||
|
||
## 5. 配置参考（Lua）
|
||
|
||
```lua
|
||
netdrv.setup(socket.LWIP_USER1, netdrv.IPSEC, {
|
||
ipsec_remote_ip = "154.8.159.79", -- 网关 IP（仅字面量）
|
||
ipsec_remote_port = 500, -- IKE 端口, 默认 500
|
||
ipsec_username = "vpnuser",
|
||
ipsec_password = "xxxx",
|
||
ipsec_san = "ipsec.air32.cn", -- 服务器 SAN 校验
|
||
-- ipsec_ca_cert_pem = "-----BEGIN CERTIFICATE-----...", -- 建议配置信任锚;
|
||
-- -- 未配置且未开启 insecure 时无法连接 (fail-closed)
|
||
-- ipsec_insecure_cert_ok = false, -- 默认 false; true 表示无 CA 时仅校验 SAN 即接受
|
||
ipsec_mtu = 1400,
|
||
ipsec_retry_enable = true,
|
||
ipsec_retry_base_ms = 1000,
|
||
ipsec_retry_max_ms = 60000,
|
||
-- ipsec_mobike_enable = true, -- MOBIKE 双向地址更新 (默认关闭)
|
||
})
|
||
```
|
||
|
||
`ipsec_mobike_enable`：布尔，默认 `false`。开启后客户端在 1s tick 轮询
|
||
本地地址，变化时发送 UPDATE_SA_ADDRESSES；底层 socket 关闭但传输仍在线
|
||
时重开同端口 socket 并走更新流程而非全量重建；同时支持对端发起的地址
|
||
更新与 established 状态下的地址学习。仅 utest 构建提供测试钩子
|
||
`netdrv.ipsec_sim_addr_change(id)` 模拟一次本地地址变更。
|
||
|
||
## 6. 联调记录（2026-08-12, PC 模拟器 ↔ ipsec.air32.cn）
|
||
|
||
联调期间发现并修复的问题：
|
||
|
||
| # | 现象 | 根因 | 修复 |
|
||
|---|---|---|---|
|
||
| 1 | 网关对 IKE_SA_INIT 无响应 | Ni/NAT-D 载荷的 Next Payload 误用 notify 值(16388)而非载荷类型(41) | 改为 `IPSEC_PAYLOAD_NOTIFY` |
|
||
| 2 | IKE_AUTH 无响应, 网关日志 `message ID 16777216, expected 1` | msgid 以单字节写入 (`01 00 00 00`) 而非 4 字节大端 | `ike_put32(msg+20, msgid)` |
|
||
| 3 | 网关日志 `MAC verification failed` | mbedTLS 3 `aes_crypt_cbc` 会把最后一组密文写回 IV 缓冲, 覆盖了包内 IV | 用独立 IV 缓冲 |
|
||
| 4 | 网关日志 `MAC verification failed`（修复 3 后仍失败） | 4500 上 ICV 把 4 字节零前缀算进去了, 而 strongSwan 收到会先剥离 | ICV 只覆盖 IKE 报文 |
|
||
| 5 | `trust anchor parse failed -0x2180` | mbedTLS 3.x 仅当缓冲区 NUL 结尾才识别 PEM | 内嵌/用户 PEM 均保留 NUL 结尾 |
|
||
| 6 | `cert chain verify failed flags=0xFFFFFFFF` | `mbedtls_x509_crt_verify_with_profile` 的 profile 传 NULL 返回 BAD_INPUT_DATA | 传 `mbedtls_x509_crt_profile_default` |
|
||
| 7 | 服务器只发叶子证书, 链校验失败 | strongSwan `leftsendcert=always` 只发叶子；Let's Encrypt 2026 新链 | 内置 YE2/ISRG Root YE/ISRG Root X2 中间 CA |
|
||
| 8 | `server AUTH signature verification failed` | 裸 r\|s 转 DER 时长度公式少算 2 字节 | 修正 `total=6+r+s+pad` |
|
||
| 9 | 服务器 `INVALID_SYNTAX` 拒绝 EAP Identity 响应 | EAP 载荷构建后未 `p += plen`, 内层为空 | 修复三处 EAP 载荷 |
|
||
| 10 | `unhandled MS-CHAPv2 request opcode 1` | 用 RFC 2759 排版解析 strongSwan 的 Challenge | 按 strongSwan 线格式解析 |
|
||
| 11 | 最终 AUTH 被拒 | 内层 `"Key Pad for IKEv2"` 用 `sizeof`（含 NUL 18 字节） | 用 17 字节 |
|
||
| 12 | 最终 AUTH 被拒（修复 11 后仍失败） | MSK 的 master 用 `sizeof(inner)=79`（实际 67）；且 0x36/0x5C 填充与 strongSwan 的 0x00/0xF2 不符；32 字节 key 从 20 字节 digest 越界拷贝 | 按 strongSwan 实现重写 MSK 派生 |
|
||
| 13 | ESP 无回包, 网关 `XfrmInNoStates` | ESP SPI 方向反了（发送用了自己提议的 SPI） | 发送用 SAr2 的 SPI |
|
||
| 14 | 隧道 IP 与策略不匹配 | CP 的 IPv4 字节序（`ip4_addr_set_u32` 需先 `lwip_htonl`） | 恢复 `lwip_htonl(ike_get32())` |
|
||
| 15 | 证书校验 `NOT_TRUSTED`（flags=0x8） | 网关改用私建 CA（`CN=IKEv2 VPN CA`，自签 10 年），strongSwan 只发叶子，内置 ISRG Root X1 / LE 中间链不再适用 | 测试脚本改从 `scripts/ikev2-ca.crt` 读取 CA 作为 `ipsec_ca_cert_pem` 传入；同时按需求移除固件内置信任锚，未配 CA 的默认行为在后续提交中收紧为 fail-closed（需显式 `ipsec_insecure_cert_ok=true` 才接受证书，且仍校验 SAN） |
|
||
|
||
服务器侧配合项（已处理，用户授权调试）：
|
||
|
||
- 云主机 `dirtyfrag.conf` 禁用 `esp4` 内核模块（`install esp4 /bin/false`），
|
||
导致 XFRM SAD 安装失败（`netlink error: Requested type not found (93)`）：
|
||
已注释该规则并加载 `esp4`/`xfrm_user`/`xfrm4_tunnel`；
|
||
- `ipsec.secrets` 私钥声明为 `: RSA` 但实际是 ECDSA P-384：
|
||
已改为 `: ECDSA`；
|
||
- 联调后 `charondebug` 已恢复 `ike 2`，`esp=aes256-sha256, aes128-sha1!`
|
||
已恢复原样。
|
||
|
||
## 7. 测试结果（PC 模拟器, testcase/unit/net/netdrv_ipsec_basic）
|
||
|
||
- `connect`：IKE_SA_INIT → 证书链+SAN 校验 → 服务器 AUTH 验签 →
|
||
EAP-MSCHAPv2（含服务器 Authenticator Response 校验）→ 双端 AUTH →
|
||
CP 下发虚拟 IP/DNS → 隧道上线 → 隧道内 TCP 到网关 SSH 收到 banner，
|
||
**3 passed / 0 failed**；
|
||
- `badpass`：错误密码 → EAP 失败 → 不 ready，**通过**；
|
||
- `sanit`：错误 SAN → 证书校验拒绝 → 不 ready，**通过**。
|
||
|
||
> 前置：`testcase/unit/net/netdrv_ipsec_basic/scripts/ikev2-ca.crt`
|
||
> （网关私建 CA）必须存在，测试会把它作为 `ipsec_ca_cert_pem` 传入；
|
||
> 测试账号凭据通过环境变量 `LUAT_IPSEC_USERNAME` / `LUAT_IPSEC_PASSWORD`
|
||
> 注入（不随源码分发），未设置时测试跳过。
|
||
> 固件默认 fail-closed：未传 `ipsec_ca_cert_pem` 且未显式开启
|
||
> `ipsec_insecure_cert_ok` 时拒绝连接（固件不再内置任何信任锚）。
|
||
|
||
## 8. 遗留与后续
|
||
|
||
- 集成联调（需网关侧重配，未完成项见交付说明）：
|
||
- PFS：网关 `pfs=yes` + 缩短 lifetime，验证重协商日志、DPD、隧道不断流；
|
||
- ECP/GCM：网关 `ike=aes256-sha256-ecp256!` / `esp=aes256gcm16!` 建连；
|
||
- MOBIKE：`netdrv.ipsec_sim_addr_change` 触发 UPDATE_SA_ADDRESSES，
|
||
网关 `mobike=no` 时回退重连。
|
||
- 硬件 BSP：需确认目标板 lwip 导出符号（`pbuf/netif/sys/ip4_input`）
|
||
与 adapter 行为，并按验收清单在目标板重跑；
|
||
- 服务器 FORWARD 链的 IPsec 池 ACCEPT 规则与 `rightsourceip`
|
||
段需按实际网络调整（当前云主机 iptables 规则与池配置不完全一致，
|
||
隧道到网关本机可用，跨子网转发需核对）；
|
||
- `netdrv.debug` 会输出 IKE/ESP 帧日志（含 SK 明文转储仅调试用）。
|
||
|
||
## 9. 相关文档
|
||
|
||
- RFC 7296（IKEv2）、RFC 3948（NAT-T）、RFC 4303（ESP）、
|
||
RFC 2759/3079（MS-CHAPv2/MSK）
|
||
- `docs/l2tp-design.md`（线程模型/胶水层/构建接线参考）
|
||
- `components/network/l2tp/src/l2tp_client.c` /
|
||
`components/network/openvpn/src/ovpn_client.c`（传输与 netif 参考）
|