Paze/PazeSSH
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 2 百科 活动
文件
main
PazeSSH/AGENT.MD
T

10 KiB
原始文件 永久链接 Blame 文件历史

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):https://git.parlz.com/Paze/PazeSSH.git，不再提交 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（✅ 基础完成）

客户端经跳板机转发连接目标主机,核心链路已实现(apps/ssh/main.c 初始版本即含):

  • -J <user@host[:port]>：connect_target() 在跳板会话上用 direct-tcpip 通道承载目标 SSH 握手(嵌套会话),主事件循环直接轮询跳板 socket。
  • config 文件 ProxyJump 字段解析(src/ssh/ssh_config.c)与匹配。
  • 补全(2026-08-14):pssh ssh -W host:port（stdio/netcat 转发,目标 TCP 隧道桥接本地 stdio）、-N（仅端口转发不执行远程命令,配 -L/-R/-D）。

已知限制:-J 接受逗号分隔的多跳语法,但多级级联跳板在同步 I/O 架构下的应用数据阶段交互不稳定,实测多跳握手可完成但握手后易卡;故当前对多跳打印警告并退化为仅第一跳的稳定单跳。单跳与 -W/-N 均已实测验证。

4. secp521r1（TLS P-521）（✅ 已完成 2026-08-14）

复用 P-384 全链路套路新增 P-521：

  • 曲线 src/crypto/p521.c + include/paze/p521.h（域 p=2^521-1,标量/仿射点 66/133 字节,常量时间标量乘;注意 P-521 非整字节对齐,标量乘须按大端位 byte=65-t/8, bit=t&7 遍历）。
  • ECDSA:ecdsa.c/h 增 paze_ecdsa_p521_sign/verify(RFC 6979,配 SHA-512)与 RFC 5915 私钥解析。
  • X.509:x509.c/h 支持 secp521r1 证书解析/验签/签发(ecdsa_p521_pub[133]、build_spki521、signer ecdsa_d521[66]、ecdsa-with-SHA512)。
  • TLS:PAZE_TLS_GROUP_SECP521R1(0x0019) / PAZE_TLS_SIG_ECDSA_SECP521R1_SHA512(0x0603),kex 增 P521,ECDH 按 SEC1 x 坐标 66 字节,supported_groups/key_share/CertificateVerify/HRR/TLS 1.2 ECDHE 均支持。
  • CLI:s_client -key_share P-521。
  • 验证:曲线(n·G=∞、3G=2G+G)、ECDSA 双向、X.509 证书 OpenSSL verify=OK、TLS 端点(密钥交换 hrr=YES+证书链/主机名验证)全部通过;既有自测无回归。

5. TLS 1.3 会话恢复持久化（✅ 已完成 2026-08-14）

session ticket key 支持持久化到文件:新增 paze_tls_config_set_session_ticket_file(设文件路径)与 paze_tls_ensure_ticket_key(首次生成时读取/写盘;PSK 验证入口 server_try_psk 亦调用以加载),实现服务端跨进程重启后会话恢复仍然有效。pazessl s_server -ticket_file <file>,端到端验证(重启后 resumed=YES)。

6. session ticket key 轮换（✅ 已完成 2026-08-14）

支持 2 代 ticket key:新增 paze_tls_config_rotate_ticket_key(当前 key 转上一代、新 key 装当前,写盘 2×32 字节);验证用所有已就绪 key 遍历匹配 MAC(不依赖 ticket 内槽位),轮换后旧 ticket 仍由上一代 key 平滑验证。pazessl s_server -rotate_ticket_key,验证:轮换后旧会话仍恢复 + 新会话跨进程恢复。

7. SSH config 兼容 + ECDSA KAT 基线（✅ 已完成 2026-08-14）

  • pssh ssh config 读取优先级:-F <file> > ~/.ssh/config(OpenSSH 兼容) > ~/.pssh/config.conf;支持 Host/HostName/Port/User/IdentityFile/ProxyJump/StrictHostKeyChecking。
  • 新增 build/run_ecdsa_selfcheck.ps1(KAT 基线):对 P-256/384/521 跑 ECDSA sign→verify 自洽,防回归。

8. 长连接保活 + fail2ban 兼容（✅ 已完成 2026-08-14）

  • pssh ssh -o ServerAliveInterval=N(默认15s):空闲发 keepalive@openssh.com global request(ssh_keepalive_send, fire-and-forget),保持空闲连接不中断;服务端回包形成保活闭环。
  • psshd 认证失败日志对齐 OpenSSH 格式(Invalid user/Failed password ... from <IP>),并记录对端 IP(ssh_session_set_peer_ip),fail2ban 默认 sshd filter 可直接匹配封禁。

9. keyboard-interactive 认证（✅ 已完成 2026-08-14）

  • 客户端:password 失败后 fallback 到 keyboard-interactive(RFC 4256,收发 INFO_REQUEST/RESPONSE,以密码响应)。
  • 服务端:方法含 keyboard-interactive 并复用用户库密码校验;psshd -kbdint 强制仅接受 ki。
  • 验证:pssh -pwd 连 psshd -kbdint 经 ki 认证成功。

10. agent 转发（-A）（✅ 已完成 2026-08-14, POSIX）

  • pssh ssh -A:开 auth-agent@openssh.com 通道,事件循环桥接本地 agent socket 与通道(ssh_agent_fd)。
  • 限制:PazeSSH 仅 POSIX 可用;Windows agent 为命名管道(无 select fd)运行时明确禁用并提示;无本地 agent 时报 cannot connect local agent。

11. 自动重连（实用版）（✅ 已完成 2026-08-14）

  • pssh ssh -o ReconnectInterval=N:断线(keepalive 发送失败判定)由外层循环自动重连并重新执行命令/重开 shell(pssh_cmd_ssh 返回 -2)。
  • 说明:依赖 ServerAliveInterval 心跳探测(建议两者搭配);恢复的是"重连+重跑",不恢复进行中 PTY 状态。
在新工单中引用 查看 Git Blame 复制永久链接