SRO PKCS11 – SSH Agent CNG

主权统一 PKCS#11 + SSH-agent + Pageant + CNG/智能卡

一个独特的 Windows 可执行文件，统一了传统上分离的四种功能：

完整的 PKCS#11 模块（Firefox、OpenSC、ssh -I）
兼容 OpenSSH/Git/VS/WSL 的 SSH 代理
兼容 PuTTY/plink/pscp 的 Pageant 服务器
用于智能卡的安全 CNG/KSP 编排器

哲学

主权。 不依赖 CRT。所有内存操作均通过 RtlCopyMemory、RtlZeroMemory、RtlEqualMemory（FreeCRT.h）。全局 Unicode（原生 Win32）。无 malloc、memcpy、strlen、printf。

安全。 私钥从不导出。PIN 从不传输。CNG/KSP 管理 Windows 原生 PIN UI。通过安全管道实现严格的服务 ↔ 用户态隔离。

极简。 单一二进制文件。无外部 DLL。无注册表臃肿。安装简单（regsvr32 或 -install）。

全能。 在同一进程中同时支持 PKCS#11、SSH-agent、Pageant 和 WSL2。

架构```

┌──────────────────────────────────────────────────────────────┐ │ Clients (Git, VS, WSL, OpenSSH, PuTTY, Firefox) │ └────────────────────────┬─────────────────────────────────────┘ │ ┌───────────────┼───────────────┬─────────────────┐ │ │ │ │ SSH-agent Pageant (WM_COPYDATA) PKCS#11 WSL2 (TCP) │ │ │ │ v v v v ┌──────────────────────────────────────────────────────────────┐ │ Service Stub (session 0, SYSTEM) │ │ - Accepte connexions sur \.\pipe\openssh-ssh-agent │ │ - Crée pipe interne par client (GUID unique) │ │ - Lance helper userland avec token interactif │ │ - Forwarde messages sans manipuler de secrets │ └────────────────────────┬─────────────────────────────────────┘ │ lancé par le service v ┌──────────────────────────────────────────────────────────────┐ │ Helper Userland (session interactive) │ │ - Connecte au pipe interne │ │ - Décode protocole SSH-agent/Pageant │ │ - Invoque CNG/KSP pour signature │ │ - UI PIN native Windows (pas de relay) │ │ - Renvoie signature au service │ │ - Fenêtre Pageant cachée pour WM_COPYDATA │ │ - Listener TCP 127.0.0.1:10022 pour WSL2 │ │ - Tray icon avec menu contextuel │ └────────────────────────┬─────────────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────┐ │ CNG/KSP Backend │ │ - NCryptSignHash avec PKCS#1/PSS padding │ │ - Enumération certificats Windows Store │ │ - Filtrage SmartCardOnly / AllowedKSP │ │ - Support RSA + ECDSA (P-256, P-384, P-521) │ │ - Support EdDSA (Ed25519, Ed448) │ │ - Support Brainpool (P256r1, P384r1, P512r1) │ │ - Cache clés + providers (4h timeout) │ └──────────────────────────────────────────────────────────────┘

## 执行模式

### 1. PKCS#11 模式（自动）

由以下方式加载：
- `ssh -I ssh-agent.exe user@host`
- Firefox（安全设备 → 加载 PKCS#11 模块）
- `pkcs11-tool --module ssh-agent.exe --list-objects`

暴露标准 PKCS#11 导出函数：
- `C_Initialize`, `C_Finalize`, `C_GetInfo`
- `C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`
- `C_GetMechanismList`, `C_GetMechanismInfo`
- `C_OpenSession`, `C_CloseSession`, `C_Login`, `C_Logout`
- `C_FindObjectsInit`, `C_FindObjects`, `C_FindObjectsFinal`
- `C_GetAttributeValue`
- `C_SignInit`, `C_Sign`
- `C_VerifyInit`, `C_Verify`
- `C_DecryptInit`, `C_Decrypt`
- `C_GenerateRandom`, `C_SeedRandom`

**支持的机制（共14个）：**
- `CKM_RSA_PKCS`（原始带填充）
- `CKM_RSA_X_509`（原始无填充）
- `CKM_SHA1_RSA_PKCS`（遗留的 ssh-rsa）
- `CKM_SHA256_RSA_PKCS`（rsa-sha2-256）
- `CKM_SHA384_RSA_PKCS`（rsa-sha2-384）
- `CKM_SHA512_RSA_PKCS`（rsa-sha2-512）
- `CKM_SHA256_RSA_PKCS_PSS`（RSA-PSS SHA-256）
- `CKM_SHA384_RSA_PKCS_PSS`（RSA-PSS SHA-384）
- `CKM_SHA512_RSA_PKCS_PSS`（RSA-PSS SHA-512）
- `CKM_ECDSA`（原始）
- `CKM_ECDSA_SHA1`（遗留）
- `CKM_ECDSA_SHA256`（ecdsa-sha2-nistp256/384/521）
- `CKM_ECDSA_SHA384`
- `CKM_ECDSA_SHA512`

### 2. 用户态代理模式（独立）```bash
ssh-agent.exe

