PazeSSH/AGENT.MD

AGENT.md — 接手指南

项目结构

include/paze/        公共头文件（tls.h 对外 API）
src/crypto/          密码学原语：哈希/AES/ChaCha20/Poly1305/AEAD/X25519/Ed25519/bignum/RSA/P-256/KDF/ASN.1/X.509
src/ssl/             TLS 1.2+1.3：tls_record(记录层) tls_keys(key schedule) tls_extensions(扩展)
                     tls_handshake13/12(状态机) tls_transcript tls_conn(API/生命周期) tls_client/server(入口)
src/ssh/             SSH-2：transport/kex/auth/channel/client/server/sftp
src/util/            内存/字节序/错误/日志
apps/                命令行：pazessl / pssh(分发) / 独立命令(pscp/pkeygen/psshd/psftp…)
build/               中间产物(编译)/测试脚本/互操作脚本
bin/                 构建输出(exe)
STATUS.md            完成度总表    AGENT.md 本文件

硬性规则

1. 目标平台 Los4：不实现 Windows/Linux/macOS 编译目标（当前平台仅作构建宿主）。
2. 零第三方依赖：仅 ISO C17 + libc；不用 OpenSSL/mbedTLS/GMP；熵来自系统调用。
3. 结构分层：crypto 原语 → ssl/ssh 协议 → apps 命令，协议层不直接依赖应用层。
4. 常量时间：密码学核心路径禁止密钥相关分支（用 paze_ct_equal 等）。
5. 编码风格：纯 C、紧凑直接、注释用中文、不做多余抽象层、单文件状态机。
6. 构建：.\build.ps1（gcc，C17），产物进 bin/，中间件留 build/。
7. 测试：build/run_tls_test.ps1 自测、build/run_openssl_interop.ps1 互操作；改动后必须跑通自测。
8. Git：中文提交信息；不主动推送，用户要求才推（parlz=gitea、origin=GitHub）；无 push 权限/网络问题时如实报告。
9. 文档：改功能同步更新 STATUS.md；不建多余 .md。

已实现功能要点

0-RTT / HRR（TLS 1.3，RFC 8446）

• 状态机（src/ssl/tls_handshake13.c）：
  • 客户端：paze_tls13_client_send_ch（抽出的 CH 发送，幂等）、client_handle_hrr（识别 HRR 魔数 → paze_tls_tr_reset_to_synthetic 合成 MessageHash → CH2 仅选定组 share）、client_rebuild_transcript、EndOfEarlyData 在 client Finished 之前用 early_write 发送
  • 服务端：server_try_psk（ticket MAC+binder 验证）、ch_ext_cb/ks_lookup_cb（supported_groups 首组 vs key_share 查找决定 HRR）、sent_hrr 分支发送 HRR（random=魔数 CF21AD74E58690691115AEDE1F40DFC9C4504D46C174A12E8B4A6F1346F84A4F）、early_read 解密早数据入 early_buf、跳过 EndOfEarlyData 后切 handshake_read
• key schedule（src/ssl/tls_keys.c）：paze_tls13_derive_early_key（PSK 关联 hash 直哈希最终 CH，client_early_traffic_secret → early_write/early_read）、paze_tls13_psk_early_secret
• 扩展（src/ssl/tls_extensions.c）：paze_tls_ext_write/parse_early_data（type 42）、key_share_client(…only_group)
• 内部字段（src/ssl/tls_internal.h）：hrr_raw/ch2/had_hrr/hrr_group/sent_hrr、early_offer/early_sent/early_accepted/early_accept、early_read/early_write
• 公共 API（include/paze/tls.h + tls_conn.c）：paze_tls_config_enable_early_data、paze_tls_early_write（握手前发早数据）、paze_tls_early_data_accepted、paze_tls_early_data_len（服务端早数据缓冲）、paze_tls_hrr_occurred
• CLI（apps/pazessl/main.c）：s_client -early -sess_in/-sess_out -key_share X25519|P-256；s_server -early -reuse
• 已知约束：0-RTT 仅在同进程会话复用（ticket_key 内存态）时可用；跨进程重启服务端会拒绝 PSK → early 记录解密失败（预期行为）
• 验证：s_server -reuse 2 -early + 两次 s_client（首次 -sess_out、二次 -sess_in -early）→ early data received + early accepted；-key_share P-256 → hrr=YES

待办（按优先级）

1. 0-RTT / HRR — TLS 1.3 数据路径（✅ 已完成 2026-08-13，详见上文要点）

2. TLS secp384r1（✅ 已完成 2026-08-13）

已实现 P-384 完整链路：

• 曲线：src/crypto/p384.c + include/paze/p384.h（Jacobian 点运算、常量时间标量乘、仿射编解码，结构对齐 p256）
• ECDSA：ecdsa.c/h 新增 paze_ecdsa_p384_sign/verify（RFC 6979 确定性 k）、paze_ecdsa_p384_priv_from_pem/der（RFC 5915,secp384r1）
• X.509：x509.c/h 支持 secp384r1 证书解析（pk_kind==ECDSA_P384）、验签（ecdsa-with-SHA384,及 SHA256 配 P-384）、paze_x509_build_spki384、签发（signer.ecdsa_d384）
• TLS：tls.h 增 PAZE_TLS_GROUP_SECP384R1(0x0018) / PAZE_TLS_SIG_ECDSA_SECP384R1_SHA384(0x0503)；tls_internal.h kex 增 P384 与 p384_priv[48]/p384_pub[97]；tls_handshake13.c kex_generate/ecdh、sign_cv/verify_cv、HRR、服务端 key_share 支持 P-384（ECDH 按 SEC1 x 坐标 48 字节）；tls_extensions.c supported_groups/signature_algorithms/key_share；TLS 1.2 ECDHE 亦支持
• CLI：s_client -key_share P-384
• 验证：P-384 曲线（n·G=∞、3G=2G+G）、ECDSA 双向（OpenSSL 验我的签名 + 我验 OpenSSL 签名）、X.509 P-384 自签名证书 OpenSSL verify=OK、TLS 端点 P-384 密钥交换(hrr=YES)+证书链/主机名验证全部通过；既有自测无回归

附带修复：

• ecdsa.c bits2int：输入短于群阶 qlen 时应右对齐而非左移（否则 P-384+SHA-256 验签错误）
• tls_conn.c 新增 paze_tls_store_peer_cert：对端证书 DER 拷贝到自有缓冲，避免 issuer/subject 指针指向被记录层复用的 app_buf 导致链验证失败（TLS 1.3 与 1.2 均在 Certificate 解析处使用）

3. SSH ProxyJump

客户端连接管理（经跳板机转发），中等。