SRO PKCS11 – SSH Agent CNG

Суверенное объединение PKCS#11 + SSH-agent + Pageant + CNG/Smartcard

Один уникальный исполняемый файл Windows, объединяющий четыре традиционно разделённые функции:

• Полный модуль PKCS#11 (Firefox, OpenSC, ssh -I)
• SSH-агент, совместимый с OpenSSH/Git/VS/WSL
• Сервер Pageant, совместимый с PuTTY/plink/pscp
• Безопасный оркестратор CNG/KSP для смарт-карт

---

Содержание

1. Философия
2. Архитектура
3. Режимы выполнения
4. Установка
5. Конфигурация
6. Поддерживаемые протоколы
7. Управление PIN
8. Бэкенд CNG
9. Безопасность
10. Совместимость
11. Экспорт открытых ключей
12. Значок в трее
13. Поддержка WSL2
14. Обнаружение конфликтов
15. Зависимости
16. Известные ограничения
17. Дорожная карта

---

Философия

Суверенный. Нет зависимости от CRT. Все операции с памятью выполняются через RtlCopyMemory, RtlZeroMemory, RtlEqualMemory (FreeCRT.h). Unicode везде (родной Win32). Нет malloc, memcpy, strlen, printf.

Безопасный. Закрытые ключи никогда не экспортируются. Никакой PIN не передаётся. CNG/KSP управляет родным интерфейсом PIN Windows. Строгая изоляция службы ↔ пользовательского режима через защищённые каналы.

Минималистичный. Один единственный бинарный файл. Нет внешних 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 (Security Devices → Load PKCS#11 Module)
- `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` (raw с дополнением)
- `CKM_RSA_X_509` (raw без дополнения)
- `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` (raw)
- `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 напрямую (без службы)
• UI 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

- Работает в сеансе 0 (SYSTEM)
- Принимает соединения через глобальный канал (pipe)
- Создаёт внутренний канал для каждого клиента (защищённый SID)
- Запускает вспомогательный процесс userland с помощью `CreateProcessAsUserW`
- Пересылает сообщения, не затрагивая секреты
- Пул вспомогательных процессов с таймаутом 4 часа (автоматическое повторное использование)
- Вытеснение LRU при заполнении пула

**Преимущества:**
- ПИН-код в пользовательском сеансе (не в сеансе 0)
- Совместимость с усиленными средами
- Строгая изоляция службы ↔ криптография
- Мультиплексирование нескольких пользователей

### 4. Режим вспомогательного крипто-процесса в пользовательском пространстве```bash
ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

Lancé automatiquement par le service :

• Connecte au pipe interne
• Traite les requêtes SSH-agent/Pageant
• Invoque NCryptSignHash (UI PIN native)
• Renvoie la signature au service
• Lance Pageant (fenêtre cachée)
• Lance listener WSL2 (127.0.0.1:10022)
• Affiche tray icon (mode SERVICE)
• Se termine après timeout ou déconnexion

---

Installation