创建用户会话中的管道 \\.\pipe\openssh-ssh-agent
实现 SSH-agent 协议
支持多客户端（最多 16 个并发连接）
自动启动 Pageant 服务器
自动启动 WSL2 监听器（127.0.0.1:10022）
直接使用 CNG/KSP（非服务模式）
在当前会话中显示 PIN 界面
可选 PIN 缓存（可配置）
系统托盘图标，实时统计信息

兼容：

Git for Windows（set SSH_AUTH_SOCK=\\.\pipe\openssh-ssh-agent）
Visual Studio
WSL（通过 npiperelay 或 socat）
WSL2（通过 TCP 127.0.0.1:10022）
OpenSSH for Windows
PuTTY、plink、pscp、psftp（通过 Pageant）

3. 服务存根模式```bash

ssh-agent.exe -install net start SROSSHAgentCNG

- Tourne en session 0 (SYSTEM) -> 在会话0（SYSTEM）中运行
- Accepte les connexions sur pipe global -> 接受全局管道上的连接
- Crée un pipe interne par client (sécurisé par SID) -> 为每个客户端创建内部管道（通过SID保护）
- Lance un helper userland avec `CreateProcessAsUserW` -> 使用 `CreateProcessAsUserW` 启动用户态助手
- Forwarde les messages sans toucher aux secrets -> 转发消息而不触及秘密
- Pool de helpers avec timeout 4h (réutilisation automatique) -> 助手池，超时4小时（自动重用）
- Éviction LRU si pool plein -> 如果池满则LRU逐出

**Avantages :**
- UI PIN dans la session utilisateur (pas en session 0) -> 用户会话中的UI PIN（而非会话0）
- Compatible environnements durcis -> 兼容加固环境
- Isolation stricte service ↔ crypto -> 服务与加密的严格隔离
- Multiplexage multi-utilisateurs -> 多用户复用

### 4. Mode helper crypto userland -> ### 4. 用户态加密助手模式```bash
ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

由服务自动启动：

连接到内部管道
处理 SSH-agent/Pageant 请求
调用 NCryptSignHash（本地 PIN 界面）
将签名返回给服务
启动 Pageant（隐藏窗口）
启动 WSL2 监听器 (127.0.0.1:10022)
显示托盘图标（服务模式）
超时或断开连接后终止

安装

注册为 PKCS#11 模块```bash

regsvr32 ssh-agent.exe

创建密钥：
- `HKLM\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\Mozilla\Firefox\PKCS11Modules\SROSSHAgent`

### 安装 Windows 服务```bash
ssh-agent.exe -install
net start SROSSHAgentCNG

配置WSL2

添加到 ~/.bashrc 或 ~/.zshrc ：```bash

--- Pont SSH Agent Windows (TCP -> Unix Socket) ---

export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"

Vérifier si le socket est déjà géré par un socat actif

if ! pgrep -u $USER socat > /dev/null || [ ! -S "$SSH_AUTH_SOCK" ]; then # Nettoyage préventif rm -f "$SSH_AUTH_SOCK"

# Lancement du bridge en arrière-plan
# Note: Utiliser 127.0.0.1 si mode 'mirrored'
# sinon l'IP du host (ex: 192.168.99.x)
socat UNIX-LISTEN:"$SSH_AUTH_SOCK",fork,unlink-early \
      TCP:127.0.0.1:10022 > /dev/null 2>&1 &

### 卸载```bash
regsvr32 /u ssh-agent.exe
ssh-agent.exe -remove

配置

HKLM\SOFTWARE\San@sro Inc\pkcs11-cng 或 HKCU\SOFTWARE\San@sro Inc\pkcs11-cng

PKCS11SSHAgent

最受欢迎