SRO PKCS11 – SSH Agent CNG

Unificación soberana PKCS#11 + SSH-agent + Pageant + CNG/Smartcard

Un ejecutable de Windows único que unifica cuatro funciones tradicionalmente separadas:

• Módulo PKCS#11 completo (Firefox, OpenSC, ssh -I)
• Agente SSH compatible con OpenSSH/Git/VS/WSL
• Servidor Pageant compatible con PuTTY/plink/pscp
• Orquestador CNG/KSP seguro para tarjetas inteligentes

---

Tabla de contenidos

1. Filosofía
2. Arquitectura
3. Modos de ejecución
4. Instalación
5. Configuración
6. Protocolos compatibles
7. Gestión del PIN
8. Backend CNG
9. Seguridad
10. Compatibilidad
11. Exportación de claves públicas
12. Tray Icon
13. Soporte para WSL2
14. Detección de conflictos
15. Dependencias
16. Limitaciones conocidas
17. Hoja de ruta

---

Filosofía

Soberano. Sin dependencia de CRT. Todas las operaciones de memoria se realizan a través de RtlCopyMemory, RtlZeroMemory, RtlEqualMemory (FreeCRT.h). Unicode en todas partes (Win32 nativo). Sin malloc, memcpy, strlen, printf.

Seguro. Las claves privadas nunca se exportan. Ningún PIN se transmite. CNG/KSP gestiona la interfaz nativa de PIN de Windows. Aislamiento estricto servicio ↔ userland a través de pipes seguros.

Minimalista. Un solo binario. Sin DLL externas. Sin inflado del registro. Instalación simple (regsvr32 o -install).

Versátil. Soporte simultáneo de PKCS#11, SSH-agent, Pageant y WSL2 en el mismo proceso.

---

Arquitectura```

┌──────────────────────────────────────────────────────────────┐ │ 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) │ └──────────────────────────────────────────────────────────────┘

---

## Modos de ejecución

### 1. Modo PKCS#11 (automático)

Cargado por:
- `ssh -I ssh-agent.exe user@host`
- Firefox (Security Devices → Load PKCS#11 Module)
- `pkcs11-tool --module ssh-agent.exe --list-objects`

Expone las exportaciones PKCS#11 estándar:
- `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`

**Mecanismos soportados (14 en total):**
- `CKM_RSA_PKCS` (raw con padding)
- `CKM_RSA_X_509` (raw sin padding)
- `CKM_SHA1_RSA_PKCS` (legacy 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` (legacy)
- `CKM_ECDSA_SHA256` (ecdsa-sha2-nistp256/384/521)
- `CKM_ECDSA_SHA384`
- `CKM_ECDSA_SHA512`

### 2. Modo agente userland (independiente)```bash
ssh-agent.exe

• Crea el pipe \\.\pipe\openssh-ssh-agent en sesión de usuario
• Implementa el protocolo SSH-agent
• Soporte multi-cliente (max 16 conexiones simultáneas)
• Inicia automáticamente el servidor Pageant
• Inicia automáticamente el listener WSL2 (127.0.0.1:10022)
• Utiliza CNG/KSP directamente (sin servicio)
• UI PIN en la sesión actual
• Caché de PIN opcional (configurable)
• Icono de bandeja con estadísticas en tiempo real

Compatible con:

• Git for Windows (set SSH_AUTH_SOCK=\\.\pipe\openssh-ssh-agent)
• Visual Studio
• WSL (mediante npiperelay o socat)
• WSL2 (mediante TCP 127.0.0.1:10022)
• OpenSSH for Windows
• PuTTY, plink, pscp, psftp (mediante Pageant)

3. Modo stub de servicio```bash

ssh-agent.exe -install net start SROSSHAgentCNG

- Se ejecuta en sesión 0 (SYSTEM)
- Acepta conexiones en pipe global
- Crea un pipe interno por cliente (protegido por SID)
- Lanza un helper userland con `CreateProcessAsUserW`
- Reenvía los mensajes sin tocar los secretos
- Pool de helpers con timeout de 4h (reutilización automática)
- Desalojo LRU si el pool está lleno

**Ventajas:**
- UI PIN en la sesión de usuario (no en sesión 0)
- Compatible con entornos endurecidos
- Aislamiento estricto servicio ↔ crypto
- Multiplexación multi-usuario

### 4. Modo helper crypto userland```bash
ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

Iniciado automáticamente por el servicio:

• Conecta al pipe interno
• Procesa las solicitudes SSH-agent/Pageant
• Invoca NCryptSignHash (UI PIN nativa)
• Devuelve la firma al servicio
• Lanza Pageant (ventana oculta)
• Lanza listener WSL2 (127.0.0.1:10022)
• Muestra icono en la bandeja (modo SERVICE)
• Finaliza después de tiempo de espera o desconexión

---

Instalación

Registrar como módulo PKCS#11```bash

regsvr32 ssh-agent.exe

Crea las claves:
- `HKLM\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\Mozilla\Firefox\PKCS11Modules\SROSSHAgent`